resqpy.property.Property

class resqpy.property.Property(parent_model, uuid=None, title=None, support_uuid=None, extra_metadata=None)

Bases: BaseResqpy

Class for an individual property object; uses a single element PropertyCollection behind the scenes.

Public Data Attributes:

resqml_type

Returns the RESQML object class string for this Property.

Inherited from BaseResqpy

resqml_type

Returns the RESQML object class string for this Property.

part

Standard part name corresponding to self.uuid.

root

XML node corresponding to self.uuid.

citation_title

Citation block title equivalent to self.title.

Commonly Used Methods:

__init__(parent_model[, uuid, title, ...])

Initialises a resqpy Property object, either for an existing RESQML property, or empty for support.

from_array(parent_model, cached_array, ...)

Populates a new Property from a numpy array and metadata; NB.

array_ref([dtype, masked, exclude_null, ...])

Returns a (cached) numpy array containing the property values.

is_continuous()

Returns boolean indicating that the property contains continuous (ie.

is_categorical()

Returns boolean indicating that the property contains categorical data.

indexable_element()

Returns string being the indexable element for the property.

property_kind()

Returns string being the property kind for the property.

facet_type()

Returns string being the facet type for the property, or None if no facet present.

facet()

Returns string being the facet value for the property, or None if no facet present.

uom()

Returns string being the units of measure (for a continuous property, otherwise None).

Methods:

from_singleton_collection(property_collection)

Populates a new Property from a PropertyCollection containing just one part.

is_points()

Returns boolean indicating that the property is a points property.

null_value()

Returns int being the null value for the (discrete) property.

count()

Returns int being the number of values for each element (usually 1).

local_property_kind_uuid()

Returns uuid of the local property kind for the property (if applicable, otherwise None).

time_series_uuid()

Returns the uuid of the related time series (if applicable, otherwise None).

time_index()

Returns int being the index into the related time series (if applicable, otherwise None).

minimum_value()

Returns the minimum value for the property as stored in xml (float or int or None).

maximum_value()

Returns the maximum value for the property as stored in xml (float or int or None).

realization()

Returns int being the realization number of the property, or None.

string_lookup_uuid()

Returns the uuid of the related string lookup table (for a categorical property, otherwise None).

string_lookup()

Returns a resqpy StringLookup table (for a categorical property, otherwise None).

constant_value()

For a constant property, returns the constant value (float or int or bool, or None if not constant).

prepare_import(cached_array, source_info, ...)

Takes a numpy array and metadata and sets up a single array import list; not usually called directly.

write_hdf5([file_name, mode, ...])

Writes the array data to the hdf5 file; not usually called directly.

create_xml([ext_uuid, support_uuid, ...])

Creates an xml tree for the property and adds it as a part to the model; not usually called directly.

Inherited from BaseResqpy

__init__(parent_model[, uuid, title, ...])

Initialises a resqpy Property object, either for an existing RESQML property, or empty for support.

try_reuse()

Look for an equivalent existing RESQML object and modify the uuid of this object if found.

create_xml([ext_uuid, support_uuid, ...])

Creates an xml tree for the property and adds it as a part to the model; not usually called directly.

append_extra_metadata(meta_dict)

Append a given dictionary of metadata to the existing metadata.

__eq__(other)

Implements equals operator; uses is_equivalent() otherwise compares class type and uuid.

__ne__(other)

Implements not equal operator.

__repr__()

String representation.


__init__(parent_model, uuid=None, title=None, support_uuid=None, extra_metadata=None)[source]

Initialises a resqpy Property object, either for an existing RESQML property, or empty for support.

Parameters
  • parent_model (model.Model) – the model to which the property belongs

  • uuid (uuid.UUID, optional) – required if initialising from an existing RESQML property object

  • title (str, optional) – the citation title to use for the property; ignored if uuid is present

  • support_uuid (uuid.UUID, optional) – identifies the supporting representation for the property; ignored if uuid is present

  • extra_metadata (dict, optional) – if present, the dictionary items are added as extra metadata; ignored if uuid is present

Returns

new resqpy Property object

append_extra_metadata(meta_dict)

Append a given dictionary of metadata to the existing metadata.

array_ref(dtype=None, masked=False, exclude_null=False, use_pack=True)[source]

Returns a (cached) numpy array containing the property values.

Parameters
  • dtype (str or type, optional) – the required dtype of the array (usually float, int or bool)

  • masked (boolean, default False) – if True, a numpy masked array is returned, with the mask determined by the inactive cell mask in the case of a Grid property

  • exclude_null (boolean, default False) – if True and masked is True, elements whose value is the null value (NaN for floats) will be masked out

  • use_pack (boolean, default True) – if True, and the property is a boolean array, the hdf5 data will be unpacked if its shape indicates that it has been packed into bits for storage

Returns

numpy array

property citation_title

Citation block title equivalent to self.title.

constant_value()[source]

For a constant property, returns the constant value (float or int or bool, or None if not constant).

count()[source]

Returns int being the number of values for each element (usually 1).

create_xml(ext_uuid=None, support_uuid=None, time_series_uuid=None, string_lookup_uuid=None, property_kind_uuid=None, find_local_property_kind=True, expand_const_arrays=False, extra_metadata={})[source]

Creates an xml tree for the property and adds it as a part to the model; not usually called directly.

Note

see the documentation for the convenience method from_array() NB. this method has the deliberate side effect of modifying the uuid and title of self to match those of the property collection part!

facet()[source]

Returns string being the facet value for the property, or None if no facet present.

note: resqpy currently supports at most one facet per property, though RESQML allows for multiple.

facet_type()[source]

Returns string being the facet type for the property, or None if no facet present.

note: resqpy currently supports at most one facet per property, though RESQML allows for multiple.

classmethod from_array(parent_model, cached_array, source_info, keyword, support_uuid, property_kind=None, local_property_kind_uuid=None, indexable_element=None, facet_type=None, facet=None, discrete=False, uom=None, null_value=None, time_series_uuid=None, time_index=None, realization=None, count=1, points=False, const_value=None, string_lookup_uuid=None, find_local_property_kind=True, expand_const_arrays=False, dtype=None, use_pack=False, extra_metadata={}, chunks=None, compression=None)[source]

Populates a new Property from a numpy array and metadata; NB. Writes data to hdf5 and adds part to model.

Parameters
  • parent_model (model.Model) – the model to which the new property belongs

  • cached_array – a numpy array to be made into a property; 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 for the property

  • support_uuid (uuid) – the uuid of the supporting representation

  • property_kind (string) – resqml property kind (required unless a local propery kind is identified with local_property_kind_uuid)

  • local_property_kind_uuid (uuid.UUID or string, optional) – uuid of local property kind, or None if a standard property kind applies or if the local property kind is identified by its name (see find_local_property_kind)

  • indexable_element (string) – the indexable element in the supporting representation; if None then the ‘typical’ indexable element for the class of supporting representation will be assumed

  • facet_type (string, optional) – resqml facet type, or None; resqpy only supports at most one facet per property though RESQML allows for multiple)

  • facet (string, optional) – resqml facet, or None; resqpy only supports at most one facet per property though RESQML allows for multiple)

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

  • uom (string, optional, default None) – the resqml units of measure for the data; required for continuous (float) array

  • null_value (int, optional, default None) – if present, this is used in the metadata to indicate that the value is to be interpreted as a null value wherever it appears in the discrete data; not used for continuous data where NaN is always the null value

  • time_series_uuid (optional) – the uuid of the full or reduced time series that the time_index is for

  • time_index (integer, optional, default None) – if not None, the time index for the property (see also time_series_uuid)

  • realization (int, optional) – realization number, or None

  • 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

  • string_lookup_uuid (optional) – if present, the uuid of the string table lookup which the categorical data relates to; if None, the property will not be configured as categorical

  • find_local_property_kind (boolean, default True) – if True, local property kind uuid need not be provided as long as the property_kind is set to match the title of the appropriate local property kind object

  • expand_const_arrays (boolean, default False) – if True, and a const_value is given, the array will be fully expanded and written to the hdf5 file; the xml will then not indicate that it is constant

  • dtype (numpy dtype, optional) – if present, the elemental data type to use when writing the array to hdf5

  • use_pack (bool, default False) – if True, a bool array will be packed along its last axis; this will generally result in hdf5 data that is not readable by non-resqpy applications

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

  • chunks (str, optional) – if not None, one of ‘auto’, ‘all’, or ‘slice’, controlling hdf5 chunks

  • compression (str, optional) – if not None, one of ‘gzip’ or ‘lzf’ being the hdf5 compression algorithm to be used; gzip gives better compression ratio but is slower

