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
-
as_data_frame
(copy=True)¶ Convert an UngriddedCoordinates object to a Pandas DataFrame.
Parameters: copy – Create a copy of the data for the new DataFrame? Default is True. Returns: A Pandas DataFrame representing the data and coordinates. Note that this won’t include any metadata.
-
coord
(name_or_coord=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_or_coord=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
¶
-
time
¶
-
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
-
as_data_frame
(copy=True)¶ Convert an UngriddedData object to a Pandas DataFrame.
Parameters: copy – Create a copy of the data for the new DataFrame? Default is True. Returns: A Pandas DataFrame representing the data and coordinates. Note that this won’t include any metadata.
-
coord
(name_or_coord=None, standard_name=None, long_name=None, attributes=None, axis=None)¶ Raise: CoordinateNotFoundError Returns: A single coord given the same arguments as :method:`coords`.
-
coords
(name_or_coord=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
-
time
¶
-
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).
-
as_data_frame
(copy=True)¶ Convert an UngriddedDataList object to a Pandas DataFrame. Note that UngriddedDataList objects are expected to share coordinates, so only the coordinates from the first object in the list are used.
Parameters: copy – Create a copy of the data for the new DataFrame? Default is True. Returns: A Pandas DataFrame representing the data and coordinates. Note that this won’t include any metadata. Note
This function will copy your data by default. If you have a large array that cannot be copied, make sure it is not masked and use copy=False.
-
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
()¶
-
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 matchiris.coords.Coord.points()
interfaceReturns: 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 addedCoord
context.-
append
(other)¶ Safely add a new coordinate object to the list, this checks for a unique
axis
andstandard_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_or_coord=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_or_coord – - Either:
- The standard name or long name or default name of the desired coordinate.
- Or, a
Coord
instance whose metadata should be used for the search criteria (note that currently only the standard name is compared)
If None, does not check for name. Also see,
Cube.name
. :type name: string or None orCoord
:param standard_name: The CF standard name of the desired coordinate. If None, does not check for standard name. :type standard_name: string or None :param long_name: An unconstrained description of the coordinate. If None, does not check for long_name. :type long_name: string or None :param attributes: A dictionary of attributes desired on the coordinates. If None, does not check for attributes :type attributes: dict or None :param axis: The desired coordinate axis, seeiris.util.guess_coord_axis()
. If None, does not check foraxis. 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_or_coord=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 toCube.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_or_coord – - Either:
- The standard name or long name or default name of the desired coordinate.
- Or, a
Coord
instance whose metadata should be used for the search criteria (note that currently only the standard name is compared)
If None, does not check for name. Also see,
Cube.name
. :type name: string or None orCoord
:param standard_name: The CF standard name of the desired coordinate. If None, does not check for standard name. :type standard_name: string or None :param long_name: An unconstrained description of the coordinate. If None, does not check for long_name. :type long_name: string or None :param attributes: A dictionary of attributes desired on the coordinates. If None, does not check for attributes :type attributes: dict or None :param axis: The desired coordinate axis, seeiris.util.guess_coord_axis()
. If None, does not check foraxis. 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
-
as_data_frame
(copy)¶ Convert a CommonData object to a Pandas DataFrame.
Parameters: copy – Create a copy of the data for the new DataFrame? Default is True. Returns: A Pandas DataFrame representing the data and coordinates. Note that this won’t include any metadata.
-
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
-