pygplates.GpmlPiecewiseAggregation

class pygplates.GpmlPiecewiseAggregation

Bases: pygplates.PropertyValue

A time-dependent property consisting of a sequence of time windows each with a constant property value.

GpmlPiecewiseAggregation behaves like a regular python list (of GpmlTimeWindow 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 GpmlPiecewiseAggregation instance s is extended by sequence t
`s + t`	the concatenation of sequences s and t where either, or both, is a GpmlPiecewiseAggregation
`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:

# Replace the second and third time windows with a new time window that spans both.
piecewise_aggregation = pygplates.GpmlPiecewiseAggregation([pygplates.GpmlTimeWindow(...), ...])
...
piecewise_aggregation[1:3] = [
    pygplates.GpmlTimeWindow(
        new_property_value,
        piecewise_aggregation[2].get_begin_time(),
        piecewise_aggregation[1].get_end_time())]

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

__init__(time_windows)

Create a piecewise-constant time-dependent property from a sequence of time windows.

Parameters: time_windows (Any sequence such as a list or a tuple) – A sequence of GpmlTimeWindow elements.
Raises: RuntimeError if time window sequence is empty

Note

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

piecewise_aggregation = pygplates.GpmlPiecewiseAggregation(time_windows)

Methods

`__init__`(time_windows)	Create a piecewise-constant time-dependent property from a sequence of time windows.
`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_geometry`()	Extracts the `geometry` if this property value contains a geometry.
`get_time_window_containing_time`(time)	Return the `time window` that contains time.
`get_time_windows`()	Returns the `time windows` in a sequence that behaves as a python `list`.
`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, begin_time, end_time)	Sets the value in the specified time window.
`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_time_window_containing_time(time)

Return the time window that contains time.

Parameters: time (float or GeoTimeInstant) – the time
Return type: GpmlTimeWindow or None

Returns None if time is outside the time ranges of all time windows.

get_time_windows()

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

Return type: GpmlTimeWindowList

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

time_windows = piecewise_aggregation.get_time_windows()

# Sort windows by begin time
time_windows.sort(key = lambda tw: tw.get_begin_time())

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

# Sort windows by begin time.
piecewise_aggregation.sort(key = lambda tw: tw.get_begin_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

Returns None if time is outside the time ranges of all time windows.

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, begin_time, end_time)

Sets the value in the specified time window.

Parameters

property_value (PropertyValue) – the property value to set
begin_time (float or GeoTimeInstant) – the begin time of the time window for the new property value
end_time (float or GeoTimeInstant) – the end time of the time window for the new property value

Returns

the time window that is inserted into the time window sequence

Return type

GpmlTimeWindow

Raises

GmlTimePeriodBeginTimeLaterThanEndTimeError if begin time is later than end time

Any existing time windows that overlap the new time window (begin_time, end_time) are clipped, removed or split (depending on how they overlap) such that they no longer overlap with the new time window. The new time window is then inserted into the existing sequence such that the time windows remained ordered by time.

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

Note that begin_time can be distant past and/or end_time can be distant future

Set the property value between distant past and 10Ma:

piecewise_aggregation.set_value(property_value, pygplates.GeoTimeInstant.create_distant_past(), 10)

Alternatively you can change the value in an existing time window (if you just want to change the value within that time window and not affect other time windows):

time_window = piecewise_aggregation.get_time_window_containing_time(time)
if time_window:
    time_window.set_value(property_value)

sort(key[, reverse]): Sort the items in place (note that key is not optional and, like python 3.0, we removed cmp).