pygplates.GpmlIrregularSampling¶

class pygplates.GpmlIrregularSampling(time_samples)

Bases: pygplates.PropertyValue

A time-dependent property consisting of a sequence of time samples irregularly spaced in time.

GpmlIrregularSampling behaves like a regular python list (of GpmlTimeSample elements) in that the following operations are supported:

Operation Result
for x in s iterates over the elements x of s
x in s True if x is an item of s
x not in s False if x is an item of s
s += t the GpmlIrregularSampling instance s is extended by sequence t
s + t the concatenation of sequences s and t where either, or both, is a GpmlIrregularSampling
s[i] the item of s at index i
s[i] = x replace the item of s at index i with x
del s[i] remove the item at index i from s
s[i:j] slice of s from i to j
s[i:j] = t slice of s from i to j is replaced by the contents of the sequence t (the slice and t can be different lengths)
del s[i:j] same as s[i:j] = []
s[i:j:k] slice of s from i to j with step k
del s[i:j:k] removes the elements of s[i:j:k] from the list
s[i:j:k] = t the elements of s[i:j:k] are replaced by those of t (the slice and t must be the same length if k != 1)
len(s) length of s
s.append(x) add element x to the end of s
s.extend(t) add the elements in sequence t to the end of s
s.insert(i,x) insert element x at index i in s
s.pop([i]) removes the element at index i in s and returns it (defaults to last element)
s.remove(x) removes the first element in s that equals x (raises ValueError if not found)
s.count(x) number of occurrences of x in s
s.index(x[,i[,j]]) smallest k such that s[k] == x and i <= k < j (raises ValueError if not found)
s.reverse() reverses the items of s in place
s.sort(key[,reverse]) sort the items of s in place (note that key is not optional and, like python 3.0, we removed cmp)

For example:

# Sort samples by time.
irregular_sampling = pygplates.GpmlIrregularSampling([pygplates.GpmlTimeSample(...), ...])
...
irregular_sampling.sort(key = lambda ts: ts.get_time())


In addition to the above list-style operations there are also the following methods...

__init__(time_samples)

Create an irregularly sampled time-dependent property from a sequence of time samples.

Parameters: time_samples (Any sequence such as a list or a tuple) – A sequence of GpmlTimeSample elements. RuntimeError if time sample sequence is empty

Note

The sequence of time samples must not be empty (for technical implementation reasons), otherwise a RuntimeError exception will be thrown.

irregular_sampling = pygplates.GpmlIrregularSampling(time_samples)


