resqpy.property.GridPropertyCollection

class resqpy.property.GridPropertyCollection(grid=None, property_set_root=None, realization=None)

Bases: PropertyCollection

Class for RESQML Property collection for an IJK Grid, inheriting from PropertyCollection.

Commonly Used Methods:

__init__([grid, property_set_root, realization])

Creates a new property collection related to an IJK grid.

Inherited from PropertyCollection

__init__([grid, property_set_root, realization])

Creates a new property collection related to an IJK grid.

parts()

Return list of parts in this collection.

uuids()

Return list of uuids in this collection.

selective_parts_list([realization, support, ...])

Returns a list of parts filtered by those arguments which are not None.

singleton([realization, support, ...])

Returns a single part selected by those arguments which are not None.

single_array_ref([realization, support, ...])

Returns the array of data for a single part selected by those arguments which are not None.

number_of_parts()

Returns the number of parts (properties) in this collection.

part_str(part[, include_citation_title])

Returns a human-readable string identifying the part.

realization_for_part(part)

Returns realization number (within ensemble) that the property relates to.

uuid_for_part(part)

Returns UUID object for the property part.

continuous_for_part(part)

Returns True if the property is continuous (including points); False if it is discrete (or categorical).

indexable_for_part(part)

Returns the text of the IndexableElement for the property part; usually 'cells' for grid properties.

property_kind_for_part(part)

Returns the resqml property kind for the property part.

facet_type_for_part(part)

If relevant, returns the resqml Facet Facet for the property part, eg.

facet_for_part(part)

If relevant, returns the resqml Facet Value for the property part, eg.

citation_title_for_part(part)

Returns the citation title for the property part.

time_index_for_part(part)

If the property has an associated time series (is not static), returns the time index within the time series.

minimum_value_for_part(part)

Returns the minimum value for the property part, as stored in the xml.

maximum_value_for_part(part)

Returns the maximum value for the property part, as stored in the xml.

uom_for_part(part)

Returns the resqml units of measure for the property part.

part_is_categorical(part)

Returns True if the property is categorical (not conintuous and has an associated string lookup).

has_multiple_realizations()

Returns the has multiple realizations flag based on whether properties belong to more than one realization.

cached_part_array_ref(part[, dtype, masked, ...])

Returns a numpy array containing the data for the property part; the array is cached in this collection.

realizations_array_ref([use_32_bit, ...])

Returns a +1D array of all parts with first axis being over realizations.

time_series_array_ref([use_32_bit, ...])

Returns a +1D array of all parts with first axis being over time indices.

add_cached_array_to_imported_list(...[, ...])

Caches array and adds to the list of imported properties (but not to the collection dict).

write_hdf5_for_imported_list([file_name, ...])

Create or append to an hdf5 file, writing datasets for the imported arrays.

create_xml_for_imported_list_and_add_parts_to_model([...])

Add imported or generated grid property arrays as parts in parent model, creating xml.

basic_static_property_parts([realization, ...])

Returns five parts: net to gross ratio, porosity, permeability rock I, J & K; each returned part may be None.

basic_static_property_uuids([realization, ...])

Returns five uuids: net to gross ratio, porosity, permeability rock I, J & K; each returned uuid may be None.

Methods:

set_grid(grid[, grid_root, modify_parts])

Sets the supporting representation object for the collection to be the given grid.

h5_slice_for_box(part, box)

Returns a subset of the array for part, without loading the whole array (unless already cached).

extend_imported_list_copying_properties_from_other_grid_collection(other)

Extends this collection's imported list with properties from other collection.

import_nexus_property_to_cache(file_name, ...)

Reads a property array from an ascii (or pure binary) file, caches and adds to imported list.

import_vdb_static_property_to_cache(vdbase, ...)

Reads a vdb static property array, caches and adds to imported list (but not collection dict).

import_vdb_recurrent_property_to_cache(...)

Reads a vdb recurrent property array for one timestep, caches and adds to imported list.

import_ab_property_to_cache(file_name, keyword)

Reads a property array from a pure binary file, caches and adds to imported list (but not collection dict).

decoarsen_imported_list([decoarsen_array, ...])

Decoarsen imported Nexus properties if needed.

write_nexus_property(part, file_name[, ...])

Writes the property array to a file in a format suitable for including as nexus input.

write_nexus_property_generating_filename(...)

Writes the property array to a file using a filename generated from the citation title etc.

write_nexus_collection(directory[, ...])

Writes a set of files, one for each part in the collection.

Inherited from PropertyCollection

set_support([support_uuid, support, model, ...])

Sets the supporting object associated with this collection if not done so at initialisation.

supporting_shape([indexable_element, direction])

Return the shape of the supporting representation with respect to the given indexable element

populate_from_property_set(property_set_root)

Populates this (newly created) collection based on xml members of property set.

set_realization(realization)

Sets the model realization number (within an ensemble) for this collection.

add_part_to_dict(part[, continuous, ...])

Add the named part to the dictionary for this collection.

add_parts_list_to_dict(parts_list)

Add all the parts named in the parts list to the dictionary for this collection.

remove_part_from_dict(part)

Remove the named part from the dictionary for this collection.

remove_parts_list_from_dict(parts_list)

Remove all the parts named in the parts list from the dictionary for this collection.

inherit_imported_list_from_other_collection(other)

Extends this collection's imported list with items from other's imported list.

inherit_parts_from_other_collection(other[, ...])

Adds all the parts in the other PropertyCollection to this one.

add_to_imported_list_sampling_other_collection(...)

Makes cut down copies of parts from other collection, using indices, and adds to imported list.

inherit_parts_selectively_from_other_collection(other)

Adds those parts from the other PropertyCollection which match all arguments that are not None.

inherit_similar_parts_for_time_series_from_other_collection(...)

Adds the example part from other collection and any other parts for the same property at different times.

inherit_similar_parts_for_facets_from_other_collection(...)

Adds the example part from other collection and any other parts for same property with different facets.

inherit_similar_parts_for_realizations_from_other_collection(...)

Add the example part from other collection and any other parts for same property with different realizations.

number_of_imports()

Returns the number of property arrays in the imported list for this collection.

part_in_collection(part)

Returns True if named part is member of this collection; otherwise False.

element_for_part(part, index)

Returns a particular element by index from the tuple of metadata for the specified part.

unique_element_list(index[, sort_list])

Returns an optionally sorted list of unique values (excluding None) of an element identified by index.

part_filename(part)

Returns a string which can be used as the starting point of a filename relating to part.

realization_list([sort_list])

Returns a list of unique realization numbers present in the collection.

support_uuid_for_part(part)

Returns supporting representation object's uuid that the property relates to.

grid_for_part(part)

Returns grid object that the property relates to.

node_for_part(part)

Returns the xml node for the property part.

extra_metadata_for_part(part)

Returns the extra_metadata dictionary for the part.

null_value_for_part(part)

Returns the null value for the (discrete) property part; np.NaN for continuous parts.

points_for_part(part)

Returns True if the property is a points property; False otherwise.

all_continuous()

Returns True if all the parts are for continuous (real) properties (includes points).

all_discrete()

Returns True if all the parts are for discrete or categorical (integer) properties.

count_for_part(part)

Returns the Count value for the property part; usually 1.

all_count_one()

Returns True if the low level Count value is 1 for all the parts in the collection.

unique_indexable_element_list([sort_list])

Returns a list of unique values for the IndexableElement of the property parts in the collection.

property_kind_list([sort_list])

Returns a list of unique property kinds found amongst the parts of the collection.

local_property_kind_uuid(part)

Returns the uuid of the bespoke (local) property kind for this part, or None for a standard property kind.

facet_type_list([sort_list])

Returns a list of unique facet types found amongst the parts of the collection.

facet_list([sort_list])

Returns a list of unique facet values found amongst the parts of the collection.

title_for_part(part)

Synonymous with citation_title_for_part().

titles()

Returns a list of citation titles for the parts in the collection.

time_series_uuid_for_part(part)

If the property has an associated time series (is not static), returns the uuid for the time series.

time_series_uuid_list([sort_list])

Returns a list of unique time series uuids found amongst the parts of the collection.

time_index_list([sort_list])

Returns a list of unique time indices found amongst the parts of the collection.

patch_min_max_for_part(part[, minimum, ...])

Updates the minimum and/ox maximum values stored in the metadata, optionally updating xml tree too.

uom_list([sort_list])

Returns a list of unique units of measure found amongst the parts of the collection.

string_lookup_uuid_for_part(part)

If the property has an associated string lookup (is categorical), return the uuid.

string_lookup_for_part(part)

Returns a StringLookup object for the part, if it has a string lookup uuid, otherwise None.

string_lookup_uuid_list([sort_list])

Returns a list of unique string lookup uuids found amongst the parts of the collection.

constant_value_for_part(part)

Returns the value (float or int) of a constant array part, or None for an hdf5 array.

override_min_max(part, min_value, max_value)

Sets the minimum and maximum values in the metadata for the part.

establish_time_set_kind()

Re-evaulates the time set kind attribute.

time_set_kind()

Returns the time set kind attribute.

establish_has_single_property_kind()

Re-evaluates the has single property kind attribute.

has_single_property_kind()

Return the has single property kind flag depending on whether all properties are of the same kind.

