General_utils

Objects

determine_season()
subset_indices_by_distance_balltree()
subset_indices_by_distance()
compare_angles()
cartesian_to_polar()
polar_to_cartesian()
subset_indices_lonlat_box()
calculate_haversine_distance()
remove_indices_by_mask()
reinstate_indices_by_mask()
nearest_indices_2d()
data_array_time_slice()
day_of_week()
nan_helper()

A general utility file.

determine_season()

def determine_season(t):

Determine season (or array of seasons) from a time (Datetime or xarray)
object. Put in an array of times, get out an array of seasons.

subset_indices_by_distance_balltree()

def subset_indices_by_distance_balltree(longitude, latitude, centre_lon, centre_lat, radius, mask=None):

Returns the indices of points that lie within a specified radius (km) of
central latitude and longitudes. This makes use of BallTree.query_radius.

Parameters
----------
longitude : (numpy.ndarray) longitudes in degrees
latitude                : (numpy.ndarray) latitudes in degrees
centre_lon : Central longitude. Can be single value or array of values
centre_lat : Central latitude. Can be single value or array of values
radius                : (float) Radius in km within which to find indices
mask                                : (numpy.ndarray) of same dimension as longitude and latitude.
                                                If specified, will mask out points from the routine.
Returns
-------
                Returns an array of indices corresponding to points within radius.
                If more than one central location is specified, this will be a list
                of index arrays. Each element of which corresponds to one centre.
If longitude is 1D:
                Returns one array of indices per central location
If longitude is 2D:
                Returns arrays of x and y indices per central location.
                ind_y corresponds to row indices of the original input arrays.

subset_indices_by_distance()

def subset_indices_by_distance(longitude, latitude, centre_lon, centre_lat, radius):

This method returns a `tuple` of indices within the `radius` of the
lon/lat point given by the user.
Scikit-learn BallTree is used to obtain indices.
:param longitude: The longitude of the users central point
:param latitude: The latitude of the users central point
:param radius: The haversine distance (in km) from the central point
:return: All indices in a `tuple` with the haversine distance of the
                                central point

compare_angles()

def compare_angles(a1, a2, degrees=True):

# Compares the difference between two angles. e.g. it is 2 degrees between
# 359 and 1 degree. If degrees = False then will treat angles as radians.

cartesian_to_polar()

def cartesian_to_polar(x, y, degrees=True):

# Conversion of cartesian to polar coordinate system
# Output theta is in radians

polar_to_cartesian()

def polar_to_cartesian(r, theta, degrees=True):

# Conversion of polar to cartesian coordinate system
# Input theta must be in radians

subset_indices_lonlat_box()

def subset_indices_lonlat_box(array_lon, array_lat, lon_min, lon_max, lat_min, lat_max):

None

calculate_haversine_distance()

def calculate_haversine_distance(lon1, lat1, lon2, lat2):

# Estimation of geographical distance using the Haversine function.
# Input can be single values or 1D arrays of locations. This
# does NOT create a distance matrix but outputs another 1D array.
# This works for either location vectors of equal length OR a single loc
# and an arbitrary length location vector.
#
# lon1, lat1 :: Location(s) 1.
# lon2, lat2 :: Location(s) 2.

remove_indices_by_mask()

def remove_indices_by_mask(array, mask):

Removes indices from a 2-dimensional array, A, based on true elements of
mask. A and mask variable should have the same shape.

reinstate_indices_by_mask()

def reinstate_indices_by_mask(array_removed, mask, fill_value=unknown):

Rebuilds a 2D array from a 1D array created using remove_indices_by_mask().
False elements of mask will be populated using array_removed. MAsked
indices will be replaced with fill_value

nearest_indices_2d()

def nearest_indices_2d(mod_lon, mod_lat, new_lon, new_lat, mask=None):

Obtains the 2 dimensional indices of the nearest model points to specified
lists of longitudes and latitudes. Makes use of sklearn.neighbours
and its BallTree haversine method. Ensure there are no NaNs in
input longitude/latitude arrays (or mask them using "mask"")

Example Usage
----------
# Get indices of model points closest to altimetry points
ind_x, ind_y = nemo.nearest_indices(altimetry.dataset.longitude,
                                                                                                                                                altimetry.dataset.latitude)
# Nearest neighbour interpolation of model dataset to these points
interpolated = nemo.dataset.isel(x_dim = ind_x, y_dim = ind_y)

Parameters
----------
mod_lon (2D array): Model longitude (degrees) array (2-dimensional)
mod_lat (2D array): Model latitude (degrees) array (2-dimensions)
new_lon (1D array): Array of longitudes (degrees) to compare with model
new_lat (1D array): Array of latitudes (degrees) to compare with model
mask (2D array): Mask array. Where True (or 1), elements of array will
                                                                not be included. For example, use to mask out land in
                                                                case it ends up as the nearest point.

Returns
-------
Array of x indices, Array of y indices

data_array_time_slice()

def data_array_time_slice(data_array, date0, date1):

Takes an xr.DataArray object and returns a new object with times
sliced between dates date0 and date1. date0 and date1 may be a string or
datetime type object.

day_of_week()

def day_of_week(date=None):

Return the day of the week (3 letter str)

nan_helper()

def nan_helper(y):

Helper to handle indices and logical indices of NaNs.

Input:
                - y, 1d numpy array, or xr.DataArray, with possible NaNs
Output:
                - nans, logical indices of NaNs
                - index, a function, with signature indices= index(logical_indices),
                to convert logical indices of NaNs to 'equivalent' indices
Example:
                >>> # linear interpolation of NaNs
                >>> nans, x= nan_helper(y)
                >>> y[nans]= np.interp(x(nans), x(~nans), y[~nans])