plotters

Tools for visualising AMOC time series and transport data.

AMOCatlas plotting functions for visualization and publication figures.

amocatlas.plotters.format_units_for_plotting(units: str) → str[source]

Convert verbose units to concise plotting format.

Translates full unit names to standard abbreviations commonly used in oceanographic plots and publications.

Parameters:: units (str) – Full unit string (e.g., from netCDF attributes).
Returns:: Abbreviated unit string suitable for plot labels.
Return type:: str

Examples

>>> format_units_for_plotting("Sverdrup")
'Sv'
>>> format_units_for_plotting("degrees_north")
'°N'
>>> format_units_for_plotting("degrees_Celsius")
'°C'

amocatlas.plotters.format_variable_name_for_plotting(name: str) → str[source]

Convert variable names with subscripts to matplotlib LaTeX format.

This function translates variable naming patterns that include Greek letters and other subscripts into proper matplotlib LaTeX syntax for publication-quality plots.

Parameters:: name (str) – Variable name that may contain subscript patterns.
Returns:: Variable name formatted with matplotlib LaTeX syntax for subscripts.
Return type:: str

Examples

>>> format_variable_name_for_plotting("MOC_sigma0")
'MOC$_{\\sigma_0}$'
>>> format_variable_name_for_plotting("MOC_z")
'MOC$_{z}$'
>>> format_variable_name_for_plotting("density_theta")
'density$_{\\theta}$'
>>> format_variable_name_for_plotting("temp_ref")
'temp$_{ref}$'

Notes

The function converts patterns with underscores to LaTeX subscripts: - Single letters: MOC_z → MOC$_{z}$ - Greek patterns: MOC_sigma → MOC$_{\sigma}$ - Numbers: MOC_sigma0 → MOC$_{\sigma_0}$ - Multiple parts: Only the first underscore pattern is converted

Matplotlib subscript syntax: $_{text}$

amocatlas.plotters.monthly_resample(da: DataArray) → DataArray[source]: Resample to monthly mean if time is datetime-like and spacing ~monthly. If time is float-year, just pass through as-is (no interpolation).

amocatlas.plotters.plot_all_moc_overlaid_pygmt(osnap_df: DataFrame, rapid_df: DataFrame, move_df: DataFrame, samba_df: DataFrame, filtered: bool = False) → pygmt.Figure[source]

Plot all MOC time series overlaid using separate coordinate systems.

This creates overlaid plots with different y-ranges for MOC data vs SAMBA anomaly, similar to the original moc_tseries_pygmt notebook with shiftflag=False.

Parameters:

osnap_df (pandas.DataFrame) – OSNAP MOC data with ‘time_num’ and ‘moc’/’moc_filtered’.
rapid_df (pandas.DataFrame) – RAPID MOC data with ‘time_num’ and ‘moc’/’moc_filtered’.
move_df (pandas.DataFrame) – MOVE MOC data with ‘time_num’ and ‘moc’/’moc_filtered’.
samba_df (pandas.DataFrame) – SAMBA MOC data with ‘time_num’ and ‘moc’/’moc_filtered’.
filtered (bool, default False) – Whether to plot filtered data (True) or original data (False).

Returns:

PyGMT figure object.

Return type:

pygmt.Figure

Raises:

ImportError – If PyGMT is not installed.

amocatlas.plotters.plot_all_moc_pygmt(osnap_df: DataFrame, rapid_df: DataFrame, move_df: DataFrame, samba_df: DataFrame, filtered: bool = False) → pygmt.Figure[source]

Plot all MOC time series (OSNAP, RAPID, MOVE, SAMBA) in a stacked PyGMT figure.

Parameters:

osnap_df (pandas.DataFrame) – OSNAP MOC data with ‘time_num’ and ‘moc’/’moc_filtered’.
rapid_df (pandas.DataFrame) – RAPID MOC data with ‘time_num’ and ‘moc’/’moc_filtered’.
move_df (pandas.DataFrame) – MOVE MOC data with ‘time_num’ and ‘moc’/’moc_filtered’.
samba_df (pandas.DataFrame) – SAMBA MOC data with ‘time_num’ and ‘moc’/’moc_filtered’.
filtered (bool, default False) – Whether to plot filtered data (True) or original data (False).

