pygplates.GpmlIrregularSampling

class pygplates.GpmlIrregularSampling

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. Raises: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.
get_value_type()	Returns the type of property value returned by 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, …)	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).

append(x)

Add element x to the end.

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 Returns: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_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

Return type:

the tuple (GpmlTimeSample, GpmlTimeSample), or None

Returns:

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) Return type:PropertyValue or None Raises: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().

get_value_type()

Returns the type of property value returned by get_value().

For example, it might return pygplates.GmlLineString which is a class object (not an instance).

Return type:a class object of the property type (derived from PropertyValue)

New in version 21.

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

Returns:

the time sample that is modified, or inserted into the time sequence

Return type:

GpmlTimeSample

Raises:

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).