17.2.5.7. CIS utility functions¶

17.2.5.7.1. cis.time_util module¶

Utilities for converting time units

cis.time_util.calculate_mid_time(t1, t2)¶

Find the mid time between two times expressed as floats

Parameters:	t1 – a time represented as a float t2 – a time in the same representation as t1
Returns:	a float representing the time between t1 and t2

cis.time_util.convert_cube_time_coord_to_standard_time(cube)¶: Converts the time coordinate from the one in the cube to one based on a standard time unit. :param cube: cube to modify :return: the cube

cis.time_util.convert_cube_time_coord_to_standard_time_assuming_gregorian_calendar(cube)¶

Converts the time coordinate from the one in the cube to one based on a standard time unit.

This approach assumes that source date is valid as a date in the calendar set for the standard time unit (Gregorian) which will not always be true. :param cube: cube to modify :return: the cube

cis.time_util.convert_datetime_to_std_time(dt)¶

cis.time_util.convert_days_since_to_std_time(days, ref)¶

cis.time_util.convert_julian_date_to_std_time(julian_date, calender='standard')¶

cis.time_util.convert_julian_date_to_std_time_array(julian_time_array, calender='standard')¶

cis.time_util.convert_obj_to_standard_date_array(time_array)¶

cis.time_util.convert_sec_since_to_std_time(seconds, ref)¶

Convert a number of seconds since a given reference datetime to a number of days since our standard time. This in principle could avoid the intermediate step converting to a datetime object except we don’t know which calender the reference is on, e.g. it could be a 360 day calendar

Parameters:	seconds – ref –
Returns:

cis.time_util.convert_sec_since_to_std_time_array(tai_time_array, ref)¶

cis.time_util.convert_std_time_to_datetime(std_time)¶

cis.time_util.convert_time_since_to_std_time(time_array, units)¶

cis.time_util.convert_time_using_time_stamp_info_to_std_time(time_array, units, time_stamp_info=None)¶: Convert the time using time stamp info and the first word of the units :param time_array: the time array to convert :param units: the units of the array (e.g. day or Days from the file time reference 2012-12-12) :param time_stamp_info: the time stamp to use for the convertion :return: converted data

17.2.5.7.2. cis.utils module¶

class cis.utils.OrderedSet(iterable=None)¶

Bases: _abcoll.MutableSet

From http://code.activestate.com/recipes/576694/

add(key)¶

discard(key)¶

pop(last=True)¶

cis.utils.add_element_to_list_in_dict(my_dict, key, value)¶

cis.utils.add_file_prefix(prefix, filepath)¶

Add a prefix to a filename taking into account any path that might be present before that actual filename

Parameters:	prefix – A string to prefix the filename with filepath – Filename, optionally including path
Returns:	A string with the full path to the prefixed file

cis.utils.add_to_list_if_not_none(item, list)¶

Add a value to a list if it is not None

Parameters:	item – the item to add list – the list to append it to
Returns:	nothing

cis.utils.apply_intersection_mask_to_two_arrays(array1, array2)¶

Ensure two (optionally) masked arrays have the same mask. If both arrays are masked the intersection of the masks is used. If one array is masked and the other is not, the mask from the masked array is applied to the unmasked array. If neither array is masked then both arrays are returned as masked arrays with an empty mask.

Parameters:	array1 – An (optionally masked) array array2 – Another (optionally masked) array
Returns:	Two masked arrays with a common mask

cis.utils.apply_mask_to_numpy_array(in_array, mask)¶

Element-wise ORs the mask with the mask of the array. If the mask masks no elements, no change is made. If the array is not masked, it is converted to a masked array.

Parameters:	in_array (numpy array or masked array) – input array mask (numpy array of boolean) – mask

cis.utils.array_equal_including_nan(array1, array2)¶

Parameters:	array1 – A numpy array array2 – Another numpy array (can be of a different shape)
Returns:	True or false if the arrays are equal, including NaNs.

cis.utils.calculate_histogram_bin_edges(data, axis, user_range, step, log_scale=False)¶

Parameters:	data – A numpy array axis – The axis on which the data will be plotted. Set to “x” for histogram2d user_range – A dictionary containing the min and max values for the edges specified by the user. The data min and max is used if the user did not specify step – The distance between each bin edge/the width of each bin
Returns:	An array containing a list of bin edges (i.e. when each bin starts and ends)

cis.utils.concatenate(arrays, axis=0)¶

Concatenate a list of numpy arrays into one larger array along the axis specified (the default axis is zero). If any of the arrays are masked arrays then the returned array will be a masked array with the correct mask, otherwise a numpy array is returned.

Parameters:	arrays – A list of numpy arrays (masked or not) axis – The axis along which to concatenate (the default is 0)
Returns:	The concatenated array

cis.utils.convert_array_type(array, new_type, operation, *args, **kwargs)¶

cis.utils.convert_masked_array_type(masked_array, new_type, operation, *args, **kwargs)¶

cis.utils.convert_numpy_array(array, new_type, operation, *args, **kwargs)¶

cis.utils.copy_attributes(source, dest)¶

Copy all attributes from one object to another

Parameters:	source – Object to copy attributes from dest – Object to copy attributes to
Returns:	None

cis.utils.create_masked_array_for_missing_data(data, missing_val)¶

cis.utils.create_masked_array_for_missing_values(data, missing_values)¶

