17.2.5.1.2. Data modules

Module for the UngriddedData class

class cis.data_io.ungridded_data.LazyData(data, metadata, data_retrieval_callback=None)

Bases: object

Wrapper (adaptor) class for the different types of possible ungridded data.

add_attributes(attributes)

Add a variable attribute to this data

Parameters:attributes – Dictionary of attribute names (keys) and values.
Returns:
add_history(new_history)

Appends to, or creates, the metadata history attribute using the supplied history string. The new entry is prefixed with a timestamp.

Parameters:new_history – history string
copy_metadata_from(other_data)

Method to copy the metadata from one UngriddedData/Cube object to another

data

This is a getter for the data property. It caches the raw data if it has not already been read. Throws a MemoryError when reading for the first time if the data is too large.

data_flattened

Returns a 1D flattened view (or copy, if necessary) of the data.

long_name
name()

This routine returns the first name property which is not empty out of: _name, standard_name and long_name. If they are all empty it returns an empty string :return: The name of the data object as a string

remove_attribute(key)

Remove a variable attribute from this data

Parameters:key – Attribute key to remove
Returns:
save_data(output_file)
shape
standard_name
units
update_range(range=None)
update_shape(shape=None)
var_name
class cis.data_io.ungridded_data.Metadata(name='', standard_name='', long_name='', shape='', units='', range='', factor='', offset='', missing_value='', calendar='', history='', misc=None)

Bases: object

alter_standard_name(new_standard_name)

Alter the standard name and log an info line to say this is happening if the standard name is not empty. Also changes internal name for metadata or the same.

Parameters:new_standard_name –
classmethod from_CubeMetadata(cube_meta)
static guess_standard_name(name)
summary(offset=5)

Creates a unicode summary of the metadata object

Parameters:offset – The left hand padding to apply to the text
Returns:The summary
class cis.data_io.ungridded_data.UngriddedCoordinates(coords)

Bases: cis.data_io.common_data.CommonData

Wrapper (adaptor) class for the different types of possible ungridded data.

alias

Return an alias for the variable name. This is an alternative name by which this data object may be identified if, for example, the actual variable name is not valid for some use (such as performing a python evaluation).

Returns:The alias
Return type:str
coord(name=None, standard_name=None, long_name=None, attributes=None, axis=None)
Raise:CoordinateNotFoundError
Returns:A single coord given the same arguments as L(coords).
coords(name=None, standard_name=None, long_name=None, attributes=None, axis=None, dim_coords=True)
Returns:A list of coordinates in this UngriddedData object fitting the given criteria
filenames = []
get_all_points()

Returns a HyperPointView of the points.

Returns:HyperPointView of all the data points
get_coordinates_points()
get_non_masked_points()

Returns a HyperPointView for which the default iterator omits masked points.

Returns:HyperPointView of the data points
history
hyper_point(index)
Parameters:index – The index in the array to find the point for
Returns:A hyperpoint representing the data at that point
is_gridded

Returns value indicating whether the data/coordinates are gridded.

lat
lon
var_name

Return the variable name associated with this data object

Returns:The ariable name
x
y
class cis.data_io.ungridded_data.UngriddedData(data, metadata, coords, data_retrieval_callback=None)

Bases: cis.data_io.ungridded_data.LazyData, cis.data_io.common_data.CommonData

Wrapper (adaptor) class for the different types of possible ungridded data.

add_attributes(attributes)

Add a variable attribute to this data

Parameters:attributes – Dictionary of attribute names (keys) and values.
Returns:
add_history(new_history)

Appends to, or creates, the metadata history attribute using the supplied history string. The new entry is prefixed with a timestamp.

Parameters:new_history – history string
alias

Return an alias for the variable name. This is an alternative name by which this data object may be identified if, for example, the actual variable name is not valid for some use (such as performing a python evaluation).

Returns:The alias
Return type:str
coord(name=None, standard_name=None, long_name=None, attributes=None, axis=None)
Raise:CoordinateNotFoundError
Returns:A single coord given the same arguments as L(coords).
coords(name=None, standard_name=None, long_name=None, attributes=None, axis=None, dim_coords=True)
Returns:A list of coordinates in this UngriddedData object fitting the given criteria
coords_flattened
copy()

