pygplates.GpmlKeyValueDictionary

class pygplates.GpmlKeyValueDictionary([key_value_mapping])

Bases: pygplates.PropertyValue

A dictionary of key/value pairs that associates string keys with integer, float or string values.

This is typically used to store attributes imported from a Shapefile so that they are available for querying and can be written back out when saving to Shapefile.

The following operations are supported:

Operation Result
len(d) number of elements in dictionary d
for k in d iterates over the keys k in dictionary d
k in d True if k is a key in dictionary d
k not in d False if k is a key in dictionary d

For example:

for key in dictionary:
    value = dictionary.get(key)

The following methods support getting, setting and removing elements in a dictionary:

__init__([key_value_mapping])

Create a dictionary containing zero or more key/value pairs.

Parameters:key_value_mapping (dict mapping each key (string) to a value (integer, float or string), or a sequence of (key, value) tuples, or None) – optional mapping of keys to values

To create an empty dictionary:

dictionary = pygplates.GpmlKeyValueDictionary()

To create a dictionary with two key/value pairs:

dictionary = pygplates.GpmlKeyValueDictionary(
    [('name', 'Test'), ('id', 23)])

To do the same thing using a dict:

dictionary = pygplates.GpmlKeyValueDictionary(
    {'name' : 'Test', 'id' : 23})

Methods

__init__([key_value_mapping]) Create a dictionary containing zero or more key/value pairs.
accept_visitor(visitor) Accept a property value visitor so that it can visit this property value.
clone() Create a duplicate of this property value (derived) instance, including a recursive copy of any nested property values that this instance might contain.
get(key, [default_value]) Returns the value of the dictionary element associated with a key.
get_geometry() Extracts the geometry if this property value contains a geometry.
get_value([time=0]) Extracts the value, of this possibly time-dependent property value, at the reconstruction time.
remove(key) Removes the dictionary element associated with a key.
set(key, value) Sets the value of the dictionary element associated with a key.
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
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
get(key[, default_value])

Returns the value of the dictionary element associated with a key.

Parameters:
  • key (string) – the key of the dictionary element
  • default_value (int or float or string or None) – the default value to return if the key does not exist in the dictionary (if not specified then it defaults to None)
Returns:

the value associated with key, otherwise default_value if key does not exist

Return type:

integer or float or string or type(default_value) or None

To test if a key is present and retrieve its value:

value = dictionary.get('key')
# Compare with None since an integer (or float) value of zero, or an empty string, evaluates to False.
if value is not None:
...
# ...or a less efficient approach...
if 'key' in dictionary:
    value = dictionary.get('key')

Return the integer value of the attribute associated with ‘key’ (default to zero if not present):

integer_value = dictionary.get('key', 0)
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_value([time=0])

Extracts the value, of this possibly time-dependent property value, at the reconstruction time.

Parameters:time (float or GeoTimeInstant) – the time to extract value (defaults to present day)
Return type:PropertyValue or None

If this property value is a time-dependent property (GpmlConstantValue, GpmlIrregularSampling or GpmlPiecewiseAggregation) then a nested property value is extracted at the reconstruction time and returned. Otherwise this property value instance is simply returned as is (since it’s not a time-dependent property value).

Returns None if this property value is a time-dependent property (GpmlConstantValue, GpmlIrregularSampling or GpmlPiecewiseAggregation) and time is outside its time range (of time samples or time windows).

Note that if this property value is a GpmlIrregularSampling instance then 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 following example demonstrates extracting an interpolated finite rotation from a total reconstruction pole at time 20Ma:

gpml_finite_rotation_20Ma = total_reconstruction_pole.get_value(20)
if gpml_finite_rotation_20Ma:
  print 'Interpolated finite rotation at 20Ma: %s' % gpml_finite_rotation_20Ma.get_finite_rotation()
remove(key)

Removes the dictionary element associated with a key.

Parameters:key (string) – the key of the dictionary element to remove

If key does not exist in the dictionary then it is ignored and nothing is done.

set(key, value)

Sets the value of the dictionary element associated with a key.

Parameters:
  • key (string) – the key of the dictionary element
  • value (integer, float or string) – the value of the dictionary element

If there is no dictionary element associated with key then a new element is created, otherwise the existing element is modified.

Previous topic

pygplates.GpmlFiniteRotation

Next topic

pygplates.GpmlOldPlatesHeader

This Page