establish_has_single_indexable_element()

Re-evaluate the has single indexable element attribute.

has_single_indexable_element()

Returns the has single indexable element flag depending on whether all properties have the same.

establish_has_multiple_realizations()

Re-evaluates the has multiple realizations attribute.

establish_has_single_uom()

Re-evaluates the has single uom attribute depending on whether all properties have the same units of measure.

has_single_uom()

Returns the has single uom flag depending on whether all properties have the same units of measure.

assign_realization_numbers()

Assigns a distinct realization number to each property, after checking for compatibility.

masked_array(simple_array[, ...])

Returns a masked version of simple_array, using inactive mask associated with support for this property collection.

h5_key_pair_for_part(part)

Return hdf5 key pair (ext uuid, internal path) for the part.

h5_slice(part, slice_tuple)

Returns a subset of the array for part, without loading the whole array.

h5_overwrite_slice(part, slice_tuple, ...[, ...])

Overwrites a subset of the array for part, in the hdf5 file.

shape_and_type_of_part(part)

Returns shape tuple and element type of cached or hdf5 array for part.

facets_array_ref([use_32_bit, indexable_element])

Returns a +1D array of all parts with first axis being over facet values; Use facet_list() for lookup.

combobulated_face_array(resqml_a)

Returns a logically ordered copy of RESQML faces-per-cell property array resqml_a.

discombobulated_face_array(resqpy_a)

Return logical face property array a, re-ordered and reshaped regarding the six facial directions.

cached_normalized_part_array_ref(part[, ...])

DEPRECATED: replaced with normalized_part_array() method.

normalized_part_array(part[, masked, ...])

Return data normalised to between 0 and 1, along with min and max value.

uncache_part_array(part)

Removes the cached copy of the array of data for the named property part.

remove_cached_imported_arrays()

Removes any cached arrays that are mentioned in imported list.

remove_cached_part_arrays()

Removes any cached arrays for parts of the collection.

remove_all_cached_arrays()

Removes any cached arrays for parts or mentioned in imported list.

write_hdf5_for_part(part[, file_name, mode])

Create or append to an hdf5 file, writing dataset for the specified part.

create_xml(ext_uuid, property_array, title, ...)

Create a property xml node for a single property related to a given supporting representation node.

create_property_set_xml(title[, ps_uuid, ...])

Creates an xml node for a property set to represent this collection of properties.

basic_static_property_parts_dict([...])

Same as basic_static_property_parts() method but returning a dictionary with 5 items.

basic_static_property_uuids_dict([...])

Same as basic_static_property_uuids() method but returning a dictionary with 5 items.


__init__(grid=None, property_set_root=None, realization=None)[source]

Creates a new property collection related to an IJK grid.

Parameters
  • grid (grid.Grid object, optional) – must be present unless creating a completely blank, empty collection

  • property_set_root (optional) – if present, the collection is populated with the properties defined in the xml tree of the property set; grid must not be None when using this argument

  • realization (integer, optional) – if present, the single realisation (within an ensemble) that this collection is for; if None, then the collection is either covering a whole ensemble (individual properties can each be flagged with a realisation number), or is for properties that do not have multiple realizations

Returns

the new GridPropertyCollection object

Note

usually a grid should be passed, however a completely blank collection may be created prior to using collection inheritance methods to populate from another collection, in which case the grid can be lazily left as None here

add_cached_array_to_imported_list(cached_array, source_info, keyword, discrete=False, uom=None, time_index=None, null_value=None, property_kind=None, local_property_kind_uuid=None, facet_type=None, facet=None, realization=None, indexable_element=None, count=1, const_value=None, points=False, time_series_uuid=None)

Caches array and adds to the list of imported properties (but not to the collection dict).

Parameters
  • cached_array – a numpy array to be added to the imported list for this collection (prior to being added as a part); for a constant array set cached_array to None (and use const_value)

  • source_info (string) – typically the name of a file from which the array has been read but can be any information regarding the source of the data

  • keyword (string) – this will be used as the citation title when a part is generated for the array

  • discrete (boolean, optional, default False) – if True, the array should contain integer (or boolean) data; if False, float

  • uom (string, optional, default None) – the resqml units of measure for the data

  • time_index (integer, optional, default None) – if not None, the time index to be used when creating a part for the array

  • null_value (int or float, optional, default None) – if present, this is used in the metadata to indicate that this value is to be interpreted as a null value wherever it appears in the data

  • property_kind (string) – resqml property kind, or None

  • local_property_kind_uuid (uuid.UUID or string) – uuid of local property kind, or None

  • facet_type (string) – resqml facet type, or None

  • facet (string) – resqml facet, or None

  • realization (int) – realization number, or None

  • indexable_element (string, optional) – the indexable element in the supporting representation

  • count (int, default 1) – the number of values per indexable element; if greater than one then this must be the fastest cycling axis in the cached array, ie last index

  • const_value (int, float or bool, optional) – the value with which a constant array is filled; required if cached_array is None, must be None otherwise

  • points (bool, default False) – if True, this is a points property with an extra dimension of extent 3

  • time_series_uuid (UUID, optional) – should be provided if time_index is not None, though can alternatively be provided when writing hdf5 and creating xml for the imported list

Returns

uuid of nascent property object

Note

the process of importing property arrays follows these steps: 1. read (or generate) array of data into a numpy array in memory (cache) 2. add to the imported list using this function (which also takes takes note of some metadata) 3. write imported list arrays to hdf5 file 4. create resqml xml nodes for imported list arrays and add as parts to model 5. include newly added parts in collection

add_part_to_dict(part, continuous=None, realization=None, trust_uom=True)

Add the named part to the dictionary for this collection.

Parameters
  • part (string) – the name of a part (which exists in the support’s parent model) to be added to this collection

  • continuous (boolean, optional) – whether the property is of a continuous (real) kind; if not None, is checked against the property’s type and an assertion error is raised if there is a mismatch; should be None or True for Points properties

  • realization (integer, optional) – if present, must match this collection’s realization number if that is not None; if this argument is None then the part is assigned the realization number associated with this collection as a whole; if the xml for the part includes a realization index then that overrides these other sources to become the realization number

  • trust_uom (boolean, default True) – if True, the uom stored in the part’s xml is used as the part’s uom in this collection; if False and the uom in the xml is an empty string or ‘Euc’, then the part’s uom in this collection is set to a guess based on the property kind and min & max values; note that this guessed value is not used to overwrite the value in the xml

add_parts_list_to_dict(parts_list)

Add all the parts named in the parts list to the dictionary for this collection.

argument:

parts_list: a list of strings, each being the name of a part in the support’s parent model

Note

the add_part_to_dict() function is called for each part in the list

add_to_imported_list_sampling_other_collection(other, flattened_indices)

Makes cut down copies of parts from other collection, using indices, and adds to imported list.

Parameters
  • other (PropertyCollection) – the source collection whose arrays will be sampled

  • flattened_indices (1D numpy int array) – the indices (in flattened space) of the elements to be copied

Notes

the values in flattened_indices refer to the source (other) array elements, after flattening; the size of flatted_indices must match the size of the target (self) supporting shape; where different indexable elements are at play, with different implicit sizes, make selective copies of other and call this method once for each group of differently sized properties; for very large collections it might also be necessary to divide the work into smaller groups to reduce memory usage; this method does not write to hdf5 nor create xml – use the usual methods for further processing of the imported list

all_continuous()

Returns True if all the parts are for continuous (real) properties (includes points).

all_count_one()

Returns True if the low level Count value is 1 for all the parts in the collection.

all_discrete()

Returns True if all the parts are for discrete or categorical (integer) properties.

assign_realization_numbers()

Assigns a distinct realization number to each property, after checking for compatibility.

Note

this method does not modify realization information in any established xml; it is intended primarily as a convenience to allow realization based processing of any collection of compatible properties

basic_static_property_parts(realization=None, share_perm_parts=False, perm_k_mode=None, perm_k_ratio=1.0)

Returns five parts: net to gross ratio, porosity, permeability rock I, J & K; each returned part may be None.

Parameters
  • realization – (int, optional): if present, only properties with the given realization are considered; if None, all properties in the collection are considered

  • share_perm_parts (boolean, default False) – if True, the permeability I part will also be returned for J and/or K if no other properties are found for those directions; if False, None will be returned for such parts

  • perm_k_mode (string, optional) – if present, indicates what action to take when no K direction permeability is found; valid values are: ‘none’: same as None, perm K part return value will be None ‘shared’: if share_perm_parts is True, then perm I value will be used for perm K, else same as None ‘ratio’: multiply IJ permeability by the perm_k_ratio argument ‘ntg’: multiply IJ permeability by ntg and by perm_k_ratio ‘ntg squared’: multiply IJ permeability by square of ntg and by perm_k_ratio

  • perm_k_ratio (float, default 1.0) – a Kv:Kh ratio, typically in the range zero to one, applied if generating a K permeability array (perm_k_mode is ‘ratio’, ‘ntg’ or ‘ntg squared’ and no existing K permeability found); ignored otherwise

Returns

tuple of 5 strings being part names for – net to gross ratio, porosity, perm i, perm j, perm k (respectively); any of the returned elements may be None if no appropriate property was identified

Note