Returns:

PyGMT figure object.

Return type:

pygmt.Figure

Raises:

ImportError – If PyGMT is not installed.

Plot 2D AMOC data with time on x-axis and depth/other coordinate on y-axis.

This function creates a color-filled contour plot suitable for visualizing 2D oceanographic data such as MOC streamfunction vs depth and time, or temperature profiles over time.

Parameters:

data (xr.Dataset or xr.DataArray) – Dataset or DataArray containing 2D data to plot.
varname (str, optional) – Variable name to extract from dataset. Not needed if DataArray is passed.
title (str) – Title of the plot.
ylabel (str, optional) – Label for the y-axis (vertical coordinate). If None, inferred from data attributes.
time_limits (tuple of str or pd.Timestamp, optional) – X-axis time limits (start, end).
ylim (tuple of float, optional) – Y-axis limits (min, max).
figsize (tuple) – Size of the figure.
colormap (str) – Colormap for the 2D data. Default is ‘RdBu_r’ (polar colormap).
vmin (float, optional) – Minimum value for color scale. If None, inferred from data.
vmax (float, optional) – Maximum value for color scale. If None, inferred from data.

Returns:

The matplotlib figure and axes objects.

Return type:

tuple[plt.Figure, plt.Axes]

Raises:

ValueError – If data doesn’t have the required dimensions or if TIME coordinate is missing.

Plot original and optionally monthly-averaged AMOC time series for one or more datasets.

Parameters:

data (list of xarray.Dataset or xarray.DataArray) – List of datasets or DataArrays to plot.
varnames (list of str, optional) – List of variable names to extract from each dataset. Not needed if DataArrays are passed.
labels (list of str, optional) – Labels for the legend.
colors (list of str, optional) – Colors for monthly-averaged plots.
title (str) – Title of the plot.
ylabel (str, optional) – Label for the y-axis. If None, inferred from attributes.
time_limits (tuple of str or pd.Timestamp, optional) – X-axis time limits (start, end).
ylim (tuple of float, optional) – Y-axis limits (min, max).
figsize (tuple) – Size of the figure.
resample_monthly (bool) – If True, monthly averages are computed and plotted.
plot_raw (bool) – If True, raw data is plotted.
lat_idx (int, optional) – Latitude index to select when dataset has a ‘lat’ dimension. Required if dataset contains ‘lat’ dimension with posterior samples.
region_idx (int, optional) – Region index to select when dataset has a ‘number_regions’ dimension. Required if dataset contains ‘number_regions’ dimension with posterior samples.
posterior_stat (str, default "mean") – Statistic to use when collapsing posterior samples dimension. Options are “mean” or “median”.

amocatlas.plotters.plot_bryden2005_pygmt() → pygmt.Figure[source]

Plot Bryden et al. 2005 historical AMOC estimates using PyGMT.

Creates a plot of the historical AMOC estimates from Bryden et al. (2005) showing the decline from 1957 to 2004. This provides historical context for modern observational time series.

Returns:: PyGMT figure object.
Return type:: pygmt.Figure
Raises:: ImportError – If PyGMT is not installed.

References

Bryden, H. L., Longworth, H. R., & Cunningham, S. A. (2005). Slowing of the Atlantic meridional overturning circulation at 25°N. Nature, 438(7068), 655-657.

amocatlas.plotters.plot_moc_timeseries_pygmt(df: DataFrame, column: str = 'moc', label: str = 'MOC [Sv]') → pygmt.Figure[source]

Plot MOC time series using PyGMT with publication-quality styling.

Parameters:

df (pandas.DataFrame) – DataFrame with ‘time_num’ (decimal years) and data columns.
column (str, default "moc") – Name of the column to plot.
label (str, default "MOC [Sv]") – Y-axis label for the plot.

