pygplates.GpmlPiecewiseAggregation

class pygplates.GpmlPiecewiseAggregation(time_windows)

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

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

Previous topic

pygplates.GpmlIrregularSampling

Next topic

pygplates.GpmlTimeSample

This Page