if generating a K permeability array, the data is appended to the hdf5 file and the xml is created, however the epc re-write must be carried out by the calling code

basic_static_property_parts_dict(realization=None, share_perm_parts=False, perm_k_mode=None, perm_k_ratio=1.0)

Same as basic_static_property_parts() method but returning a dictionary with 5 items.

Note

returned dictionary contains following keys: ‘NTG’, ‘PORO’, ‘PERMI’, ‘PERMJ’, ‘PERMK’

basic_static_property_uuids(realization=None, share_perm_parts=False, perm_k_mode=None, perm_k_ratio=1.0)

Returns five uuids: net to gross ratio, porosity, permeability rock I, J & K; each returned uuid may be None.

Note

see basic_static_property_parts() method for argument documentation

basic_static_property_uuids_dict(realization=None, share_perm_parts=False, perm_k_mode=None, perm_k_ratio=1.0)

Same as basic_static_property_uuids() method but returning a dictionary with 5 items.

Note

returned dictionary contains following keys: ‘NTG’, ‘PORO’, ‘PERMI’, ‘PERMJ’, ‘PERMK’

cached_normalized_part_array_ref(part, masked=False, use_logarithm=False, discrete_cycle=None, trust_min_max=False)

DEPRECATED: replaced with normalized_part_array() method.

cached_part_array_ref(part, dtype=None, masked=False, exclude_null=False)

Returns a numpy array containing the data for the property part; the array is cached in this collection.

Parameters
  • part (string) – the part name for which the array reference is required

  • dtype (optional, default None) – the element data type of the array to be accessed, eg ‘float’ or ‘int’; if None (recommended), the dtype of the returned numpy array matches that in the hdf5 dataset

  • masked (boolean, default False) – if True, a masked array is returned instead of a simple numpy array; the mask is set to the inactive array attribute of the support object if present

  • exclude_null (boolean, default False) – if True, and masked is also True, then elements of the array holding the null value will also be masked out

Returns

reference to a cached numpy array containing the actual property data; multiple calls will return the same cached array so calling code should copy if duplication is needed

Notes

this function is the usual way to get at the actual property array; at present, the funtion only works if the entire array is stored as a single patch in the hdf5 file (resqml allows multiple patches per array); the masked functionality can be used to apply a common mask, stored in the supporting representation object with the attribute name ‘inactive’, to multiple properties (this will only work if the indexable element is set to the typical value for the class of supporting representation, eg. ‘cells’ for grid objects); if exclude_null is set True then null value elements will also be masked out (as long as masked is True); however, it is recommended simply to use np.NaN values in floating point property arrays if the commonality is not needed

citation_title_for_part(part)

Returns the citation title for the property part.

Parameters

part (string) – the part name for which the citation title is required

Returns

citation title (string) for this part

Note

for simulation grid properties, the citation title is often a property keyword specific to a simulator

combobulated_face_array(resqml_a)

Returns a logically ordered copy of RESQML faces-per-cell property array resqml_a.

argument:

