Profile_analysis

Docstrings for the Profile_analysis class

Objects

ProfileAnalysis()
ProfileAnalysis.depth_means()
ProfileAnalysis.bottom_means()
ProfileAnalysis.determine_mask_indices()
ProfileAnalysis.mask_means()
ProfileAnalysis.difference()
ProfileAnalysis.interpolate_vertical()
ProfileAnalysis.average_into_grid_boxes()

Profile Class

ProfileAnalysis()

class ProfileAnalysis(Indexed):
A set of analysis routines suitable for datasets in a Profile object.
See individual docstrings in each method for more info.
ProfileAnalysis.depth_means()
@classmethod
def ProfileAnalysis.depth_means(cls, profile, depth_bounds):

Calculates a mean of all variable data that lie between two depths.
Returns a new Profile() object containing the meaned data

INPUTS:
dataset (Dataset)                : A dataset from a Profile object.
depth_bounds (Tuple) : A tuple of length 2 describing depth bounds
                                                                                                Should be of form: (lower, upper) and in metres

ProfileAnalysis.bottom_means()
@classmethod
def ProfileAnalysis.bottom_means(cls, profile, layer_thickness, depth_thresholds=unknown):

Averages profile data in some layer above the bathymetric depth. This
routine requires there to be a 'bathymetry' variable in the Profile dataset.
It can apply a constant averaging layer thickness across all profiles
or a bespoke thickness dependent on the bathymetric depth. For example,
you may want to define the 'bottom' as the average of 100m above the
bathymetry in very deep ocean but only 10m in the shallower ocean.
If there is no data available in the layer specified (e.g. CTD cast not
deep enough or model bathymetry wrong) then it will be NaN

To apply constant thickness, you only need to provide a value (in metre)
for layer_thickness. For different thicknesses, you also need to give
depth_thresholds. The last threshold must always be np.inf, i.e. all
data below a specific bathymetry depth.

For example, to apply 10m to everywhere <100m, 50m to 100m -> 500m and
100m elsewhere, use:

                layer_thickness = [10, 50, 100]
                depth_thresholds = [100, 500, np.inf]

The bottom bound is always assumed to be 0.

*NOTE: If time related issues arise, then remove any time variables
from the profile dataset before running this routine.

INPUTS:
layer_thickness (array) : A scalar layer thickness or list of values
depth_thresholds (array) : Optional. List of bathymetry thresholds.

OUTPUTS:
New profile object containing bottom averaged data.

ProfileAnalysis.determine_mask_indices()
@classmethod
def ProfileAnalysis.determine_mask_indices(cls, profile, mask_dataset):

Determines whether each profile is within a mask (region) or not.
These masks should be in Dataset form, as returned by
Mask_maker().make_mask_dataset(). I.E, each mask
should be a 2D array with corresponding 2D longitude and latitude
arrays. Multiple masks should be stored along a dim_mask dimension.

Parameters
----------
dataset : xarray.Dataset
                A dataset from a profile object
mask_dataset : xarray.Dataset
                Dataset with dimensions (dim_mask, x_dim, y_dim).
                Should contain longitude, latitude and mask. Mask has dimensions
                (dim_mask, y_dim, x_dim). Spatial dimensions should align with
                longitude and latitude

Returns
-------
Dataset describing which profiles are in which mask/region.
Ready for input to Profile.mask_means()

ProfileAnalysis.mask_means()
@classmethod
def ProfileAnalysis.mask_means(cls, profile, mask_indices):

Averages all data inside a given profile dataset across a regional mask
or for multiples regional masks.

Parameters
----------
dataset : xarray.Dataset
                The profile dataset to average.
mask_indices : xarray.Dataset
                Describes which profiles are in which region. Returned from
                profile_analysis.determine_mask_indices().

Returns
-------
xarray.Dataset containing meaned data.

ProfileAnalysis.difference()
@classmethod
def ProfileAnalysis.difference(cls, profile1, profile2, absolute_diff=True, square_diff=True):

Calculates differences between all matched variables in two Profile
datasets. Difference direction is dataset1 - dataset2.

Parameters
----------
dataset1 : xarray.Dataset
                First profile dataset
dataset2 : xarray.Dataset
                Second profile dataset
absolute_diff : bool, optional
                Whether to calculate absolute differences. The default is True.
square_diff : bool, optional
                Whether to calculate square differences. The default is True.

Returns
-------
New Profile object containing differenced dataset.
Differences have suffix diff_
Absolute differences have suffix abs_
Square differences have suffic square_

ProfileAnalysis.interpolate_vertical()
@classmethod
def ProfileAnalysis.interpolate_vertical(cls, profile, new_depth, interp_method=linear, print_progress=False):

(04/10/2021)
Author: David Byrne

For vertical interpolation of all profiles within this object. User
should pass an array describing the new depths or another profile object
containing the same number of profiles as this object.

If a 1D numpy array is passed then all profiles will be interpolated
onto this single set of depths. If a xarray.DataArray is passed, it
should have dimensions (id_dim, z_dim) and contain a variable called
depth. This DataArray should contain the same number of profiles as
this object and will map profiles in order for interpolation. If
another profile object is passed, profiles will be mapped and
interpolated onto the other objects depth array.

INPUTS:
new_depth (array or dataArray) : new depths onto which to interpolate
                                                                                                                                see description above for more info.
interp_method (str)                                                : Any scipy interpolation string.

OUTPUTS:
Returns a new PROFILE object containing the interpolated dataset.

ProfileAnalysis.average_into_grid_boxes()
@classmethod
def ProfileAnalysis.average_into_grid_boxes(cls, profile, grid_lon, grid_lat, min_datapoints=1, season=None, var_modifier=):

Takes the contents of this Profile() object and averages each variables
into geographical grid boxes. At the moment, this expects there to be
no vertical dimension (z_dim), so make sure to slice the data out you
want first using isel, Profile.depth_means() or Profile.bottom_means().

INPUTS
grid_lon (array)                : 1d array of longitudes
grid_lat (array)                : 1d array of latitude
min_datapoints (int) : Minimum N of datapoints at which to average
                                                                                                into box. Will return Nan in boxes with smaller N.
                                                                                                NOTE this routine will also return the variable
                                                                                                grid_N, which tells you how many points were
                                                                                                averaged into each box.
season (str)                                : 'DJF','MAM','JJA' or 'SON'. Will only average
                                                                                                data from specified season.
var_modifier (str)                : Suffix to add to all averaged variables in the
                                                                                                output dataset. For example you may want to add
                                                                                                _DJF to all vars if restricting only to winter.

OUTPUTS
COAsT Gridded object containing averaged data.


Last modified November 23, 2022: Updated docstrings from coast repo. (9daee18)