Returns

new Property object built from numpy array; the hdf5 data has been written, xml created and the part added to the model

Notes

this method writes to the hdf5 file and creates the xml node, which is added as a part to the model; calling code must still call the model’s store_epc() method; this from_array() method is a convenience method calling self.collection.set_support(), self.prepare_import(), self.write_hdf5() and self.create_xml()

classmethod from_singleton_collection(property_collection: PropertyCollection)[source]

Populates a new Property from a PropertyCollection containing just one part.

Parameters

property_collection (PropertyCollection) – the singleton collection from which to populate this Property

indexable_element()[source]

Returns string being the indexable element for the property.

is_categorical()[source]

Returns boolean indicating that the property contains categorical data.

is_continuous()[source]

Returns boolean indicating that the property contains continuous (ie. float) data.

is_points()[source]

Returns boolean indicating that the property is a points property.

local_property_kind_uuid()[source]

Returns uuid of the local property kind for the property (if applicable, otherwise None).

maximum_value()[source]

Returns the maximum value for the property as stored in xml (float or int or None).

minimum_value()[source]

Returns the minimum value for the property as stored in xml (float or int or None).

null_value()[source]

Returns int being the null value for the (discrete) property.

property part

Standard part name corresponding to self.uuid.

prepare_import(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)[source]

