Altimetry

Objects

Altimetry()
Altimetry.read_cmems()
Altimetry.load()
Altimetry.load_single()
Altimetry.load_multiple()
Altimetry.subset_indices_lonlat_box()
Altimetry.quick_plot()
Altimetry.obs_operator()
Altimetry.crps()
Altimetry.difference()
Altimetry.absolute_error()
Altimetry.mean_absolute_error()
Altimetry.root_mean_square_error()
Altimetry.time_mean()
Altimetry.time_std()
Altimetry.time_correlation()
Altimetry.time_covariance()
Altimetry.basic_stats()

Altimetry class

Altimetry()

class Altimetry(Track):

An object for reading, storing and manipulating altimetry data.
Currently the object contains functionality for reading altimetry netCDF
data from the CMEMS database. This is the default for initialisation.

Data should be stored in an xarray.Dataset, in the form:

* Date Format Overview *

    1. A single dimension (time).
    2. Three coordinates: time, latitude, longitude. All lie on the 'time'
       dimension.
    3. Observed variable DataArrays on the time dimension.

There are currently no naming conventions for the variables however
examples from the CMEMS database include sla_filtered, sla_unfiltered and
mdt (mean dynamic topography).

* Methods Overview *

    *Initialisation and File Reading*
    -> __init__(): Initialises an ALTIMETRY object.
    -> read_cmems(): Reads data from a CMEMS netCDF file.

    *Plotting*
    -> quick_plot(): Makes a quick along-track plot of specified data.

    *Model Comparison*
    -> obs_operator(): For interpolating model data to this object.
    -> cprs(): Calculates the CRPS between a model and obs variable.
    -> difference(): Differences two specified variables
    -> absolute_error(): Absolute difference, two variables
    -> mean_absolute_error(): MAE between two variables
    -> root_mean_square_error(): RMSE between two variables
    -> time_mean(): Mean of a variable in time
    -> time_std(): St. Dev of a variable in time
    -> time_correlation(): Correlation between two variables
    -> time_covariance(): Covariance between two variables
    -> basic_stats(): Calculates multiple of the above metrics.

Altimetry.read_cmems()

def Altimetry.read_cmems(self, file_path, multiple):

Read file.

Args:
                file_path (str): path to data file
                multiple (boolean): True if reading multiple files otherwise False

Altimetry.load()

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

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

Args:
                file_or_dir (str) : file name 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]

Altimetry.load_single()

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

Loads a single file into object's dataset variable.

Args:
                file (str) : file name or directory to multiple files.
                chunks (dict) : Chunks to use in Dask [default None]

Altimetry.load_multiple()

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

Loads multiple files from directory into dataset variable.

Args:
                directory_to_files (str) : directory path to multiple files.
                chunks (dict) : Chunks to use in Dask [default None]

Altimetry.subset_indices_lonlat_box()

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

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

Keyword arguments:
lon                -- Longitudes, 1D or 2D.
lat                -- Latitudes, 1D or 2D
lonbounds -- Array of form [min_longitude=-180, max_longitude=180]
latbounds -- Array of form [min_latitude, max_latitude]

return: Indices corresponding to datapoints inside specified box

Altimetry.quick_plot()

def Altimetry.quick_plot(self, color_var_str=None):

Quick plot

Altimetry.obs_operator()

def Altimetry.obs_operator(self, model, mod_var_name, time_interp=nearest, model_mask=None):

For interpolating a model dataarray onto altimetry locations and times.

For ALTIMETRY, the interpolation is done independently in two steps:
                1. Horizontal space
                2. Time
Model data is taken at the surface if necessary (0 index).

Example usage:
--------------
altimetry.obs_operator(nemo_obj, 'sossheig')

Parameters
----------
model : model object (e.g. NEMO)
mod_var: variable name string to use from model object
time_interp: time interpolation method (optional, default: 'nearest')
                This can take any string scipy.interpolate would take. e.g.
                'nearest', 'linear' or 'cubic'
model_mask : Mask to apply to model data in geographical interpolation
                of model. For example, use to ignore land points.
                If None, no mask is applied. If 'bathy', model variable
                (bathymetry==0) is used. Custom 2D mask arrays can be
                supplied.
Returns
-------
Adds a DataArray to self.dataset, containing interpolated values.

Altimetry.crps()

def Altimetry.crps(self, model_object, model_var_name, obs_var_name, nh_radius=20, time_interp=linear, create_new_object=True):

Comparison of observed variable to modelled using the Continuous
Ranked Probability Score. This is done using this ALTIMETRY object.
This method specifically performs a single-observation neighbourhood-
forecast method.

Parameters
----------
model_object (model) : Model object (NEMO) containing model data
model_var_name (str) : Name of model variable to compare.
obs_var_name (str) : Name of observed variable to compare.
nh_radius (float)                : Neighbourhood radius (km)
time_interp (str)                : Type of time interpolation to use (s)
create_new_obj (bool): If True, save output to new ALTIMETRY obj.
                                                                                Otherwise, save to this obj.

Returns
-------
xarray.Dataset containing times, sealevel and quality control flags

Example Usage
-------
# Compare modelled 'sossheig' with 'sla_filtered' using CRPS
crps = altimetry.crps(nemo, 'sossheig', 'sla_filtered')

Altimetry.difference()

def Altimetry.difference(self, var_str0, var_str1, date0=None, date1=None):

Difference two variables defined by var_str0 and var_str1 between
two dates date0 and date1. Returns xr.DataArray

Altimetry.absolute_error()

def Altimetry.absolute_error(self, var_str0, var_str1, date0=None, date1=None):

Absolute difference two variables defined by var_str0 and var_str1
between two dates date0 and date1. Return xr.DataArray

Altimetry.mean_absolute_error()

def Altimetry.mean_absolute_error(self, var_str0, var_str1, date0=None, date1=None):

Mean absolute difference two variables defined by var_str0 and
var_str1 between two dates date0 and date1. Return xr.DataArray

Altimetry.root_mean_square_error()

def Altimetry.root_mean_square_error(self, var_str0, var_str1, date0=None, date1=None):

Root mean square difference two variables defined by var_str0 and
var_str1 between two dates date0 and date1. Return xr.DataArray

Altimetry.time_mean()

def Altimetry.time_mean(self, var_str, date0=None, date1=None):

Time mean of variable var_str between dates date0, date1

Altimetry.time_std()

def Altimetry.time_std(self, var_str, date0=None, date1=None):

Time st. dev of variable var_str between dates date0 and date1

Altimetry.time_correlation()

def Altimetry.time_correlation(self, var_str0, var_str1, date0=None, date1=None, method=pearson):

Time correlation between two variables defined by var_str0,
var_str1 between dates date0 and date1. Uses Pandas corr().

Altimetry.time_covariance()

def Altimetry.time_covariance(self, var_str0, var_str1, date0=None, date1=None):

Time covariance between two variables defined by var_str0,
var_str1 between dates date0 and date1. Uses Pandas corr().

Altimetry.basic_stats()

def Altimetry.basic_stats(self, var_str0, var_str1, date0=None, date1=None, create_new_object=True):

Calculates a selection of statistics for two variables defined by
var_str0 and var_str1, between dates date0 and date1. This will return
their difference, absolute difference, mean absolute error, root mean
square error, correlation and covariance. If create_new_object is True
then this method returns a new ALTIMETRY object containing statistics,
otherwise variables are saved to the dateset inside this object.