Preprocessing functions

Module with preprocessing functions that can be used with batching.

tctrack.preprocessing.read_files(input_files, *, output_file=None, select=None)[source]

Read fields from one or more files.

Parameters:

input_files (str | Sequence[str]) – Input file path(s) to read. glob pattern matching allowed.
output_file (str | None, optional) – Output file to write the loaded fields to.
select (str | None, optional) – Optional field selection for cf.read.

Returns:

The list of fields read from the input files.

Return type:

list[cf.Field]

tctrack.preprocessing.select_time_range(inputs, time_bounds, *, output_file=None)[source]

Combine files in time and select a time range.

Parameters:

inputs (FieldSource) – The file path(s) or fields to use.
time_bounds (tuple[str, str] | tuple[cftime.datetime, cftime.datetime]) – Start and end datetimes. Strings must use the format "YYYY-MM-DD[ HH:MM]". The end bound is open / exclusive.
output_file (str | None, optional) – Output file to write the result to.

Returns:

The list of combined fields.

Return type:

list[cf.Field]

tctrack.preprocessing.separate_variables(input_files, output_files, *, return_order=None)[source]

Split variables into separate files.

Parameters:

input_files (FieldSource) – The file path(s) or fields to use.
output_files (dict[str, str]) – Mapping from NetCDF variable name to output file path.
return_order (Sequence[str] | None) – Optional list of NetCDF variable names to specify the order of the returned fields.

Returns:

The list of fields read from the input files.

Return type:

list[cf.Field]

tctrack.preprocessing.squeeze_field(input_, *, output_file=None)[source]

Remove size-1 dimensions from a field.

Parameters:

input (FieldSource) – A field, file path(s), or FieldSelect describing which field to load.
output_file (str | None, optional) – Output file to write the squeezed field to.

Returns:

The squeezed field.

Return type:

cf.Field

tctrack.preprocessing.flip_axis(input_, axis, *, output_file=None)[source]

Flip (reverse) a field along one or more axes.

Parameters:

input (FieldSource) – A field, file path(s), or FieldSelect describing which field to load.
axis (str | Sequence[str]) – Axis or axes to flip, e.g. "Y" to reverse the latitude order.
output_file (str | None, optional) – Output file to write the flipped field to.

Returns:

The flipped field.

Return type:

cf.Field

tctrack.preprocessing.subsample_field(input_, subspace_kwargs, *, output_file=None, squeeze=False)[source]

Subsample a field using cf.Field.subspace.

Parameters:

input (FieldSource) – A field, file path(s), or FieldSelect describing which field to load.
subspace_kwargs (dict[str, Any]) – Keyword arguments passed to cf.Field.subspace.
output_file (str | None, optional) – Output file to write the result to.
squeeze (bool, optional) – Whether to squeeze size-1 dimensions after subspacing. Default: False.

Returns:

The subsampled field.

Return type:

cf.Field

tctrack.preprocessing.collapse_field(input_, method, axes, *, output_file=None, squeeze=True)[source]

Collapse a field over one or more axes.

Parameters:

input (FieldSource) – A field, file path(s), or FieldSelect describing which field to load.
method (str) – Collapse method passed to cf.Field.collapse. E.g. "mean", "minimum".
axes (str | Sequence[str]) – Axis or axes to collapse over.
output_file (str | None, optional) – Output file to write the collapsed field to.
squeeze (bool, optional) – Whether to squeeze size-1 dimensions after collapsing.

Returns:

The collapsed field.

Return type:

cf.Field

tctrack.preprocessing.calculate_curl_xy(inputs, nc_name, properties, *, output_file=None)[source]

Calculate the curl of x and y vector components.

Parameters:

inputs (list[FieldSource]) – Fields for the x and y vector components.
nc_name (str) – NetCDF variable name for the output field.
properties (dict[str, str]) – Field properties to set on the output.
output_file (str | None, optional) – Output file to write the curl field to.

Returns:

Curl field derived from the two inputs.

Return type:

cf.Field

tctrack.preprocessing.calculate_vorticity(inputs, *, nc_name='vorticity', output_file=None)[source]

Calculate vorticity from colocated velocity fields.

Parameters:

inputs (list[FieldSource]) – Fields for the eastward and northward velocity components.
nc_name (str, optional) – NetCDF variable name for the output field.
output_file (str | None, optional) – Output file to write the vorticity field to.

Returns:

Vorticity field.

Return type:

cf.Field

tctrack.preprocessing.calculate_norm_xy(inputs, nc_name, properties=None, *, output_file=None)[source]

Calculate the norm (magnitude) of x and y vector components.

Parameters:

inputs (list[FieldSource]) – Fields for the x any y vector components.
nc_name (str) – NetCDF variable name for the output field.
properties (dict[str, str] | None, optional) – Field properties to set on the output. This should atleast include standard_name.
output_file (str | None, optional) – Output file to write the norm field to.

Returns:

Norm field derived from the two inputs.

Return type:

cf.Field

tctrack.preprocessing.calculate_wind_speed(inputs, *, nc_name='wind_speed', output_file=None)[source]

Calculate wind speed from colocated velocity fields.

Parameters:

inputs (list[FieldSource]) – Fields for the eastward and northward velocity components.
nc_name (str, optional) – NetCDF variable name for the output field.
output_file (str | None, optional) – Output file to write the wind speed field to.

Returns:

Wind speed field.

Return type:

cf.Field

tctrack.preprocessing.multiply_field(input_, factor, *, output_file=None)[source]

Multiply a field by a constant factor.

Parameters:

input (FieldSource) – A field, file path(s), or FieldSelect describing which field to load.
factor (float) – Constant factor to multiply the field by.
output_file (str | None, optional) – Output file to write the result to.

Returns:

The scaled field.

Return type:

cf.Field

tctrack.preprocessing.set_time_units(input_, units, *, output_file=None)[source]

Set the units (reference date) of the time coordinate of a field.

The coordinate values are converted to the new units so the actual datetimes are unchanged.

Parameters:

input (FieldSource) – A field, file path(s), or FieldSelect describing which field to load.
units (str) – New units for the time coordinate, e.g. "days since 1950-01-01". These must be time reference units compatible with the existing ones.
output_file (str | None, optional) – Output file to write the updated field to.

Returns:

Field with updated time coordinate units.

Return type:

cf.Field

tctrack.preprocessing.replace_fill_value(input_, fill_value, *, output_file=None)[source]

Replace masked values in a field using cf.Field.filled.

Parameters:

input (FieldSource) – A field, file path(s), or FieldSelect describing which field to load.
fill_value (float) – Value for missing data.
output_file (str | None, optional) – Output file to write the updated field to.

Returns:

Field with fill value replaced.

Return type:

cf.Field

tctrack.preprocessing.set_netcdf_info(input_, *, nc_name=None, properties=None, coord_nc_names=None, axis_unlimited=None, output_file=None)[source]

Set NetCDF variable names and properties for a field and its coordinates.

Parameters:

input (FieldSource) – A field, file path(s), or FieldSelect describing which field to load.
nc_name (str | None, optional) – NetCDF variable name for the field. If None the name is left unchanged.
properties (dict[str, str] | None, optional) – Field properties to set, e.g. standard_name, long_name, units.
coord_nc_names (dict[str, str] | None, optional) – Updated NetCDF variable names for coordinates. Keys are the standard names.
axis_unlimited (str | tuple[str, bool] | None, optional) – Set a domain axis as unlimited. Or use a tuple with the axis as the first value and a boolean as the second (False removes the unlimited status).
output_file (str | None, optional) – Output file to write the updated field to.

Returns:

Field with updated NetCDF variable names and properties.

Return type:

cf.Field

tctrack.preprocessing.regrid_to_field(input_, target, *, output_file=None, method='linear')[source]

Regrid a field onto the grid of another field or domain.

Parameters:

input (FieldSource) – A field, file path(s), or FieldSelect describing the field to regrid.
target (FieldSource | cf.Domain) – Target field or domain that supplies the destination grid.
output_file (str | None, optional) – Output file to write the regridded field to.
method (str, optional) – Regridding method passed to cf.Field.regrids.

Returns:

Regridded field.

Return type:

cf.Field

tctrack.preprocessing.regrid_to_lat_lon(input_, latitude, longitude, *, output_file=None, method='linear')[source]

Regrid a field onto a latitude-longitude grid.

Parameters:

input (FieldSource) – A field, file path(s), or FieldSelect describing the field to regrid.
latitude (np.ndarray) – Latitude coordinate values for the target grid.
longitude (np.ndarray) – Longitude coordinate values for the target grid.
output_file (str | None, optional) – Output file to write the regridded field to.
method (str, optional) – Regridding method passed to cf.Field.regrids.

Returns:

Regridded field on the requested latitude-longitude grid.

Return type:

cf.Field

tctrack.preprocessing.gaussian_grid(n)[source]

Create regular Gaussian latitude and longitude coordinates.

Parameters:: n (int) – Number of latitude points per hemisphere.
Returns:: Latitude and longitude coordinate arrays.
Return type:: tuple[np.ndarray, np.ndarray]

tctrack.preprocessing.regrid_to_gaussian(input_, n, *, output_file=None, method='linear')[source]

Regrid a field onto a regular Gaussian grid.

Parameters:

input (FieldSource) – A field, file path(s), or FieldSelect describing the field to regrid.
n (int) – Number of latitude points per hemisphere for the target gaussian grid.
output_file (str | None, optional) – Output file to write the regridded field to.
method (str, optional) – Regridding method passed to cf.Field.regrids.

Returns:

Regridded field on the Gaussian grid.

Return type:

cf.Field

tctrack.preprocessing.FieldSource: TypeAlias = str | collections.abc.Sequence[str] | tctrack.preprocessing.FieldSelect | cf.field.Field | list[cf.field.Field]

Type alias for the allowed sources for cf.Field arguments.

The cf.Field can be passed directly or using the path(s) CF-NetCDF file(s). If the file(s) contain multiple fields then FieldSelect should be used to specify which to use.

class tctrack.preprocessing.FieldSelect[source]

Dictionary containing the file name(s) plus the NetCDF variable name to select.

This is necessary for choosing a variable from files which contain multiple.

Parameters:

files (str | Sequence[str]) – Input file path(s) to read from. glob pattern matching allowed.
var_name (str) – NetCDF variable name to select from the input files.