Returns:

PyGMT figure object.

Return type:

pygmt.Figure

Raises:

ImportError – If PyGMT is not installed.

amocatlas.plotters.plot_monthly_anomalies(**kwargs) → tuple[Figure, list[Axes]][source]

Plot the monthly anomalies for various datasets.

Pass keyword arguments in the form: label_name_data, label_name_label.

For example:: osnap_data = standardOSNAP[0][“MOC_all”], osnap_label = “OSNAP” …

amocatlas.plotters.plot_osnap_components_pygmt(data: DataFrame | Dict) → pygmt.Figure[source]

Plot OSNAP MOC components with shaded error bands using PyGMT.

Parameters:: data (pandas.DataFrame or dict) – Must contain: - time_num (decimal years) - MOC_SIGMA0, MOC_EAST_SIGMA0, MOC_WEST_SIGMA0 (or legacy MOC_ALL, MOC_EAST, MOC_WEST) - MOC_EAST_SIGMA0_ERR, MOC_WEST_SIGMA0_ERR (or legacy MOC_EAST_ERR, MOC_WEST_ERR)
Returns:: PyGMT figure object.
Return type:: pygmt.Figure
Raises:: ImportError – If PyGMT is not installed.

amocatlas.plotters.plot_rapid_components_pygmt(df: DataFrame) → pygmt.Figure[source]

Plot RAPID MOC and component transports using PyGMT.

Parameters:: df (pandas.DataFrame) – Must include: - ‘time_num’ - ‘moc_mar_hc10’ (total MOC) - ‘t_gs10’ (Florida Current) - ‘t_ek10’ (Ekman) - ‘t_umo10’ (upper mid-ocean)
Returns:: PyGMT figure object.
Return type:: pygmt.Figure
Raises:: ImportError – If PyGMT is not installed.

amocatlas.plotters.show_attributes(data: str | Dataset) → DataFrame[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:: A DataFrame containing the following columns: - Attribute: The name of the attribute. - Value: The value of the attribute. - DType: The data type of the attribute.
Return type:: pandas.DataFrame
Raises:: TypeError – If the input data is not a file path (str) or an xarray Dataset.

amocatlas.plotters.show_contents(data: str | Dataset, content_type: str = 'variables') → Styler | DataFrame[source]

Wrapper function to show contents of an xarray Dataset or a netCDF file.

Parameters:

data (str or xr.Dataset) – The input data, either a file path to a netCDF file or an xarray Dataset.
content_type (str, optional) – The type of content to show, either ‘variables’ (or ‘vars’) or ‘attributes’ (or ‘attrs’). Default is ‘variables’.

Returns:

A styled DataFrame with details about the variables or attributes.

Return type:

pandas.io.formats.style.Styler or pandas.DataFrame

Raises:

TypeError – If the input data is not a file path (str) or an xarray Dataset.
ValueError – If the content_type is not ‘variables’ (or ‘vars’) or ‘attributes’ (or ‘attrs’).

amocatlas.plotters.show_variables(data: str | Dataset) → Styler[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:: 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). - standard_name: The standard name of the variable (if available). - dtype: The data type of the variable.
Return type:: pd.io.formats.style.Styler
Raises:: TypeError – If the input data is not a file path (str) or an xarray Dataset.

amocatlas.plotters.show_variables_by_dimension(data: str | Dataset, dimension_name: str = 'trajectory') → Styler[source]

Extracts variable information from an xarray Dataset or a netCDF file and returns a styled DataFrame with details about the variables filtered by a specific dimension.

Parameters:

data (str or xr.Dataset) – The input data, either a file path to a netCDF file or an xarray Dataset.
dimension_name (str, optional) – The name of the dimension to filter variables by, by default “trajectory”.

Returns:

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

Return type:

pandas.io.formats.style.Styler

Raises:

TypeError – If the input data is not a file path (str) or an xarray Dataset.