Takes a numpy array and metadata and sets up a single array import list; not usually called directly.

Note

see the documentation for the convenience method from_array()

property_kind()[source]

Returns string being the property kind for the property.

realization()[source]

Returns int being the realization number of the property, or None.

property resqml_type

Returns the RESQML object class string for this Property.

property root

XML node corresponding to self.uuid.

string_lookup()[source]

Returns a resqpy StringLookup table (for a categorical property, otherwise None).

string_lookup_uuid()[source]

Returns the uuid of the related string lookup table (for a categorical property, otherwise None).

time_index()[source]

Returns int being the index into the related time series (if applicable, otherwise None).

time_series_uuid()[source]

Returns the uuid of the related time series (if applicable, otherwise None).

try_reuse()

Look for an equivalent existing RESQML object and modify the uuid of this object if found.

Returns

boolean – True if an equivalent object was found, False if not

Note

by design this method may change this object’s uuid as a side effect

uom()[source]

Returns string being the units of measure (for a continuous property, otherwise None).

write_hdf5(file_name=None, mode='a', expand_const_arrays=False, dtype=None, use_pack=False, chunks=None, compression=None)[source]

Writes the array data to the hdf5 file; not usually called directly.

Parameters
  • file_name (str, optional) – if present, the path of the hdf5 file to use; strongly recommended not to set this argument

  • mode (str, default 'a') – ‘a’ or ‘w’ being the mode to open the hdf5 file in; strongly recommended to use ‘a’

  • expand_const_arrays (bool, default False) – if True and the array is a constant array then a fully populated array is generated and stored (otherwise the constant value is held in xml and no hdf5 data is needed)

  • dtype (numpy dtype, optional) – if present, the elemental data type to use when writing the array to hdf5

  • use_pack (bool, default False) – if True, a bool array will be packed along its last axis; this will generally result in hdf5 data that is not readable by non-resqpy applications

  • chunks (str, optional) – if not None, one of ‘auto’, ‘all’, or ‘slice’, controlling hdf5 chunks

  • compression (str, optional) – if not None, one of ‘gzip’ or ‘lzf’ being the hdf5 compression algorithm to be used; gzip gives better compression ratio but is slower

Notes

see the documentation for the convenience method from_array()

title

Citation title

originator

Creator of object. By default, user id.

uuid

Unique identifier