Methods

 __init__(time_samples) Create an irregularly sampled time-dependent property from a sequence of time samples. accept_visitor(visitor) Accept a property value visitor so that it can visit this property value. append(x) Add element x to the end. clone() Create a duplicate of this property value (derived) instance, including a recursive copy of any nested property values that this instance might contain. count(x) Number of occurrences of x. extend(t) Add the elements in sequence t to the end. get_enabled_time_samples() Filter out the disabled time samples and return a list of enabled time samples. get_geometry() Extracts the geometry if this property value contains a geometry. get_time_samples() Returns the time samples in a sequence that behaves as a python list. get_time_samples_bounding_time(time[[, ...]) Return the two adjacent time samples that surround time. get_value([time=0]) Extracts the value at the reconstruction time. index(x[,i[,j]]) Smallest k such that the k th element equals x and i <= k < j (raises ValueError if not found). insert(i,x) Insert element x at index i. pop([i]) Removes the element at index i and returns it (defaults to last element). remove(x) Removes the first element that equals x (raises ValueError if not found). reverse() Reverses the items in place. set_value(property_value, time, ...) Sets the value at the reconstruction time. sort(key[,reverse]) Sort the items in place (note that key is not optional and, like python 3.0, we removed cmp).
accept_visitor(visitor)

Accept a property value visitor so that it can visit this property value. As part of the visitor pattern, this enables the visitor instance to discover the derived class type of this property. Note that there is no common interface shared by all property value types, hence the visitor pattern provides one way to find out which type of property value is being visited.

Parameters: visitor (PropertyValueVisitor) – the visitor instance visiting this property value
append(x)

Add element x to the end.

clone()

Create a duplicate of this property value (derived) instance, including a recursive copy of any nested property values that this instance might contain.

Return type: PropertyValue
count(x)

Number of occurrences of x.

extend(t)

Add the elements in sequence t to the end.

get_enabled_time_samples()

Filter out the disabled time samples and return a list of enabled time samples.

Return type: list the list of enabled time samples (if any)

Returns an empty list if all time samples are disabled.

This method essentially does the following:

return filter(lambda ts: ts.is_enabled(), get_time_samples())


NOTE: Unlike get_time_samples(), the returned sequence is a new list object and hence modifications to the list such as list.sort (as opposed to modifications to the list elements) will not modify the internal state of the GpmlIrregularSampling instance (it only modifies the returned list).

get_geometry()

Extracts the geometry if this property value contains a geometry.

Return type: GeometryOnSphere or None

This function searches for a geometry in the following standard geometry property value types:

If this property value does not contain a geometry then None is returned.

Time-dependent geometry properties are not yet supported, so the only time-dependent property value wrapper currently supported by this function is GpmlConstantValue.

To extract geometry from a specific feature property:

property_value = feature.get_value(pygplates.PropertyName.gpml_pole_position)
if property_value:
geometry = property_value.get_geometry()


...however Feature.get_geometry() provides an easier way to extract geometry from a feature with:

geometry = feature.get_geometry(pygplates.PropertyName.gpml_pole_position)


To extract all geometries from a feature (regardless of which properties they came from):

all_geometries = []
for property in feature:
property_value = property.get_value()
if property_value:
geometry = property_value.get_geometry()
if geometry:
all_geometries.append(geometry)


...however again Feature.get_geometry() does this more easily with:

all_geometries = feature.get_geometry(lambda property: True, pygplates.PropertyReturn.all)

get_time_samples()

Returns the time samples in a sequence that behaves as a python list.

Return type: GpmlTimeSampleList

Modifying the returned sequence will modify the internal state of the GpmlIrregularSampling instance:

time_samples = irregular_sampling.get_time_samples()

# Sort samples by time.
time_samples.sort(key = lambda ts: ts.get_time())


The same effect can be achieved by working directly on the GpmlIrregularSampling instance:

# Sort samples by time.
irregular_sampling.sort(key = lambda ts: ts.get_time())

get_time_samples_bounding_time(time[, include_disabled_samples=False])

Return the two adjacent time samples that surround time.

Parameters: time (float or GeoTimeInstant) – the time include_disabled_samples (bool) – if True then disabled time samples are included in the search the tuple (GpmlTimeSample, GpmlTimeSample), or None the two time samples surrounding time, or None

Returns None if time is outside the range of times (later than the most recent time sample or earlier than the least recent time sample).

Note: The returned time samples are ordered forward in time (the first sample is further in the past than the second sample). This is opposite the typical ordering of time samples in a GpmlIrregularSampling (which are progressively further back in time) but is similar to GpmlTimeWindow (where its begin time is further in the past than its end time).

get_value([time=0])

Extracts the value at the reconstruction time.

Parameters: time (float or GeoTimeInstant) – the time to extract value (defaults to present day) PropertyValue or None InterpolationError if time is distant past or distant future

Returns None if time is outside the time range of the time samples.

Note that the extracted property value is interpolated (at reconstruction time) if property value can be interpolated (currently only GpmlFiniteRotation and XsDouble), otherwise None is returned. The function FiniteRotation.interpolate() is used internally when the extracted property value type is GpmlFiniteRotation.

NOTE: modifying the returned property value does not modify the sequence of time samples (because the returned property value is a new interpolated time sample that does not exist in the sequence). Instead set_value() can be used to modify the sequence for a specific time value.

This method overrides PropertyValue.get_value().

index(x[, i[, j]])

Smallest k such that the k th element equals x and i <= k < j (raises ValueError if not found).

insert(i, x)

Insert element x at index i.

pop([i])

Removes the element at index i and returns it (defaults to last element).

remove(x)

Removes the first element that equals x (raises ValueError if not found).

reverse()

Reverses the items in place.

set_value(property_value, time[, description][, is_enabled=True])

Sets the value at the reconstruction time.

Parameters: property_value (PropertyValue) – the property value to set time (float or GeoTimeInstant) – the time to set the value description (string or None) – description of the time sample is_enabled (bool or None) – whether time sample is enabled the time sample that is modified, or inserted into the time sequence GpmlTimeSample ValueError if time is distant past or distant future

If an existing time sample matches time then it will be modified, otherwise a new time sample will be inserted into the sequence such that the time samples remain ordered by time.

This method assumes the precondition that the time samples are ordered by time from most recent to least recent.

Note that time can be outside the time range of existing time samples.

sort(key[, reverse])

Sort the items in place (note that key is not optional and, like python 3.0, we removed cmp).

Previous topic

pygplates.GpmlConstantValue

Next topic

pygplates.GpmlPiecewiseAggregation