Create a copy of this UngriddedData object with new data and coordinates so that that they can be modified without held references being affected. Will call any lazy loading methods in the data and coordinates

Returns:Copied UngriddedData object
copy_metadata_from(other_data)

Method to copy the metadata from one UngriddedData/Cube object to another

data

This is a getter for the data property. It caches the raw data if it has not already been read. Throws a MemoryError when reading for the first time if the data is too large.

data_flattened

Returns a 1D flattened view (or copy, if necessary) of the data.

filenames = []
find_standard_coords()

Constructs a list of the standard coordinates. The standard coordinates are latitude, longitude, altitude, air_pressure and time; they occur in the return list in this order.

Returns:list of coordinates or None if coordinate not present
classmethod from_points_array(hyperpoints)

Constuctor for building an UngriddedData object from a list of hyper points

Parameters:hyperpoints – list of HyperPoints
get_all_points()

Returns a HyperPointView of the points.

Returns:HyperPointView of all the data points
get_coordinates_points()

Returns a HyperPointView of the coordinates of points.

Returns:HyperPointView of the coordinates of points
get_non_masked_points()

Returns a HyperPointView for which the default iterator omits masked points.

Returns:HyperPointView of the data points
history
hyper_point(index)
Parameters:index – The index in the array to find the point for
Returns:A hyperpoint representing the data at that point
is_gridded

Returns value indicating whether the data/coordinates are gridded.

lat
lon
long_name
make_new_with_same_coordinates(data=None, var_name=None, standard_name=None, long_name=None, history=None, units=None, flatten=False)

Create a new, empty UngriddedData object with the same coordinates as this one.

Parameters:
  • data – Data to use (if None then defaults to all zeros)
  • var_name – Variable name
  • standard_name – Variable CF standard name
  • long_name – Variable long name
  • history – Data history string
  • units – Variable units
  • flatten – Whether to flatten the data and coordinates (for ungridded data only)
Returns:

UngriddedData instance
name()

This routine returns the first name property which is not empty out of: _name, standard_name and long_name. If they are all empty it returns an empty string :return: The name of the data object as a string

remove_attribute(key)

Remove a variable attribute from this data

Parameters:key – Attribute key to remove
Returns:
save_data(output_file)
shape
standard_name
summary()

Unicode summary of the UngriddedData with metadata of itself and its coordinates

units
update_range(range=None)
update_shape(shape=None)
var_name
x
y
class cis.data_io.ungridded_data.UngriddedDataList(iterable=())

Bases: cis.data_io.common_data.CommonDataList

Class which represents multiple UngriddedData objects (e.g. from reading multiple variables)

add_history(new_history)

Appends to, or creates, the metadata history attribute using the supplied history string. The new entry is prefixed with a timestamp. :param new_history: history string

append(p_object)
append_or_extend(item_to_add)

Append or extend an item to an existing list, depending on whether the item to add is itself a list or not. :param item_to_add: Item to add (may be list or not).

coord(*args, **kwargs)

Call UnGriddedData.coord(*args, **kwargs)() for the first item of data (assumes all data in list has same coordinates)

Parameters:
  • args –
  • kwargs –
Returns:
coords(*args, **kwargs)

Returns all coordinates used in all the data object :return: A list of coordinates in this data list object fitting the given criteria

copy()

Create a copy of this UngriddedDataList with new data and coordinates so that that they can be modified without held references being affected. Will call any lazy loading methods in the data and coordinates

Returns:Copied UngriddedData object
count(value) → integer -- return number of occurrences of value
extend(iterable)
filenames

Get the filenames in this data list

get_non_masked_points()

Returns a list containing a HyperPointViews for which the default iterator omits masked points, for each item in this UngriddedDataList.

Returns:List of HyperPointViews of the data points
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

insert()

L.insert(index, object) – insert object before index

is_gridded

Returns value indicating whether the data/coordinates are gridded.