cis.utils.deprecated(func)¶

This is a decorator which can be used to mark functions as deprecated. It will result in a warning being emitted when the function is used.

Taken from http://code.activestate.com/recipes/391367-deprecated/

cis.utils.dimensions_equal(dimensions, other_dimensions)¶

Check to see if two dimensions are the same (contain the same variables in the same order)

Parameters:	dimensions – dimension list other_dimensions – other dimension list

cis.utils.expand_1d_to_2d_array(array_1d, length, axis=0)¶

General utility routine to ‘extend a 1D array into a 2D array by duplicating the data along a given ‘axis’ (default is 0) of size ‘length’.

Examples:

>>> a = np.array([1, 2, 3, 4])
>>> expand_1d_to_2d_array(a, 4, axis=0)
[[1 2 3 4]
 [1 2 3 4]
 [1 2 3 4]
 [1 2 3 4]]

>>> a = np.array([1, 2, 3, 4])
>>> expand_1d_to_2d_array(a, 4, axis=1)
[[1 1 1 1]
 [2 2 2 2]
 [3 3 3 3]
 [4 4 4 4]]

Parameters:	array_1d – length – axis –
Returns:

cis.utils.find_longitude_wrap_start(x_variable, x_range, packed_data_items)¶

cis.utils.fix_longitude_range(lons, range_start)¶

Shifts longitude values by +/- 360 to fit within a 360 degree range starting at a specified value. It is assumed that a no shifts larger than 360 are needed.

Parameters:	lons – numpy array of longitude values range_start – longitude at start of 360 degree range into which values are required to fit
Returns:	array of fixed longitudes

cis.utils.get_class_name(cls)¶

Returns the qualified class name of a class.

Parameters:	cls – class
Returns:	class name

cis.utils.get_coord(data_object, variable, data)¶

Find a specified coord

Parameters:	data_object – variable – data –
Returns:

cis.utils.guess_coord_axis(coord)¶

Returns X, Y, Z or T corresponding to longitude, latitude, altitude or time respectively if the coordinate can be determined to be one of these (based on the standard name only, in this implementation).

This is intended to be similar to iris.util.guess_coord_axis.

cis.utils.haversine(lat, lon, lat2, lon2)¶: Computes the Haversine distance between two points

cis.utils.index_iterator(shape)¶

Iterates over the indexes of a multi-dimensional array of a specified shape. The last index changes most rapidly.

Parameters:	shape – sequence of array dimensions
Returns:	yields tuples of array indexes

cis.utils.index_iterator_for_non_masked_data(shape, points)¶

Iterates over the indexes of a multi-dimensional array of a specified shape. The last index changes most rapidly.

Parameters:	shape – sequence of array dimensions
Returns:	yields tuples of array indexes

cis.utils.index_iterator_nditer(shape, points)¶

Iterates over the indexes of a multi-dimensional array of a specified shape. The last index changes most rapidly.

Parameters:	shape – sequence of array dimensions
Returns:	yields tuples of array indexes

cis.utils.isnan(number)¶

cis.utils.listify(item)¶

If item is not a list, return it as a list

Parameters:	item – Item which may or may not be a list
Returns:	List

cis.utils.log_memory_profile(location)¶

Write the total memory to the log as debug message

Parameters:	location – location in the program where the memory measurement was taken
Returns:	nothing

cis.utils.parse_distance_with_units_to_float_km(distance)¶

Parse a string such as ‘10km’ or ‘1.0e3m’ to a distance in km

Parameters:	distance – string to parse
Returns:	A distance in km

cis.utils.parse_distance_with_units_to_float_m(distance)¶

Parse a string such as ‘10km’ or ‘1.0e3m’ to a distance in m

Parameters:	distance – string to parse
Returns:	A distance in m

cis.utils.parse_key_val_list(input_list)¶

Takes list of keyword value strings (seperated by =) and returns a dictionary with those keys and values NOTE if a key has no value, the key is stored and given the value True

Parameters:	input_list – A list of strings which are keyword value pairs separated by =
Returns:	A dictionary of the keywords and values

cis.utils.parse_key_val_string(arguments, separator)¶

Takes a (comma) separated list of keyword value pairs (separated by =) and returns a dictionary with those keys and values

Parameters:	arguments – A string which is a separated list of keyword value pairs separator – String which is used to split the string into a list
Returns:	A dictionary of the keywords and values

cis.utils.remove_file_prefix(prefix, filepath)¶

Remove a prefix from a filename, taking into account any path that might be present before that actual filename

Parameters:	prefix – The prefix to remove filepath – Filename, optional including path
Returns:	A string with the full path to the un-prefixed file

cis.utils.set_cube_standard_name_if_valid(cube, standard_name)¶

Set a cube’s standard name if it is a valid CF compliant name, otherwise set it to None

Parameters:	cube – Cube to set standard name on standard_name – Standard name to set
Returns:

cis.utils.split_into_float_and_units(measurement)¶

Split a string such as ‘1000m’ or ‘1.0e3’ to a value and, optionally, units

Parameters:	distance – string to parse
Returns:	A distance in m

cis.utils.unpack_data_object(data_object, x_variable, y_variable, x_wrap_start)¶: :param data_object A cube or an UngriddedData object :return: A dictionary containing x, y and data as numpy arrays

cis.utils.wrap_longitude_coordinate_values(x_min, x_max)¶