Preprocessing functions

Module with preprocessing functions that can be used with batching.

tctrack.preprocessing.read_files(input_files, *, output_file=None, select=None)

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(input_files, time_bounds, *, output_file=None)

Combine files in time and select a time range.

Parameters:

• input_files (str | Sequence[str]) – Input file path(s) to combine. glob pattern matching allowed.

• time_bounds (tuple[str, str]) – Start and end datetime strings in 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)

Split variables into separate files.

Parameters:

• input_files (str | Sequence[str]) – Input file path(s) to read. glob pattern matching allowed.

• output_files (dict[str, str]) – Mapping from NetCDF variable name to output file path.

Returns:

The list of fields read from the input files.

Return type:

list[cf.Field]

tctrack.preprocessing.subsample_field(input_, subspace_kwargs, *, output_file=None, squeeze=False)

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)

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(input_x, input_y, variable_name, variable_info, *, output_file=None)

Calculate the curl of x and y vector components.

Parameters:

• input_x (FieldSource) – Field for the x component.

• input_y (FieldSource) – Field for the y component.

• variable_name (str) – NetCDF variable name for the output field.

• variable_info (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(input_u, input_v, *, output_file=None)

Calculate vorticity from colocated velocity fields.

Parameters:

• input_u (FieldSource) – Field for the eastward velocity component.

• input_v (FieldSource) – Field for the northward velocity component.

• output_file (str | None, optional) – Output file to write the vorticity field to.

Returns:

Vorticity field.

Return type:

cf.Field

tctrack.preprocessing.replace_fill_value(input_, fill_value, *, output_file=None)

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_variable_name(input_, field_name, *, output_file=None, coord_names=None)

Set NetCDF variable names for a field and, optionally, its coordinates.

Parameters:

• input (FieldSource) – A field, file path(s), or FieldSelect describing which field to load.

• field_name (str) – NetCDF variable name for the field.

• output_file (str | None, optional) – Output file to write the updated field to.

• coord_names (dict[str, str] | None, optional) – Optional updated NetCDF variable names for coordinates. Keys are the standard names.

Returns:

Field with updated NetCDF variable names.

Return type:

cf.Field

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

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')

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)

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')

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

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.