pop([index]) → item -- remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()

L.reverse() – reverse IN PLACE

save_data(output_file)

Save the UngriddedDataList to a file

Parameters:output_file – output filename
Returns:
set_longitude_range(range_start)

Rotates the longitude coordinate array and changes its values by 360 as necessary to force the values to be within a 360 range starting at the specified value. :param range_start: starting value of required longitude range

sort()

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

var_name

Get the variable names in this list

class cis.data_io.Coord.Coord(data, metadata, axis='')

Bases: cis.data_io.ungridded_data.LazyData

add_attributes(attributes)

Add a variable attribute to this data

Parameters:attributes – Dictionary of attribute names (keys) and values.
Returns:
add_history(new_history)

Appends to, or creates, the metadata history attribute using the supplied history string. The new entry is prefixed with a timestamp.

Parameters:new_history – history string
convert_TAI_time_to_std_time(ref)
convert_datetime_to_standard_time()
convert_julian_to_std_time(calender='standard')
convert_to_std_time(time_stamp_info=None)

Convert this coordinate to standard time. It will use either: the units of the coordinate if it is in the standard ‘x since y’ format; or the first word of the units, combined with the time stamp (if the timestamp is not given an error is thrown).

Parameters:time_stamp_info – the time stamp info from the file, None if it does not exist
copy()

Create a copy of this Coord object with new data so that that they can be modified without held references being affected. This will call any lazy loading methods in the coordinate data

Returns:Copied Coord
copy_metadata_from(other_data)

Method to copy the metadata from one UngriddedData/Cube object to another

data

This is a getter for the data property. It caches the raw data if it has not already been read. Throws a MemoryError when reading for the first time if the data is too large.

data_flattened

Returns a 1D flattened view (or copy, if necessary) of the data.

classmethod from_many_coordinates(coords)

Create a single coordinate object from the concatenation of all of the coordinate objects in the input list, updating the shape as appropriate

Parameters:coords – A list of coordinate objects to be combined
Returns:A single Coord object
long_name
name()

This routine returns the first name property which is not empty out of: _name, standard_name and long_name. If they are all empty it returns an empty string :return: The name of the data object as a string

points

Alias for self.data(), to match iris.coords.Coord.points() interface

Returns:Coordinate data values
remove_attribute(key)

Remove a variable attribute from this data

Parameters:key – Attribute key to remove
Returns:
save_data(output_file)
set_longitude_range(range_start)

Confine the coordinate longitude range to 360 degrees from the range_start value.

Parameters:range_start (float) – Start of the longitude range
shape
standard_name
units
update_range(range=None)
update_shape(shape=None)
var_name
class cis.data_io.Coord.CoordList(*args)

Bases: list

All the functionality of a standard list with added Coord context.

append(other)

Safely add a new coordinate object to the list, this checks for a unique axis and standard_name.

:param Coord other: Other coord to add :raises DuplicateCoordinateError: If the coordinate is not unique in the list

copy()

Create a copy of this CoordList object with new data so that that they can be modified without held references being affected. This will call any lazy loading methods in the coordinate data

Returns:Copied CoordList
count(value) → integer -- return number of occurrences of value
extend()

L.extend(iterable) – extend list by appending elements from the iterable

find_standard_coords()

Constructs a list of the standard coordinates. The standard coordinates are latitude, longitude, altitude, air_pressure and time; they occur in the return list in this order.

Returns:list of coordinates or None if coordinate not present
get_coord(name=None, standard_name=None, long_name=None, attributes=None, axis=None)

Return a single coord fitting the given criteria. This is deliberately very similar to Cube.coord() method to maintain a similar interface and because the functionality is similar. There is no distinction between dimension coordinates and auxilliary coordinates here though.

Parameters:
  • name (string or None) – The standard name or long name or default name of the desired coordinate. If None, does not check for name. Also see, Cube.name.
  • standard_name (string or None) – The CF standard name of the desired coordinate. If None, does not check for standard name.
  • long_name (string or None) – An unconstrained description of the coordinate. If None, does not check for long_name.
  • attributes (dict or None) – A dictionary of attributes desired on the coordinates. If None, does not check for attributes
  • axis (string or None) – The desired coordinate axis, see iris.util.guess_coord_axis(). If None, does not check for axis. Accepts the values ‘X’, ‘Y’, ‘Z’ and ‘T’ (case-insensitive).
