Coast

Docstrings for the Coast class

Objects

setup_dask_client()
Coast()
Coast.load()
Coast.load_single()
Coast.load_multiple()
Coast.load_dataset()
Coast.set_dimension_mapping()
Coast.set_variable_mapping()
Coast.set_grid_ref_attribute()
Coast.set_dimension_names()
Coast.set_variable_names()
Coast.set_variable_grid_ref_attribute()
Coast.copy()
Coast.isel()
Coast.sel()
Coast.rename()
Coast.subset()
Coast.subset_as_copy()
Coast.distance_between_two_points()
Coast.subset_indices_by_distance()
Coast.subset_indices_lonlat_box()
Coast.calculate_haversine_distance()
Coast.get_subset_as_xarray()
Coast.get_2d_subset_as_xarray()
Coast.plot_simple_2d()
Coast.plot_cartopy()
Coast.plot_movie()

The coast class is the main access point into this package.

setup_dask_client()


def setup_dask_client(workers=2, threads=2, memory_limit_per_worker=2GB):

None

Coast()

class Coast():
None
Coast.load()

def Coast.load(self, file_or_dir, chunks=None, multiple=False):

Loads a file into a COAsT object's dataset variable using xarray.

Args:
                file_or_dir (str): file name, OPeNDAP accessor, or directory to multiple files.
                chunks (dict): Chunks to use in Dask [default None].
                multiple (bool): If true, load in multiple files from directory. If false load a single file [default False].

Coast.load_single()

def Coast.load_single(self, file, chunks=None):

Loads a single file into COAsT object's dataset variable.

Args:
                file (str): Input file.
                chunks (Dict): Chunks to use in Dask [default None].

Coast.load_multiple()

def Coast.load_multiple(self, directory_to_files, chunks=None):

Loads multiple files from directory into dataset variable.

Args:
                directory_to_files (str):
                chunks (Dict): Chunks to use in Dask [default None].

Coast.load_dataset()

def Coast.load_dataset(self, dataset):

Loads a dataset.

Args:
                dataset (xr.Dataset): Dataset to load.

Coast.set_dimension_mapping()

def Coast.set_dimension_mapping(self):

Set mapping of dimensions.

Coast.set_variable_mapping()

def Coast.set_variable_mapping(self):

Set mapping of variable.

Coast.set_grid_ref_attribute()

def Coast.set_grid_ref_attribute(self):

Set grid reference attribute.

Coast.set_dimension_names()

def Coast.set_dimension_names(self, dim_mapping):

Relabel dimensions in COAsT object xarray.dataset to ensure consistent naming throughout the COAsT package.

Args:
                dim_mapping (Dict): keys are dimension names to change and values new dimension names.

Coast.set_variable_names()

def Coast.set_variable_names(self, var_mapping):

Relabel variables in COAsT object xarray.dataset to ensure consistent naming throughout the COAsT package.

Args:
                var_mapping (Dict): keys are variable names to change and values are new variable names

Coast.set_variable_grid_ref_attribute()

def Coast.set_variable_grid_ref_attribute(self, grid_ref_attr_mapping):

Set attributes for variables to access within package and set grid attributes to identify which grid variable is associated with.

Args:
                grid_ref_attr_mapping (Dict): Dict containing mappings.

Coast.copy()

def Coast.copy(self):

Method to copy self.

Coast.isel()

def Coast.isel(self, indexers=None, drop=False, **kwargs):

Indexes COAsT object along specified dimensions using xarray isel.

Input is of same form as xarray.isel. Basic use, hand in either:
1. dictionary with keys = dimensions, values = indices
2. **kwargs of form dimension = indices.

Args:
                indexers (Dict): A dict with keys matching dimensions and values given by integers, slice objects or arrays.
                drop (bool): If drop=True, drop coordinates variables indexed by integers instead of making them scalar.
                **kwargs (Any): The keyword arguments form of indexers. One of indexers or indexers_kwargs must be provided.

Coast.sel()

def Coast.sel(self, indexers=None, drop=False, **kwargs):

Indexes COAsT object along specified dimensions using xarray sel.

Input is of same form as xarray.sel. Basic use, hand in either:
                1. Dictionary with keys = dimensions, values = indices
                2. **kwargs of form dimension = indices

Args:
                indexers (Dict): A dict with keys matching dimensions and values given by scalars, slices or arrays of tick labels.
                drop (bool): If drop=True, drop coordinates variables in indexers instead of making them scalar.
                **kwargs (Any): The keyword arguments form of indexers. One of indexers or indexers_kwargs must be provided.

Coast.rename()

def Coast.rename(self, rename_dict, **kwargs):

Rename dataset.

