template_project API

template_project.readers.load_dataset(array_name: str, source: str = None, file_list: str | list[str] = None, transport_only: bool = True, data_dir: str | Path | None = None, redownload: bool = False) → list[Dataset][source]

Load raw datasets from a selected AMOC observing array.

Parameters:

  • array_name (str) – The name of the observing array to load. Options are: - ‘rapid’ : RAPID 26N array

  • source (str, optional) – URL or local path to the data source. If None, the reader-specific default source will be used.

  • file_list (str or list of str, optional) – Filename or list of filenames to process. If None, the reader-specific default files will be used.

  • transport_only (bool, optional) – If True, restrict to transport files only.

  • data_dir (str, optional) – Local directory for downloaded files.

  • redownload (bool, optional) – If True, force redownload of the data.

Returns:

List of datasets loaded from the specified array.

Return type:

list of xarray.Dataset

Raises:

ValueError – If an unknown array name is provided.

template_project.readers.load_sample_dataset(array_name: str = 'rapid') → Dataset[source]

Load a sample dataset for quick testing.

Currently supports: - ‘rapid’ : loads the ‘RAPID_26N_TRANSPORT.nc’ file

Parameters:

array_name (str, optional) – The name of the observing array to load. Default is ‘rapid’.

Returns:

A single xarray Dataset from the sample file.

Return type:

xr.Dataset

Raises:

ValueError – If the array_name is not recognised.

template_project.plotters.plot_monthly_transport(ds: Dataset, var: str = 'moc_mar_hc10') → None[source]

Plot original and monthly averaged transport time series.

Parameters:

  • ds (xr.Dataset) – Dataset with a time dimension and a transport variable.

  • var (str, optional) – Name of the variable to plot. Default is “moc_mar_hc10”.

template_project.plotters.show_attributes(data)[source]

Processes an xarray Dataset or a netCDF file, extracts attribute information, and returns a DataFrame with details about the attributes.

Parameters: data (str or xr.Dataset): The input data, either a file path to a netCDF file or an xarray Dataset.

Returns: pandas.DataFrame: A DataFrame containing the following columns:

  • Attribute: The name of the attribute.

  • Value: The value of the attribute.

template_project.plotters.show_variables(data)[source]

Processes an xarray Dataset or a netCDF file, extracts variable information, and returns a styled DataFrame with details about the variables.

Parameters: data (str or xr.Dataset): The input data, either a file path to a netCDF file or an xarray Dataset.

Returns: pandas.io.formats.style.Styler: A styled DataFrame containing the following columns:

  • dims: The dimension of the variable (or “string” if it is a string type).

  • name: The name of the variable.

  • units: The units of the variable (if available).

  • comment: Any additional comments about the variable (if available).

template_project.writers.save_dataset(ds, output_file='../data/test.nc', delete_existing=False, prompt_user=True)[source]

Attempts to save the dataset to a NetCDF file. If a TypeError occurs due to invalid attribute values, it converts the invalid attributes to strings and retries the save operation.

Parameters:

  • (xarray.Dataset) (ds)

  • (str) (output_file)

  • (bool) (prompt_user)

  • (bool)