Raises CoordinateNotFoundError:
 

If the arguments given do not result in precisely 1 coordinate being matched.
Returns:

A single Coord.
get_coordinates_points()
get_coords(name=None, standard_name=None, long_name=None, attributes=None, axis=None)

Return a list of coordinates in this CoordList fitting the given criteria. This is deliberately very similar to Cube.coords() to maintain a similar interface and because the functionality is similar. There is no distinction between dimension coordinates and auxiliary coordinates here though.

Parameters:
  • name (string or None) – The standard name or long name or default name of the desired coordinate. If None, does not check for name. Also see, Cube.name.
  • standard_name (string or None) – The CF standard name of the desired coordinate. If None, does not check for standard name.
  • long_name (string or None) – An unconstrained description of the coordinate. If None, does not check for long_name.
  • attributes (dict or None) – A dictionary of attributes desired on the coordinates. If None, does not check for attributes
  • axis (string or None) – The desired coordinate axis, see iris.util.guess_coord_axis(). If None, does not check for axis. Accepts the values ‘X’, ‘Y’, ‘Z’ and ‘T’ (case-insensitive).
Returns:

A CoordList of coordinates fitting the given criteria
get_standard_coords(data_len)

Constructs a list of the standard coordinate values. The standard coordinates are latitude, longitude, altitude, time and air_pressure; they occur in the return list in this order. If a standard coordinate has not been found it’s values are returned as a list of length data_len.

Parameters:data_len (int) – Expected length of coordinate data
Returns:list of indexed sequences of coordinate values
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

insert()

L.insert(index, object) – insert object before index

pop([index]) → item -- remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()

L.reverse() – reverse IN PLACE

sort()

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

cis.data_io.gridded_data.load_cube(*args, **kwargs)
cis.data_io.gridded_data.make_from_cube(cube)
class cis.data_io.common_data.CommonData

Bases: object

Interface of common methods implemented for gridded and ungridded data.

alias

Return an alias for the variable name. This is an alternative name by which this data object may be identified if, for example, the actual variable name is not valid for some use (such as performing a python evaluation).

Returns:The alias
Return type:str
filenames = []
get_all_points()

Returns a list-like object allowing access to all points as HyperPoints. The object should allow iteration over points and access to individual points.

Returns:list-like object of data points
get_coordinates_points()

Returns a list-like object allowing access to the coordinates of all points as HyperPoints. The object should allow iteration over points and access to individual points.

Returns:list-like object of data points
get_non_masked_points()

Returns a list-like object allowing access to all points as HyperPoints. The object should allow iteration over non-masked points and access to individual points.

Returns:list-like object of data points
history

Return the associated history of the object

Returns:The history
Return type:str
is_gridded()

Returns value indicating whether the data/coordinates are gridded.

var_name

Return the variable name associated with this data object

Returns:The ariable name
class cis.data_io.common_data.CommonDataList(iterable=())

Bases: list

Interface for common list methods implemented for both gridded and ungridded data

add_history(new_history)

Appends to, or creates, the metadata history attribute using the supplied history string. The new entry is prefixed with a timestamp. :param new_history: history string

append(p_object)
append_or_extend(item_to_add)

Append or extend an item to an existing list, depending on whether the item to add is itself a list or not. :param item_to_add: Item to add (may be list or not).

coords(*args, **kwargs)

Returns all coordinates used in all the data object :return: A list of coordinates in this data list object fitting the given criteria

extend(iterable)
filenames

Get the filenames in this data list

is_gridded

Returns value indicating whether the data/coordinates are gridded.

set_longitude_range(range_start)

Rotates the longitude coordinate array and changes its values by 360 as necessary to force the values to be within a 360 range starting at the specified value. :param range_start: starting value of required longitude range

var_name

Get the variable names in this list