Args:
                rename_dict (Dict): Dictionary whose keys are current variable or dimension names and whose values are the desired names.
                **kwargs (Any): Keyword form of name_dict. One of name_dict or names must be provided.

Coast.subset()

def Coast.subset(self, **kwargs):

Subsets all variables within the dataset inside self (a COAsT object).

Input is a set of keyword argument pairs of the form: dimension_name = indices.
The entire object is then subsetted along this dimension at indices

Args:
                **kwargs (Any): The keyword arguments form of indexers. One of indexers or indexers_kwargs must be provided.

Coast.subset_as_copy()

def Coast.subset_as_copy(self, **kwargs):

Similar to COAsT.subset() however applies the subsetting to a copy of the original COAsT object.

This subsetted copy is then returned.Useful for preserving the original object whilst creating smaller subsetted object copies.

Args:
                **kwargs (Any): The keyword arguments form of indexers. One of indexers or indexers_kwargs must be provided.

Coast.distance_between_two_points()

def Coast.distance_between_two_points(self):

None

Coast.subset_indices_by_distance()

def Coast.subset_indices_by_distance(self, centre_lon, centre_lat, radius):

This method returns a `tuple` of indices within the `radius` of the lon/lat point given by the user.

Distance is calculated as haversine - see `self.calculate_haversine_distance`.

Args:
                centre_lon (float): The longitude of the users central point.
                centre_lat (float): The latitude of the users central point.
                radius (float): The haversine distance (in km) from the central point.

Return:
                Tuple[xr.DataArray, xr.DataArray]: All indices in a `tuple` with the haversine distance of the central point.

Coast.subset_indices_lonlat_box()

def Coast.subset_indices_lonlat_box(self, lonbounds, latbounds):

Generates array indices for data which lies in a given lon/lat box.

Args:
                lonbounds: Longitude boundaries. List of form [min_longitude=-180, max_longitude=180].
                latbounds: Latitude boundaries. List of form [min_latitude, max_latitude].

Returns:
                np.ndarray: Indices corresponding to datapoints inside specified box.

Coast.calculate_haversine_distance()
@staticmethod
def Coast.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 location and an arbitrary length location vector.

Args:
                lon1 (Any): Angles in degrees.
                lat1 (Any): Angles in degrees.
                lon2 (Any): Angles in degrees.
                lat2 (Any): Angles in degrees.

Returns:
                float: Haversine distance between points.

Coast.get_subset_as_xarray()

def Coast.get_subset_as_xarray(self, var, points_x, points_y, line_length=None, time_counter=0):

This method gets a subset of the data across the x/y indices given for the chosen variable.

Setting time_counter to None will treat `var` as only having 3 dimensions depth, y, x
there is a check on `var` to see the size of the time_counter, if 1 then time_counter is fixed to index 0.

Args:
                var (str): The name of the variable to get data from.
                points_x (slice): A list/array of indices for the x dimension.
                points_y (slice): A list/array of indices for the y dimension.
                line_length (int): The length of your subset (assuming simple line transect). TODO This is unused.
                time_counter (int): Which time slice to get data from, if None and the variable only has one a time
                                channel of length 1 then time_counter is fixed too an index of 0.

Returns:
                xr.DataArray: Data across all depths for the chosen variable along the given indices.

Coast.get_2d_subset_as_xarray()

def Coast.get_2d_subset_as_xarray(self, var, points_x, points_y, line_length=None, time_counter=0):

Get 2d subset as an xarray.

Args:
                var (str): Member of dataset.
                points_x (slice): Keys matching dimensions.
                points_y (slice): Keys matching dimensions.
                line_length (int): Unused.
                time_counter (int): Time counter.

Return:
                xr.Dataset: Subset.

Coast.plot_simple_2d()

def Coast.plot_simple_2d(self, x, y, data, cmap, plot_info):

This is a simple method that will plot data in a 2d. It is a wrapper for matplotlib's 'pcolormesh' method.

`cmap` and `plot_info` are required to run this method, `cmap` is passed directly to `pcolormesh`.
`plot_info` contains all the required information for setting the figure;
                - ylim
                - xlim
                - clim
                - title
                - fig_size
                - ylabel

Args:
                x (xr.Variable): The variable contain the x axis information.
                y (xr.Variable): The variable contain the y axis information.
                data (xr.DataArray): the DataArray a user wishes to plot.
                cmap (matplotlib.cm): Matplotlib color map.
                plot_info (Dict): Dict containing all the required information for setting the figure.

Coast.plot_cartopy()

def Coast.plot_cartopy(self, var, plot_var, params, time_counter=0):

Plot cartopy.

Coast.plot_movie()

def Coast.plot_movie(self):

Plot movie.


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