resqml_a (numpy array of shape (…, 6): a RESQML property array with indexable element faces per cell

Returns

numpy array of shape (…, 3, 2) where the 3 covers K,J,I and the 2 the -/+ face polarities being a resqpy logically

arranged copy of resqml_a

Notes

this method is for properties of IJK grids only; RESQML documentation is not entirely clear about the required ordering of -I, +I, -J, +J faces; current implementation assumes count = 1 for the property; does not currently support points properties

constant_value_for_part(part)

Returns the value (float or int) of a constant array part, or None for an hdf5 array.

Note

a constant array can optionally be expanded and written to the hdf5, in which case it will not have a constant value assigned when the dataset is read from file

continuous_for_part(part)

Returns True if the property is continuous (including points); False if it is discrete (or categorical).

Parameters

part (string) – the part name for which the continuous versus discrete flag is required

Returns

True if the part is representing a continuous (or points) property, ie. the array elements are real numbers (float); False if the part is representing a discrete property or a categorical property, ie the array elements are integers (or boolean)

Note

RESQML differentiates between discrete and categorical properties; discrete properties are unbounded integers where the values have numerical significance (eg. could be added together), whilst categorical properties have an associated dictionary mapping from a finite set of integer key values onto strings (eg. {1: ‘background’, 2: ‘channel sand’, 3: ‘mud drape’}); however, this module treats categorical properties as a special case of discrete properties

count_for_part(part)

Returns the Count value for the property part; usually 1.

Parameters

part (string) – the part name for which the count is required

Returns

integer reflecting the count attribute for the part (usually one); if greater than one, the array has an extra axis, cycling fastest, having this extent

Note

this mechanism allows a vector of values to be associated with a single indexable element in the supporting representation

create_property_set_xml(title, ps_uuid=None, originator=None, add_as_part=True, add_relationships=True)

Creates an xml node for a property set to represent this collection of properties.

Parameters
  • title (string) – to be used as citation title

  • ps_uuid (string, optional) – if present, used as the uuid for the property set, otherwise a new uuid is generated

  • originator (string, optional) – if present, used as the citation creator (otherwise login name is used)

  • add_as_part (boolean, default True) – if True, the property set is added to the model as a part

  • add_relationships (boolean, default True) – if True, the relationships to the member properties are added

Note

xml for individual properties should exist before calling this method

create_xml(ext_uuid, property_array, title, property_kind, support_uuid=None, p_uuid=None, facet_type=None, facet=None, discrete=False, time_series_uuid=None, time_index=None, uom=None, null_value=None, originator=None, source=None, add_as_part=True, add_relationships=True, add_min_max=True, min_value=None, max_value=None, realization=None, string_lookup_uuid=None, property_kind_uuid=None, find_local_property_kinds=True, indexable_element=None, count=1, points=False, extra_metadata={}, const_value=None, expand_const_arrays=False)

Create a property xml node for a single property related to a given supporting representation node.

Parameters
  • ext_uuid (uuid.UUID) – the uuid of the hdf5 external part

  • property_array (numpy array) – the actual property array (used to populate xml min & max values); may be None if min_value and max_value are passed or add_min_max is False

  • title (string) – used for the citation Title text for the property; often set to a simulator keyword for grid properties

  • property_kind (string) – the resqml property kind of the property; in the case of a bespoke (local) property kind, this is used as the title in the local property kind reference and the property_kind_uuid argument must also be passed or find_local_property_kinds set True

  • support_uuid (uuid.UUID, optional) – if None, the support for the collection is used

  • p_uuid (uuid.UUID, optional) – if None, a new uuid is generated for the property; otherwise this uuid is used

  • facet_type (string, optional) – if present, a resqml facet type whose value is supplied in the facet argument

  • facet (string, optional) – required if facet_type is supplied; the value of the facet

  • discrete (boolean, default False) – if True, a discrete or categorical property node is created (depending on whether string_lookup_uuid is None or present); if False (default), a continuous property node is created

  • time_series_uuid (uuid.UUID, optional) – if present, the uuid of the time series that this (recurrent) property relates to

  • time_index (int, optional) – if time_series_uuid is not None, this argument is required and provides the time index into the time series for this property array

  • uom (string) – the resqml unit of measure for the property (only used for continuous properties)

  • null_value (optional) – the value that is to be interpreted as null if it appears in the property array

  • originator (string, optional) – the name of the human being who created the property object; default is to use the login name

  • source (string, optional) – if present, an extra metadata node is added as a child to the property node, with this string indicating the source of the property data

  • add_as_part (boolean, default True) – if True, the newly created xml node is added as a part in the model

  • add_relationships (boolean, default True) – if True, relationship xml parts are created relating the new property part to: the support, the hdf5 external part; and the time series part (if applicable)

  • add_min_max (boolean, default True) – if True, min and max values are included as children in the property node

  • min_value (optional) – if present and add_min_max is True, this is used as the minimum value (otherwise it is calculated from the property array)

  • max_value (optional) – if present and add_min_max is True, this is used as the maximum value (otherwise it is calculated from the property array)

  • realization (int, optional) – if present, is used as the realization number in the property node; if None, no realization child is created

  • string_lookup_uuid (optional) – if present, and discrete is True, a categorical property node is created which refers to this string table lookup

  • property_kind_uuid (optional) – if present, the property kind is a local property kind; must be None for a standard property kind

  • find_local_property_kinds (boolean, default True) – if True and property_kind is not in standard supported property kind list and property_kind_uuid is None, the citation titles of PropertyKind objects in the model are compared with property_kind and if a match is found, that local property kind is used; if no match is found, a new local property kind is created; the same logic is applied if the specified property kind is abstract (‘continuous’, ‘discrete’, ‘categorical’) in which case the property title is also used as the property kind title

  • indexable_element (string, optional) – if present, is used as the indexable element in the property node; if None, ‘cells’ are used for grid properties and ‘nodes’ for wellbore frame properties

  • count (int, default 1) – the number of values per indexable element; if greater than one then this axis must cycle fastest in the array, ie. be the last index

  • points (bool, default False) – if True, this is a points property

  • extra_metadata (dictionary, optional) – if present, adds extra metadata in the xml

  • const_value (float or int, optional) – if present, create xml for a constant array filled with this value

  • expand_const_arrays (boolean, default False) – if True, the hdf5 write must also have been called with the same argument and the xml will treat a constant array as a normal array

Returns

the newly created property xml node

Notes

this function doesn’t write the actual array data to the hdf5 file: that should be done before calling this function; this code (and elsewhere) only supports at most one facet per property, though the RESQML standard allows for multiple facets; RESQML does not allow facets for points properties; if the xml has not been created for the support object, then xml will not be created for relationships between the properties and the supporting representation

create_xml_for_imported_list_and_add_parts_to_model(ext_uuid=None, support_uuid=None, time_series_uuid=None, selected_time_indices_list=None, string_lookup_uuid=None, property_kind_uuid=None, find_local_property_kinds=True, expand_const_arrays=False, extra_metadata={})

Add imported or generated grid property arrays as parts in parent model, creating xml.

hdf5 should already have been written.

Parameters
  • ext_uuid – uuid for the hdf5 external part, which must be known to the model’s hdf5 dictionary

  • support_uuid (optional) – the uuid of the supporting representation that the imported properties relate to

  • time_series_uuid (optional) – the uuid of the full or reduced time series for which any recurrent properties’ timestep numbers can be used as a time index; in the case of a reduced series, the selected_time_indices_list argument must be passed and the properties timestep numbers are found in the list with the position yielding the time index for the reduced list; time_series_uuid should be present if there are any recurrent properties in the imported list

  • selected_time_indices_list (list of int, optional) – if time_series_uuid is for a reduced time series then this argument must be present and its length must match the number of timestamps in the reduced series; the values in the list are indices in the full time series

  • string_lookup_uuid (optional) – if present, the uuid of the string table lookup which any non-continuous properties relate to (ie. they are all taken to be categorical)

  • property_kind_uuid (optional) – if present, the uuid of the bespoke (local) property kind for all the property arrays in the imported list (except those with an individual local property kind uuid)

  • find_local_property_kinds (boolean, default True) – if True, local property kind uuids need not be provided as long as the property kinds are set to match the titles of the appropriate local property kind objects

  • expand_const_arrays (boolean, default False) – if True, the hdf5 write must also have been called with the same argument and the xml will treat the constant arrays as normal arrays

  • extra_metadata (optional) – if present, a dictionary of extra metadata to be added for the part

Returns

list of uuid.UUID, being the uuids of the newly added property parts

Notes

the imported list should have been built up, and associated hdf5 arrays written, before calling this method; the imported list is cleared as a deliberate side-effect of this method (so a new set of imports can be started hereafter); discrete and categorical properties cannot be mixed in the same import list - process as separate lists; all categorical properties in the import list must refer to the same string table lookup; when importing categorical properties, establish the xml for the string table lookup before calling this method; if importing properties of a bespoke (local) property kind, ensure the property kind objects exist as parts in the model before calling this method

decoarsen_imported_list(decoarsen_array=None, reactivate=True)[source]

Decoarsen imported Nexus properties if needed.

Parameters
  • decoarsen_array (int array, optional) – if present, the naturalised cell index of the coarsened host cell, for each fine cell; if None, the ICOARS keyword is searched for in the imported list and if not found KID data is used to derive the mapping

  • reactivate (boolean, default True) – if True, the parent grid will have decoarsened cells’ inactive flag set to that of the host cell

Returns

a copy of the array used for decoarsening, if established, or None if no decoarsening array was identified

Notes

a return value of None indicates that no decoarsening occurred; coarsened values are redistributed quite naively, with coarse volumes being split equally between fine cells, similarly for length and area based properties; default used for most properties is simply to replicate the coarse value; the ICOARS array itself is left unchanged, which means the method should only be called once for an imported list; if no array is passed and no ICOARS array found, the KID values are inspected and the decoarsen array reverse engineered; the method must be called before the imported arrays are written to hdf5; reactivation only modifies the grid object attribute and does not write to hdf5, so the method should be called prior to writing the grid in this situation

discombobulated_face_array(resqpy_a)

Return logical face property array a, re-ordered and reshaped regarding the six facial directions.

argument:
resqpy_a (numpy array of shape (…, 3, 2)): the penultimate array axis represents K,J,I and the final axis is -/+ face

polarity; the resqpy logically arranged property array to be converted to illogical RESQML ordering and shape

Returns

numpy array of shape (…, 6) being a copy of resqpy_a with slices reordered before collapsing the last 2 axes into 1;

ready to be stored as a RESQML property array with indexable element faces per cell

Notes

this method is for properties of IJK grids only; RESQML documentation is not entirely clear about the required ordering of -I, +I, -J, +J faces; current implementation assumes count = 1 for the property; does not currently support points properties

establish_has_multiple_realizations()

Re-evaluates the has multiple realizations attribute.

Based on whether properties belong to more than one realization.

establish_has_single_indexable_element()

Re-evaluate the has single indexable element attribute.

Depends on whether all properties have the same.

establish_has_single_property_kind()

Re-evaluates the has single property kind attribute.

Depends on whether all properties are of the same kind.

establish_has_single_uom()

Re-evaluates the has single uom attribute depending on whether all properties have the same units of measure.

establish_time_set_kind()

Re-evaulates the time set kind attribute.

Based on all properties having same time index in the same time series.

extend_imported_list_copying_properties_from_other_grid_collection(other, box=None, refinement=None, coarsening=None, realization=None, copy_all_realizations=False, uncache_other_arrays=True)[source]

Extends this collection’s imported list with properties from other collection.

Optionally extract for a box.

Parameters
  • other – another GridPropertyCollection object which might relate to a different grid object

  • box – (numpy int array of shape (2, 3), optional): if present, a logical ijk cuboid subset of the source arrays is extracted, box axes are (min:max, kji0); if None, the full arrays are copied

  • refinement (resqpy.olio.fine_coarse.FineCoarse object, optional) – if present, other is taken to be a collection for a coarser grid and the property values are sampled for a finer grid based on the refinement mapping

  • coarsening (resqpy.olio.fine_coarse.FineCoarse object, optional) – if present, other is taken to be a collection for a finer grid and the property values are upscaled for a coarser grid based on the coarsening mapping

  • realization (int, optional) – if present, only properties for this realization are copied; if None, only properties without a realization number are copied unless copy_all_realizations is True

  • copy_all_realizations (boolean, default False) – if True (and realization is None), all properties are copied; if False, only properties with a realization of None are copied; ignored if realization is not None

  • uncache_other_arrays (boolean, default True) – if True, after each array is copied, the original is uncached from the source collection (to free up memory)

Notes

this function can be used to copy properties between one grid object and another compatible one, for example after a grid manipulation has generated a new version of the geometry; it can also be used to select an ijk box subset of the property data and/or refine or coarsen the property data; if a box is supplied, the first index indicates min (0) or max (1) and the second index indicates k (0), j (1) or i (2); the values in box are zero based and cells matching the maximum indices are included (unlike with python ranges); when coarsening or refining, this function ignores the ‘within…box’ attributes of the FineCoarse object so the box argument must be used to effect a local grid coarsening or refinement

extra_metadata_for_part(part)

Returns the extra_metadata dictionary for the part.

Parameters

part (string) – the part name for which the xml node is required

Returns

dictionary containing extra_metadata for part

facet_for_part(part)

If relevant, returns the resqml Facet Value for the property part, eg. ‘I’; otherwise None.

Parameters

part (string) – the part name for which the facet value is required

Returns

facet value for this part (string), for the facet type returned by the facet_type_for_part() function, or None

see notes for facet_type_for_part()

facet_list(sort_list=True)

Returns a list of unique facet values found amongst the parts of the collection.

facet_type_for_part(part)

If relevant, returns the resqml Facet Facet for the property part, eg. ‘direction’; otherwise None.

Parameters

part (string) – the part name for which the facet type is required

Returns

standard resqml facet type for this part (string), or None

Notes

resqml refers to Facet Facet and Facet Value; the equivalents in this module are facet_type and facet; the resqml standard allows a property to have any number of facets; this module currently limits a property to having at most one facet; the facet_type and facet should be either both None or both not None

facet_type_list(sort_list=True)

Returns a list of unique facet types found amongst the parts of the collection.

facets_array_ref(use_32_bit=False, indexable_element=None)

Returns a +1D array of all parts with first axis being over facet values; Use facet_list() for lookup.

Parameters
  • use_32_bit (boolean, default False) – if True, the resulting numpy array will use a 32 bit dtype; if False, 64 bit

  • indexable_element (string, optional) – the indexable element for the properties in the collection; if None, will be determined from the data

Returns

numpy array containing all the data in the collection, the first axis being over facet values and the rest of the axes matching the shape of the individual property arrays

Notes

the property collection should be constructed so as to hold a suitably coherent set of properties before calling this method; the facet_list() method will return the facet values that correspond to slices in the first axis of the resulting array

grid_for_part(part)

Returns grid object that the property relates to.

Parameters

part (string) – the part name for which the related grid object is required

Returns

grid.Grid object reference

Note

this method maintained for backward compatibility and kept in base PropertyClass for pragmatic reasons (rather than being method in GridPropertyCollection)

h5_key_pair_for_part(part)

Return hdf5 key pair (ext uuid, internal path) for the part.

h5_overwrite_slice(part, slice_tuple, array_slice, update_cache=True)

Overwrites a subset of the array for part, in the hdf5 file.

Parameters
  • part (string) – the part name for which the array slice is to be overwritten

  • slice_tuple (tuple of slice objects) – each element should be constructed using the python built-in function slice()

  • array_slice (numpy array of shape to match slice_tuple) – the data to be written

  • update_cache (boolean, default True) – if True and the part is currently cached within this PropertyCollection, then the cached array is also updated; if False, the part is uncached

Notes

this method naively writes the slice to hdf5 without using mpi to look after parallel writes; if a cached copy of the array is updated, this is in an unmasked form; if calling code has a reterence to a masked version of the array then the mask will not be updated by this method; if the part is not currently cached, this method will not cause it to become cached, regardless of the update_cache argument

h5_slice(part, slice_tuple)

Returns a subset of the array for part, without loading the whole array.

Parameters
  • part (string) – the part name for which the array slice is required

  • slice_tuple (tuple of slice objects) – each element should be constructed using the python built-in function slice()

Returns

numpy array that is a hyper-slice of the hdf5 array, with the same ndim as the source hdf5 array

Note

this method always fetches from the hdf5 file and does not attempt local caching; the whole array is not loaded; all axes continue to exist in the returned array, even where the sliced extent of an axis is 1

h5_slice_for_box(part, box)[source]

Returns a subset of the array for part, without loading the whole array (unless already cached).

Parameters
  • part (string) – the part name for which the array slice is required

  • box (numpy int array of shape (2, 3)) – the min, max indices for K, J, I axes for which an array extract is required

Returns

numpy array that is a hyper-slice of the hdf5 array

Note

this method always fetches from the hdf5 file and does not attempt local caching; the whole array is not loaded; all axes continue to exist in the returned array, even where the sliced extent of an axis is 1; the upper indices indicated in the box are included in the data (unlike the python protocol)

has_multiple_realizations()

Returns the has multiple realizations flag based on whether properties belong to more than one realization.

has_single_indexable_element()

Returns the has single indexable element flag depending on whether all properties have the same.

has_single_property_kind()

Return the has single property kind flag depending on whether all properties are of the same kind.

has_single_uom()

Returns the has single uom flag depending on whether all properties have the same units of measure.

import_ab_property_to_cache(file_name, keyword, extent_kji=None, discrete=None, uom=None, time_index=None, null_value=None, property_kind=None, local_property_kind_uuid=None, facet_type=None, facet=None, realization=None)[source]

Reads a property array from a pure binary file, caches and adds to imported list (but not collection dict).

Parameters
  • file_name (string) – the name of the file to read the array data from; should contain data for one array only in ‘pure binary’ format (as used by ab_* suite of utilities)

  • keyword (string) – the keyword to associate with the imported data, which will become the citation title

  • extent_kji (optional, default None) – if present, [nk, nj, ni] being the extent (shape) of the array to be imported; if None, the shape of the grid associated with this collection is used

  • discrete (boolean, optional, default False) – if True, integer data is imported, if False, float data

  • uom (string, optional, default None) – the resqml units of measure applicable to the data

  • time_index (integer, optional, default None) – if present, this array is for time varying data and this value is the index into a time series associated with this collection

  • null_value (int or float, optional, default None) – if present, this is used in the metadata to indicate that this value is to be interpreted as a null value wherever it appears in the data (this does not change the data during import)

  • property_kind (string) – resqml property kind, or None

  • local_property_kind_uuid (uuid.UUID or string) – uuid of local property kind, or None

  • facet_type (string) – resqml facet type, or None

  • facet (string) – resqml facet, or None

  • realization (int) – realization number, or None

Note

this function only performs the first importation step of actually reading the array into memory; other steps must follow to include the array as a part in the resqml model and in this collection of properties (see doc string for add_cached_array_to_imported_list() for the sequence of steps)

import_nexus_property_to_cache(file_name, keyword, extent_kji=None, discrete=False, uom=None, time_index=None, null_value=None, property_kind=None, local_property_kind_uuid=None, facet_type=None, facet=None, realization=None, use_binary=True)[source]

Reads a property array from an ascii (or pure binary) file, caches and adds to imported list.

Does not add to collection dict.

Parameters
  • file_name (string) – the name of the file to read the array data from; should contain data for one array only, without the keyword

  • keyword (string) – the keyword to associate with the imported data, which will become the citation title

  • extent_kji (optional, default None) – if present, [nk, nj, ni] being the extent (shape) of the array to be imported; if None, the shape of the grid associated with this collection is used

  • discrete (boolean, optional, default False) – if True, integer data is imported, if False, float data

  • uom (string, optional, default None) – the resqml units of measure applicable to the data

  • time_index (integer, optional, default None) – if present, this array is for time varying data and this value is the index into a time series associated with this collection

  • null_value (int or float, optional, default None) – if present, this is used in the metadata to indicate that this value is to be interpreted as a null value wherever it appears in the data (this does not change the data during import)

  • property_kind (string) – resqml property kind, or None

  • local_property_kind_uuid (uuid.UUID or string) – uuid of local property kind, or None for standard property kind

  • facet_type (string) – resqml facet type, or None

  • facet (string) – resqml facet, or None

  • realization (int) – realization number, or None

  • use_binary (boolean, optional, default True) – if True, and an up-to-date pure binary version of the file exists, then the data is loaded from that instead of from the ascii file; if True but the binary version does not exist (or is older than the ascii file), the pure binary version is written as a side effect of the import; if False, the ascii file is used even if a pure binary equivalent exists, and no binary file is written

Note

this function only performs the first importation step of actually reading the array into memory; other steps must follow to include the array as a part in the resqml model and in this collection of properties (see doc string for add_cached_array_to_imported_list() for the sequence of steps)

import_vdb_recurrent_property_to_cache(vdbase, timestep, keyword, grid_name='ROOT', time_index=None, uom=None, realization=None, property_kind=None, facet_type=None, facet=None)[source]

Reads a vdb recurrent property array for one timestep, caches and adds to imported list.

Does not add to collection dict.

Parameters
  • vdbase – an object of class vdb.VDB, already initialised with the path of the vdb

  • timestep (int) – the Nexus timestep number at which the property array was generated; NB. this is not necessarily the same as a resqml time index

  • keyword (string) – the Nexus keyword (or equivalent) of the recurrent property to be loaded

  • grid_name (string) – the grid name as used in the vdb

  • time_index (int, optional) – if present, used as the time index, otherwise timestep is used

  • uom (string) – The resqml unit of measure that applies to the data

  • realization (optional, int) – the realization number that this property belongs to; use None if not applicable

  • property_kind (string, optional) – the RESQML property kind of the property

  • facet_type (string, optional) – a RESQML facet type for the property

  • facet (string, optional) – the RESQML facet value for the given facet type for the property

Returns

cached array containing the property data; the cached array is in an unpacked state (ie. can be directly indexed with [k0, j0, i0])

Notes

when importing from a vdb (or other sources), use methods such as this to build up a list of imported arrays; then write hdf5 for the imported arrays; finally create xml for imported properties

import_vdb_static_property_to_cache(vdbase, keyword, grid_name='ROOT', uom=None, realization=None, property_kind=None, facet_type=None, facet=None)[source]

Reads a vdb static property array, caches and adds to imported list (but not collection dict).

Parameters
  • vdbase – an object of class vdb.VDB, already initialised with the path of the vdb

  • keyword (string) – the Nexus keyword (or equivalent) of the static property to be loaded

  • grid_name (string) – the grid name as used in the vdb

  • uom (string) – The resqml unit of measure that applies to the data

  • realization (optional, int) – The realization number that this property belongs to; use None if not applicable

  • property_kind (string, optional) – the RESQML property kind of the property

  • facet_type (string, optional) – a RESQML facet type for the property

  • facet (string, optional) – the RESQML facet value for the given facet type for the property

Returns

cached array containing the property data; the cached array is in an unpacked state (ie. can be directly indexed with [k0, j0, i0])

Note

when importing from a vdb (or other sources), use methods such as this to build up a list of imported arrays; then write hdf5 for the imported arrays; finally create xml for imported properties

indexable_for_part(part)

Returns the text of the IndexableElement for the property part; usually ‘cells’ for grid properties.

Parameters

part (string) – the part name for which the indexable element is required

Returns

string, usually ‘cells’ when the supporting representation is a grid or ‘nodes’ when a wellbore frame

Note

see tail of Representations.xsd for overview of indexable elements usable for other object classes

inherit_imported_list_from_other_collection(other, copy_cached_arrays=True, exclude_inactive=False)

Extends this collection’s imported list with items from other’s imported list.

Parameters
  • other – another PropertyCollection object with some imported arrays

  • copy_cached_arrays (boolean, default True) – if True, arrays cached with the other collection are copied and cached with this collection

  • exclude_inactive (boolean, default False) – if True, any item in the other imported list which has INACTIVE or ACTIVE as the keyword is excluded from the inheritance

Note

the imported list is a list of cached imported arrays with basic info for each array; it is used as a staging post before fully incorporating the imported arrays as parts of the support’s parent model and writing the arrays to the hdf5 file

inherit_parts_from_other_collection(other, ignore_clashes=False)

Adds all the parts in the other PropertyCollection to this one.

Parameters
  • other – another PropertyCollection object related to the same support as this collection

  • ignore_clashes (boolean, default False) – if False, any part in other which is already in this collection will result in an assertion error; if True, such duplicates are simply skipped without modifying the existing part in this collection

inherit_parts_selectively_from_other_collection(other, realization=None, support_uuid=None, grid=None, uuid=None, continuous=None, count=None, points=None, indexable=None, property_kind=None, facet_type=None, facet=None, citation_title=None, citation_title_match_mode=False, time_series_uuid=None, time_index=None, uom=None, string_lookup_uuid=None, categorical=None, related_uuid=None, const_value=None, ignore_clashes=False)

Adds those parts from the other PropertyCollection which match all arguments that are not None.

Parameters
  • other – another PropertyCollection object related to the same support as this collection

  • citation_title_match_mode (str, optional) – if present, one of ‘is’, ‘starts’, ‘ends’, ‘contains’, ‘is not’, ‘does not start’, ‘does not end’, ‘does not contain’; None is the same as ‘is’

  • ignore_clashes (boolean, default False) – if False, any part in other which passes the filters yet is already in this collection will result in an assertion error; if True, such duplicates are simply skipped without modifying the existing part in this collection

Other optional arguments (realization, grid, uuid, continuous, count, points, indexable, property_kind, facet_type, facet, citation_title, time_series_uuid, time_index, uom, string_lookup_uuid, categorical):

For each of these arguments: if None, then all members of collection pass this filter; if not None then only those members with the given value pass this filter; finally, the filters for all the attributes must be passed for a given member (part) to be inherited; a soft relationship is sufficient for related_uuid to pass.

Note

the grid argument is maintained for backward compatibility; it is treated synonymously with support which takes precendence; the categorical boolean argument can be used to filter only Categorical (or non-Categorical) properties

inherit_similar_parts_for_facets_from_other_collection(other, example_part, citation_title_match_mode=None, ignore_clashes=False)

Adds the example part from other collection and any other parts for same property with different facets.

Parameters
  • other – another PropertyCollection object related to the same grid as this collection, from which to inherit

  • example_part (string) – the part name of an example member of other

  • citation_title_match_mode (str, optional) – if present, one of ‘is’, ‘starts’, ‘ends’, ‘contains’, ‘is not’, ‘does not start’, ‘does not end’, ‘does not contain’; None is the same as ‘is’

  • ignore_clashes (boolean, default False) – if False, any part in other which passes the filters yet is already in this collection will result in an assertion error; if True, such duplicates are simply skipped without modifying the existing part in this collection

Note

at present, the citation title must match (as well as the other identifying elements) for a part to be inherited

inherit_similar_parts_for_realizations_from_other_collection(other, example_part, citation_title_match_mode=None, ignore_clashes=False)

Add the example part from other collection and any other parts for same property with different realizations.

Parameters
  • other – another PropertyCollection object related to the same support as this collection, from which to inherit

  • example_part (string) – the part name of an example member of other

  • citation_title_match_mode (str, optional) – if present, one of ‘is’, ‘starts’, ‘ends’, ‘contains’, ‘is not’, ‘does not start’, ‘does not end’, ‘does not contain’; None is the same as ‘is’

  • ignore_clashes (boolean, default False) – if False, any part in other which passes the filters yet is already in this collection will result in an assertion error; if True, such duplicates are simply skipped without modifying the existing part in this collection

Note

at present, the citation title must match (as well as the other identifying elements) for a part to be inherited

inherit_similar_parts_for_time_series_from_other_collection(other, example_part, citation_title_match_mode=None, ignore_clashes=False)

Adds the example part from other collection and any other parts for the same property at different times.

Parameters
  • other – another PropertyCollection object related to the same grid as this collection, from which to inherit

  • example_part (string) – the part name of an example member of other (which has an associated time_series)

  • citation_title_match_mode (str, optional) – if present, one of ‘is’, ‘starts’, ‘ends’, ‘contains’, ‘is not’, ‘does not start’, ‘does not end’, ‘does not contain’; None is the same as ‘is’

  • ignore_clashes (boolean, default False) – if False, any part in other which passes the filters yet is already in this collection will result in an assertion error; if True, such duplicates are simply skipped without modifying the existing part in this collection

Note

at present, the citation title must match (as well as the other identifying elements) for a part to be inherited

local_property_kind_uuid(part)

Returns the uuid of the bespoke (local) property kind for this part, or None for a standard property kind.

masked_array(simple_array, exclude_inactive=True, exclude_value=None, points=False)

Returns a masked version of simple_array, using inactive mask associated with support for this property collection.

Parameters
  • simple_array (numpy array) – an unmasked numpy array with the same shape as property arrays for the support (and indexable element) associated with this collection

  • exclude_inactive (boolean, default True) – elements which are flagged as inactive in the supporting representation are masked out if this argument is True

  • exclude_value (float or int, optional) – if present, elements which match this value are masked out; if not None then usually set to np.NaN for continuous data or null_value_for_part() for discrete data

  • points (boolean, default False) – if True, the simple array is expected to have an extra dimension of extent 3, relative to the inactive attribute of the support

Returns

a masked version of the array, with the mask set to exclude cells which are inactive in the support

Notes

when requesting a reference to a cached copy of a property array (using other functions), a masked argument can be used to apply the inactive mask; this function is therefore rarely needed by calling code (it is used internally by this module); the simple_array need not be part of this collection

maximum_value_for_part(part)

Returns the maximum value for the property part, as stored in the xml.

Parameters

part (string) – the part name for which the maximum value is required

Returns

maximum value (as float ir int) for this part, or None if metadata item is not set

Note

this method merely returns the maximum value recorded in the xml for the property, it does not check the array data

minimum_value_for_part(part)

Returns the minimum value for the property part, as stored in the xml.

Parameters

part (string) – the part name for which the minimum value is required

Returns

minimum value (as float or int) for this part, or None if metadata item is not set

Note

this method merely returns the minimum value recorded in the xml for the property, it does not check the array data

node_for_part(part)

Returns the xml node for the property part.

Parameters

part (string) – the part name for which the xml node is required

Returns

xml Element object reference for the main xml node for the part

normalized_part_array(part, masked=False, use_logarithm=False, discrete_cycle=None, trust_min_max=False, fix_zero_at=None)

Return data normalised to between 0 and 1, along with min and max value.

Parameters
  • part (string) – the part name for which the normalized array reference is required

  • masked (boolean, optional, default False) – if True, the masked version of the property array is used to determine the range of values to map onto the normalized range of 0 to 1 (the mask removes inactive cells from having any impact); if False, the values of inactive cells are included in the operation; the returned normalized array is masked or not depending on this argument

  • use_logarithm (boolean, optional, default False) – if False, the property values are linearly mapped to the normalized range; if True, the logarithm (base 10) of the property values are mapped to the normalized range

  • discrete_cycle (positive integer, optional, default None) – if a value is supplied and the property array contains integer data (discrete or categorical), the modulus of the property values are calculated against this value before conversion to floating point and mapping to the normalized range

  • trust_min_max (boolean, optional, default False) – if True, the minimum and maximum values from the property’s metadata is used as the range of the property values; if False, the values are determined using numpy min and max operations

  • fix_zero_at (float, optional) – if present, a value between 0.0 and 1.0 (typically 0.0 or 0.5) to pin zero at

Returns

(normalized_array, min_value, max_value) where – normalized_array is a numpy array of floats, masked or unmasked depending on the masked argument, with values ranging between 0 and 1; in the case of a masked array the values for excluded cells are meaningless and may lie outside the range 0 to 1 min_value and max_value: the property values that have been mapped to 0 and 1 respectively

Notes

this function is typically used to map property values onto the range required for colouring in; in case of failure, (None, None, None) is returned; if use_logarithm is True, the min_value and max_value returned are the log10 values, not the original property values; also, if use logarithm is True and the minimum property value is not greater than zero, then values less than 0.0001 are set to 0.0001, prior to taking the logarithm; fix_zero_at is mutually incompatible with use_logarithm; to force the normalised data to have a true zero, set fix_zero_at to 0.0; for divergent data fixing zero at 0.5 will often be appropriate; fixing zero at 0.0 or 1.0 may result in normalised values being clipped; for floating point data, NaN values will be handled okay; if all data are NaN, (None, NaN, NaN) is returned; for integer data, null values are not currently supported (though the RESQML metadata can hold a null value); the masked argument is most applicable to properties for grid objects; note that NaN values are excluded when determining the min and max regardless of the value of the masked argument; not applicable to points properties

null_value_for_part(part)

Returns the null value for the (discrete) property part; np.NaN for continuous parts.

Parameters

part (string) – the part name for which the null value is required

Returns

int or np.NaN

number_of_imports()

Returns the number of property arrays in the imported list for this collection.

Returns

count of number of cached property arrays in the imported list for this collection (non-negative integer)

Note

the importation list is cleared after creation of xml trees for the imported properties, so this function will return zero at that point, until a new list of imports is built up

number_of_parts()

Returns the number of parts (properties) in this collection.

Returns

count of the number of parts (members) in this collection; there is one part per property array (non-negative integer)

override_min_max(part, min_value, max_value)

Sets the minimum and maximum values in the metadata for the part.

Parameters
  • part (string) – the part name for which the minimum and maximum values are to be set

  • min_value (float or int or string) – the minimum value to be stored in the metadata

  • max_value (float or int or string) – the maximum value to be stored in the metadata

Note

this function is typically called if the existing min & max metadata is missing or distrusted; the min and max values passed in are typically the result of numpy min and max function calls (possibly skipping NaNs) on the property array or a version of it masked for inactive cells

part_filename(part)

Returns a string which can be used as the starting point of a filename relating to part.

Parameters

part (string) – the part name for which a partial filename is required

Returns

a string suitable as the basis of a filename for the part (typically used when exporting)

part_in_collection(part)

Returns True if named part is member of this collection; otherwise False.

Parameters

part (string) – part name to be tested for membership of this collection

Returns

boolean

part_is_categorical(part)

Returns True if the property is categorical (not conintuous and has an associated string lookup).

part_str(part, include_citation_title=True)

Returns a human-readable string identifying the part.

Parameters
  • part (string) – the part name for which a displayable string is required

  • include_citation_title (boolean, default True) – if True, the citation title for the part is included in parenthesis at the end of the returned string; otherwise it does not appear

Returns

a human readable string consisting of the property kind, the facet (if present), the time index (if applicable), and the citation title (if requested)

Note

the time index is labelled ‘timestep’ in the returned string; however, resqml differentiates between the simulator timestep number and a time index into a time series; at present this module conflates the two

parts()

Return list of parts in this collection.

Returns

list of part names (strings) being the members of this collection; there is one part per property array

patch_min_max_for_part(part, minimum=None, maximum=None, model=None)

Updates the minimum and/ox maximum values stored in the metadata, optionally updating xml tree too.

Parameters
  • part (str) – the part name of the property

  • minimum (float or int, optional) – the new minimum value to be set in the metadata (unchanged if None)

  • maximum (float or int, optional) – the new maximum value to be set in the metadata (unchanged if None)

  • model (model.Model, optional) – if present and containing xml for the part, that xml is also patched

Notes

this method is rarely needed: only if a property array is being re-populated after being initialised with temporary values; the xml tree for the part in the model will only be updated where the minimum and/or maximum nodes already exist in the tree

points_for_part(part)

Returns True if the property is a points property; False otherwise.

Parameters

part (string) – the part name for which the points flag is required

Returns

True if the part is representing a points property, ie. the array has an extra dimension of extent 3 covering the xyz axes; False if the part is representing a non-points property

populate_from_property_set(property_set_root)

Populates this (newly created) collection based on xml members of property set.

property_kind_for_part(part)

Returns the resqml property kind for the property part.

Parameters

part (string) – the part name for which the property kind is required

Returns

standard resqml property kind or local property kind for this part, as a string, eg. ‘porosity’

Notes

see attributes of this module named supported_property_kind_list and supported_local_property_kind_list for the property kinds which this module can relate to simulator keywords (Nexus); however, other property kinds should be handled okay in a generic way; for bespoke (local) property kinds, this is the property kind title as stored in the xml reference node

property_kind_list(sort_list=True)

Returns a list of unique property kinds found amongst the parts of the collection.

realization_for_part(part)

Returns realization number (within ensemble) that the property relates to.

Parameters

part (string) – the part name for which the realization number (realization index) is required

Returns

integer or None

realization_list(sort_list=True)

Returns a list of unique realization numbers present in the collection.

realizations_array_ref(use_32_bit=False, fill_missing=True, fill_value=None, indexable_element=None)

Returns a +1D array of all parts with first axis being over realizations.

Parameters
  • use_32_bit (boolean, default False) – if True, the resulting numpy array will use a 32 bit dtype; if False, 64 bit

  • fill_missing (boolean, default True) – if True, the first axis of the resulting numpy array will range from 0 to the maximum realization number present and slices for any missing realizations will be filled with fill_value; if False, the extent of the first axis will only cpver the number pf realizations actually present (see also notes)

  • fill_value (int or float, optional) – the value to use for missing realization slices; if None, will default to np.NaN if data is continuous, -1 otherwise; irrelevant if fill_missing is False

  • indexable_element (string, optional) – the indexable element for the properties in the collection; if None, will be determined from the data

Returns

numpy array containing all the data in the collection, the first axis being over realizations and the rest of the axes matching the shape of the individual property arrays

Notes

the property collection should be constructed so as to hold a suitably coherent set of properties before calling this method; if fill_missing is False, the realization axis indices range from zero to the number of realizations present; if True, the realization axis indices range from zero to the maximum realization number and slices for missing realizations will be filled with the fill_value

remove_all_cached_arrays()

Removes any cached arrays for parts or mentioned in imported list.

remove_cached_imported_arrays()

Removes any cached arrays that are mentioned in imported list.

remove_cached_part_arrays()

Removes any cached arrays for parts of the collection.

remove_part_from_dict(part)

Remove the named part from the dictionary for this collection.

argument:

part (string): the name of a part which might be in this collection, to be removed

Note

if the part is not in the collection, no action is taken and no exception is raised

remove_parts_list_from_dict(parts_list)

Remove all the parts named in the parts list from the dictionary for this collection.

argument:

parts_list: a list of strings, each being the name of a part which might be in the collection

Note

the remove_part_from_dict() function is called for each part in the list

selective_parts_list(realization=None, support=None, support_uuid=None, grid=None, continuous=None, points=None, count=None, indexable=None, property_kind=None, facet_type=None, facet=None, citation_title=None, title_mode=None, time_series_uuid=None, time_index=None, uom=None, string_lookup_uuid=None, categorical=None, related_uuid=None, title=None, const_value=None)

Returns a list of parts filtered by those arguments which are not None.

All arguments are optional.

For each of these arguments: if None, then all members of collection pass this filter; if not None then only those members with the given value pass this filter; finally, the filters for all the attributes must be passed for a given member (part) to be included in the returned list of parts; title is a synonym for citation_title

Returns

list of part names (strings) of those parts which match any selection arguments which are not None

Note

the support and grid keyword arguments are maintained for backward compatibility; support_uuid takes precedence over support and both take precedence over grid

set_grid(grid, grid_root=None, modify_parts=True)[source]

Sets the supporting representation object for the collection to be the given grid.

Note

this method does not need to be called if the grid was passed during object initialisation.

set_realization(realization)

Sets the model realization number (within an ensemble) for this collection.

argument:
realization (non-negative integer): the realization number of the whole collection within an ensemble of

collections

Note

the resqml Property classes allow for a realization index to be associated with an individual property array; this module supports this by associating a realization number (equivalent to realization index) for each part (ie. for each property array); however, the collection can be given a realization number which is then applied to each member of the collection as it is added, if no part-specific realization number is provided

set_support(support_uuid=None, support=None, model=None, modify_parts=True)

Sets the supporting object associated with this collection if not done so at initialisation.

Does not load properties.

Parameters
  • support_uuid – the uuid of the supporting representation which the properties in this collection are for

  • support – a grid.Grid, unstructured.UnstructuredGrid (or derived class), well.WellboreFrame, well.BlockedWell, surface.Mesh, well.WellboreMarkerFrame or fault.GridConnectionSet object which the properties in this collection are for

  • model (model.Model object, optional) – if present, the model associated with this collection is set to this; otherwise the model is assigned from the supporting object

  • modify_parts (boolean, default True) – if True, any parts already in this collection have their individual support_uuid set

shape_and_type_of_part(part)

Returns shape tuple and element type of cached or hdf5 array for part.

single_array_ref(realization=None, support=None, support_uuid=None, grid=None, uuid=None, continuous=None, points=None, count=None, indexable=None, property_kind=None, facet_type=None, facet=None, citation_title=None, time_series_uuid=None, time_index=None, uom=None, string_lookup_uuid=None, categorical=None, dtype=None, masked=False, exclude_null=False, multiple_handling='exception', title=None, title_mode=None, related_uuid=None)

Returns the array of data for a single part selected by those arguments which are not None.

Parameters
  • dtype (optional, default None) – the element data type of the array to be accessed, eg ‘float’ or ‘int’; if None (recommended), the dtype of the returned numpy array matches that in the hdf5 dataset

  • masked (boolean, optional, default False) – if True, a masked array is returned instead of a simple numpy array; the mask is set to the inactive array attribute of the grid object

  • exclude_null (boolean, default False) – it True and masked is True, elements holding the null value will also be masked out

  • multiple_handling (string, default 'exception') – one of ‘exception’, ‘none’, ‘first’, ‘oldest’, ‘newest’

  • title (string, optional) – synonym for citation_title argument

Other optional arguments: realization, support, support_uuid, grid, continuous, points, count, indexable, property_kind, facet_type, facet, citation_title, time_series_uuid, time_index, uom, string_lookup_id, categorical, related_uuid:

For each of these arguments: if None, then all members of collection pass this filter; if not None then only those members with the given value pass this filter; finally, the filters for all the attributes must pass for a given member (part) to be selected

Returns

reference to a cached numpy array containing the actual property data for the part which matches all selection arguments which are not None

Notes

returns None if no parts match; if more than one part matches multiple_handling argument determines behaviour; multiple calls will return the same cached array so calling code should copy if duplication is needed; support and grid arguments are for backward compatibilty: support_uuid takes precedence over support and both take precendence over grid

singleton(realization=None, support=None, support_uuid=None, grid=None, uuid=None, continuous=None, points=None, count=None, indexable=None, property_kind=None, facet_type=None, facet=None, citation_title=None, time_series_uuid=None, time_index=None, uom=None, string_lookup_uuid=None, categorical=None, multiple_handling='exception', title=None, title_mode=None, related_uuid=None, const_value=None)

Returns a single part selected by those arguments which are not None.

multiple_handling (string, default ‘exception’): one of ‘exception’, ‘none’, ‘first’, ‘oldest’, ‘newest’ title (string, optional): synonym for citation_title argument

For each argument (other than multiple_handling): if None, then all members of collection pass this filter; if not None then only those members with the given value pass this filter; finally, the filters for all the attributes must pass for a given member (part) to be selected

multiple_handling (string, default ‘exception’): one of ‘exception’, ‘none’, ‘first’, ‘oldest’, ‘newest’

Returns

part name (string) of the part which matches all selection arguments which are not None; returns None if no parts match; if more than one part matches multiple_handling argument determines behaviour

string_lookup_for_part(part)

Returns a StringLookup object for the part, if it has a string lookup uuid, otherwise None.

string_lookup_uuid_for_part(part)

If the property has an associated string lookup (is categorical), return the uuid.

Parameters

part (string) – the part name for which the string lookup uuid is required

Returns

string lookup uuid (uuid.UUID) for this part

string_lookup_uuid_list(sort_list=True)

Returns a list of unique string lookup uuids found amongst the parts of the collection.

support_uuid_for_part(part)

Returns supporting representation object’s uuid that the property relates to.

Parameters

part (string) – the part name for which the related support object uuid is required

Returns

uuid.UUID object (or string representation thereof)

supporting_shape(indexable_element=None, direction=None)

Return the shape of the supporting representation with respect to the given indexable element

Parameters
  • indexable_element (string, optional) – if None, a hard-coded default depending on the supporting representation class will be used

  • direction (string, optional) – must be passed if required for the combination of support class and indexable element; currently only used for Grid faces.

Returns

list of int, being required shape of numpy array, or None if not coded for

Note

individual property arrays will only match this shape if they have the same indexable element and a count of one

time_index_for_part(part)

If the property has an associated time series (is not static), returns the time index within the time series.

Parameters

part (string) – the part name for which the time index is required

Returns

time index (integer) for this part

time_index_list(sort_list=True)

Returns a list of unique time indices found amongst the parts of the collection.

time_series_array_ref(use_32_bit=False, fill_missing=True, fill_value=None, indexable_element=None)

Returns a +1D array of all parts with first axis being over time indices.

Parameters
  • use_32_bit (boolean, default False) – if True, the resulting numpy array will use a 32 bit dtype; if False, 64 bit

  • fill_missing (boolean, default True) – if True, the first axis of the resulting numpy array will range from 0 to the maximum time index present and slices for any missing indices will be filled with fill_value; if False, the extent of the first axis will only cpver the number pf time indices actually present (see also notes)

  • fill_value (int or float, optional) – the value to use for missing time index slices; if None, will default to np.NaN if data is continuous, -1 otherwise; irrelevant if fill_missing is False

  • indexable_element (string, optional) – the indexable element for the properties in the collection; if None, will be determined from the data

Returns

numpy array containing all the data in the collection, the first axis being over time indices and the rest of the axes matching the shape of the individual property arrays

Notes

the property collection should be constructed so as to hold a suitably coherent set of properties before calling this method; if fill_missing is False, the time axis indices range from zero to the number of time indices present, with the list of tine index values available by calling the method time_index_list(sort_list = True); if fill_missing is True, the time axis indices range from zero to the maximum time index and slices for missing time indices will be filled with the fill_value

time_series_uuid_for_part(part)

If the property has an associated time series (is not static), returns the uuid for the time series.

Parameters

part (string) – the part name for which the time series uuid is required

Returns

time series uuid (uuid.UUID) for this part

time_series_uuid_list(sort_list=True)

Returns a list of unique time series uuids found amongst the parts of the collection.

time_set_kind()

Returns the time set kind attribute.

Based on all properties having same time index in the same time series.

title_for_part(part)

Synonymous with citation_title_for_part().

titles()

Returns a list of citation titles for the parts in the collection.

uncache_part_array(part)

Removes the cached copy of the array of data for the named property part.

argument:

part (string): the part name for which the cached array is to be removed

Note

this function applies a python delattr() which will mark the array as no longer being in use here; however, actual freeing of the memory only happens when all other references to the array are released

unique_indexable_element_list(sort_list=False)

Returns a list of unique values for the IndexableElement of the property parts in the collection.

uom_for_part(part)

Returns the resqml units of measure for the property part.

Parameters

part (string) – the part name for which the units of measure is required

Returns

resqml units of measure (string) for this part

uom_list(sort_list=True)

Returns a list of unique units of measure found amongst the parts of the collection.

uuid_for_part(part)

Returns UUID object for the property part.

Parameters

part (string) – the part name for which the UUID is required

Returns

uuid.UUID object reference; use str(uuid_for_part()) to convert to string

uuids()

Return list of uuids in this collection.

Returns

list of uuids being the members of this collection; there is one uuid per property array

write_hdf5_for_imported_list(file_name=None, mode='a', expand_const_arrays=False, dtype=None)

Create or append to an hdf5 file, writing datasets for the imported arrays.

Parameters
  • file_name (str, optional) – if present, this hdf5 filename will override the default

  • mode (str, default 'a') – the mode to open the hdf5 file in, either ‘a’ (append), or ‘w’ (overwrite)

  • expand_const_arrays (boolean, default False) – if True, constant arrays will be written in full to the hdf5 file and the same argument should be used when creating the xml

  • dtype (numpy dtype, optional) – the required numpy element type to use when writing to hdf5; eg. np.float16, np.float32, np.float64, np.uint8, np.int16, np.int32, np.int64 etc.; defaults to the dtype of each individual numpy array in the imported list

write_hdf5_for_part(part, file_name=None, mode='a')

Create or append to an hdf5 file, writing dataset for the specified part.

write_nexus_collection(directory, use_title_for_keyword=False, headers=True, columns=20, decimals=3, blank_line_after_i_block=True, blank_line_after_j_block=False, space_separated=False, use_binary=False, binary_only=False, nan_substitute_value=None)[source]

Writes a set of files, one for each part in the collection.

Parameters
  • directory (string) – the path of the diractory into which the files will be written

  • arguments (for other) – write_nexus_property() functions

  • and (see the docstrings for the write_nexus_property_generating_filename()) – write_nexus_property() functions

Note

the generated filenames are based on the citation titles etc., as for write_nexus_property_generating_filename()

write_nexus_property(part, file_name, keyword=None, headers=True, append=False, columns=20, decimals=3, blank_line_after_i_block=True, blank_line_after_j_block=False, space_separated=False, use_binary=False, binary_only=False, nan_substitute_value=None)[source]

Writes the property array to a file in a format suitable for including as nexus input.

Parameters
  • part (string) – the part name for which the array is to be exported

  • file_name (string) – the path of the file to be created (any existing file will be overwritten)

  • keyword (string, optional, default None) – if not None, the Nexus keyword to be included in the ascii export file (otherwise data only is written, without a keyword)

  • headers (boolean, optional, default True) – if True, some header comments are included in the ascii export file, using a Nexus comment character

  • append (boolean, optional, default False) – if True, any existing file is appended to rather than overwritten

  • columns (integer, optional, default 20) – the maximum number of data items to be written per line

  • decimals (integer, optional, default 3) – the number of decimal places included in the values written to the ascii export file (ignored for integer data)

  • blank_line_after_i_block (boolean, optional, default True) – if True, a blank line is inserted after each I-block of data (ie. when the J index changes)

  • blank_line_after_j_block (boolean, optional, default False) – if True, a blank line is inserted after each J-block of data (ie. when the K index changes)

  • space_separated (boolean, optional, default False) – if True, a space is inserted between values; if False, a tab is used

  • use_binary (boolean, optional, default False) – if True, a pure binary copy of the array is written

  • binary_only (boolean, optional, default False) – if True, and if use_binary is True, then no ascii file is generated; if False (or if use_binary is False) then an ascii file is written

  • nan_substitute_value (float, optional, default None) – if a value is supplied, any not-a-number values are replaced with this value in the exported file (the cached property array remains unchanged); if None, then ‘nan’ or ‘Nan’ will appear in the ascii export file

write_nexus_property_generating_filename(part, directory, use_title_for_keyword=False, headers=True, columns=20, decimals=3, blank_line_after_i_block=True, blank_line_after_j_block=False, space_separated=False, use_binary=False, binary_only=False, nan_substitute_value=None)[source]

Writes the property array to a file using a filename generated from the citation title etc.

Parameters
  • part (string) – the part name for which the array is to be exported

  • directory (string) – the path of the diractory into which the file will be written

  • use_title_for_keyword (boolean, optional, default False) – if True, the citation title for the property part is used as a keyword in the ascii export file

  • arguments (for other) –

  • function (see the docstring for the write_nexus_property()) –

Note

the generated filename consists of:

the citation title (with spaces replaced with underscores); the facet type and facet, if present; _t_ and the time_index, if the part has a time index _r_ and the realisation number, if the part has a realisation number