Returns:

  • bool (True if the dataset was saved successfully, False otherwise.)

  • Based on (https://github.com/pydata/xarray/issues/3743)

template_project.tools.convert_units_var(var_values, current_unit, new_unit, unit_conversion={'Celsius': {'factor': 1, 'units_name': 'degrees_Celsius'}, 'Pa': {'factor': 0.0001, 'units_name': 'dbar'}, 'S m-1': {'factor': 0.1, 'units_name': 'mS cm-1'}, 'S/m': {'factor': 0.1, 'units_name': 'mS/cm'}, 'cm': {'factor': 0.01, 'units_name': 'm'}, 'cm s-1': {'factor': 0.01, 'units_name': 'm s-1'}, 'cm/s': {'factor': 0.01, 'units_name': 'm/s'}, 'dbar': {'factor': 10000, 'units_name': 'Pa'}, 'degrees_Celsius': {'factor': 1, 'units_name': 'Celsius'}, 'g m-3': {'factor': 0.001, 'units_name': 'kg m-3'}, 'kg m-3': {'factor': 1000, 'units_name': 'g m-3'}, 'km': {'factor': 1000, 'units_name': 'm'}, 'm': {'factor': 100, 'units_name': 'cm'}, 'm s-1': {'factor': 100, 'units_name': 'cm s-1'}, 'm/s': {'factor': 100, 'units_name': 'cm/s'}, 'mS cm-1': {'factor': 10, 'units_name': 'S m-1'}, 'mS/cm': {'factor': 10, 'units_name': 'S/m'}})[source]

Convert the units of variables in an xarray Dataset to preferred units. This is useful, for instance, to convert cm/s to m/s.

Parameters:

  • (xarray.Dataset) (ds)

  • (list) (preferred_units)

  • (dict) (unit_conversion)

  • string (Each key is a unit) –

    • ‘factor’: The factor to multiply the variable by to convert it.

    • ’units_name’: The new unit name after conversion.

  • with (and each value is a dictionary) –

    • ‘factor’: The factor to multiply the variable by to convert it.

    • ’units_name’: The new unit name after conversion.

Returns:

xarray.Dataset

Return type:

The dataset with converted units.

template_project.tools.reformat_units_var(ds, var_name, unit_format={'S/m': 'S m-1', 'cm/s': 'cm s-1', 'degrees_Celsius': 'Celsius', 'g/m^3': 'g m-3', 'm/s': 'm s-1', 'm^3/s': 'Sv', 'meters': 'm'})[source]

Renames units in the dataset based on the provided dictionary for OG1.

Parameters:

  • (xarray.Dataset) (ds)

  • (dict) (unit_format)

Returns:

xarray.Dataset

Return type:

The dataset with renamed units.

template_project.utilities.apply_defaults(default_source: str, default_files: List[str]) → Callable[source]

Decorator to apply default values for ‘source’ and ‘file_list’ parameters if they are None.

Parameters:

  • default_source (str) – Default source URL or path.

  • default_files (list of str) – Default list of filenames.

Returns:

A wrapped function with defaults applied.

Return type:

Callable

template_project.utilities.download_file(url: str, dest_folder: str, redownload: bool = False) → str[source]

Download a file from HTTP(S) or FTP to the specified destination folder.

Parameters:

  • url (str) – The URL of the file to download.

  • dest_folder (str) – Local folder to save the downloaded file.

  • redownload (bool, optional) – If True, force re-download of the file even if it exists.

Returns:

The full path to the downloaded file.

Return type:

str

Raises:

ValueError – If the URL scheme is unsupported.

template_project.utilities.get_default_data_dir() → Path[source]
template_project.utilities.resolve_file_path(file_name: str, source: str | Path | None, download_url: str | None, local_data_dir: Path, redownload: bool = False) → Path[source]

Resolve the path to a data file, using local source, cache, or downloading if necessary.

Parameters:

  • file_name (str) – The name of the file to resolve.

  • source (str or Path or None) – Optional local source directory.

  • download_url (str or None) – URL to download the file if needed.

  • local_data_dir (Path) – Directory where downloaded files are stored.

  • redownload (bool, optional) – If True, force redownload even if cached file exists.

Returns:

Path to the resolved file.

Return type:

Path

template_project.utilities.safe_update_attrs(ds: Dataset, new_attrs: Dict[str, str], overwrite: bool = False, verbose: bool = True) → Dataset[source]

Safely update attributes of an xarray Dataset without overwriting existing keys, unless explicitly allowed.

Parameters:

  • ds (xr.Dataset) – The xarray Dataset whose attributes will be updated.

  • new_attrs (dict of str) – Dictionary of new attributes to add.

  • overwrite (bool, optional) – If True, allow overwriting existing attributes. Defaults to False.

  • verbose (bool, optional) – If True, emit a warning when skipping existing attributes. Defaults to True.

Returns:

The dataset with updated attributes.

Return type:

xr.Dataset