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