AMOCatlas demo

The purpose of this notebook is to demonstrate the functionality of AMOCatlas.

The demo is organised to show

Step 1: Loading and plotting a sample dataset
Step 2: Exploring the dataset attributes and variables.

Note that when you submit a pull request, you should clear all outputs from your python notebook for a cleaner merge.

[1]:

import pathlib
import sys
import os
from amocatlas import read, plotters

script_dir = pathlib.Path().parent.absolute()
parent_dir = script_dir.parents[0]
sys.path.append(str(parent_dir))

# Specify the path for writing datafiles
data_path = os.path.join(parent_dir, "data")

Load RAPID 26°N

To see what files are available for each data source, use read.DATASOURCE.list_files(). So for the RAPID array, you can use read.rapid.list_files().

You can then use this list (or a subset thereof) to specify which files to be loaded and standardised using the read.rapid(file_list=["file1", "file2"]) function with the input file_list. It will return a list of xarray datasets, in the same order and the same length as file_list. An exception is if file_list has length = 1, in which case it will return just the xarray dataset.

[2]:

# Find available files
rapid_file_list = read.rapid.list_files()

print("Available RAPID files:")
print(rapid_file_list)

# To specify to read two of those files, provide a file_list
standardRAPID = read.rapid(file_list = rapid_file_list[0:2])

Available RAPID files:
['moc_transports.nc', 'moc_vertical.nc', 'ts_gridded.nc', '2d_gridded.nc', 'meridional_transports.nc']
Loading 2 RAPID 26°N dataset(s):
  0. moc_transports.nc: RAPID layer transport time series
  1. moc_vertical.nc: RAPID vertical streamfunction time series

/home/runner/micromamba/envs/amocatlas/lib/python3.14/site-packages/xarray/backends/plugins.py:109: RuntimeWarning: Engine 'gmt' loading failed:
Error loading GMT shared library at 'libgmt.so'.
libgmt.so: cannot open shared object file: No such file or directory
  external_backend_entrypoints = backends_dict_from_pkg(entrypoints_unique)

[3]:

# Plot RAPID timeseries
plotters.plot_amoc_timeseries(
    data=[standardRAPID[0]],
    varnames=["MOC"],
    labels=[""],
    resample_monthly=True,
    plot_raw=True,
    figsize=(10, 5),
    title="RAPID 26°N"
)

[3]:

(<Figure size 1000x500 with 1 Axes>,
 <Axes: title={'center': 'RAPID 26°N'}, xlabel='Time', ylabel='MOC$_{z}$ [Sv]'>)

Load MOVE 16°N

To load the specified default transport file, use the read.DATASOURCE() function with no inputs. So for the MOVE array, this is read.move(). It will provide a single xarray dataset. For each array, a default transport file has been specified.

Developer’s note: This is specified in ~/amocatlas/data_source/DATASOURCE.py.

[4]:

ds_move = read.move()

Loading 1 MOVE 16°N dataset(s):
  0. OS_MOVE_20000206-20221014_DPR_VOLUMETRANSPORT.nc: MOVE transport time series

[5]:

# Plot MOVE timeseries
plotters.plot_amoc_timeseries(
    data=[ds_move],
    varnames=["MOC"],
    labels=[""],
    colors=["darkgreen"],
    resample_monthly=True,
    plot_raw=True,
    title="MOVE 16°N - NADW Transport"
)

[5]:

(<Figure size 1000x300 with 1 Axes>,
 <Axes: title={'center': 'MOVE 16°N - NADW Transport'}, xlabel='Time', ylabel='MOC$_{z}$ [Sv]'>)

Load SAMBA 34.5°S

If you want to load all datasets available for a datasource, provide the option all_files=True. Note that the first time you do this, it will download the data for you. On subsequent runs (set up from the same location) it will use the previously downloaded data.

See the data reports in the docs: https://amoccommunity.github.io/AMOCatlas/ if you want to check how big a dataset is before downloading it.

[8]:

standardSAMBA = read.samba(all_files=True)

Loading 2 SAMBA 34.5°S dataset(s):
  0. Upper_Abyssal_Transport_Anomalies.txt: Daily volume transport anomaly estimates for the upper and abyssal cells of the MOC
  1. MOC_TotalAnomaly_and_constituents.asc: Daily travel time values, calibrated to a nominal pressure of 1000 dbar, and bottom pressures from the two PIES/CPIES moorings

[9]:

# Plot SAMBA timeseries
plotters.plot_amoc_timeseries(
    data=[standardSAMBA[0], standardSAMBA[1]],
    varnames=["UPPER_TRANSPORT", "MOC"],
    labels=["Kersale et al. 2020", "Meinen et al. 2018"],
    colors=["grey", "blue"],
    title="SAMBA 34.5°S",
    time_limits=("2000-01-01", "2022-12-31"),
    ylim=(-25, 25),
    resample_monthly=True,
    plot_raw=False # Raw data is a little spiky
)

[9]:

(<Figure size 1000x300 with 1 Axes>,
 <Axes: title={'center': 'SAMBA 34.5°S'}, xlabel='Time', ylabel='Upper Transport [Sv]'>)

Load FW2015

For a formatted table showing the data including variables, dimensions, units etc, use the function plotters.show_variables(DATASET) where DATASET is an xarray dataset.

[10]:

standardfw2015 = read.fw2015()
plotters.show_variables(standardfw2015)

Loading 1 Frajka-Williams 2015 dataset(s):
  0. MOCproxy_for_figshare_v1.mat: Time series of MOC

information is based on xarray Dataset

[10]:

	dims	units	standard_name	dtype
name
MOC	TIME	Sverdrup	ocean_meridional_overturning_transport	float64
MOC_PROXY	TIME	Sverdrup	ocean_meridional_overturning_streamfunction	float64
SSHA	TIME	cm	Sea_surface_height_anomaly	float64
TIME	TIME	datetime64[ns]	time	datetime64[ns]
TRANS_1100_3000	TIME	Sverdrup	ocean_volume_transport_across_line	float64
TRANS_3000_5000	TIME	Sverdrup	ocean_volume_transport_across_line	float64
TRANS_EKMAN	TIME	Sverdrup	ocean_volume_transport_across_line	float64
TRANS_EKMAN__GRID	TIME	Sverdrup	ocean_volume_transport_across_line	float64
TRANS_FC	TIME	Sverdrup	ocean_volume_transport_across_line	float64
TRANS_FC_GRID	TIME	Sverdrup	ocean_volume_transport_across_line	float64
TRANS_UMO	TIME	Sverdrup	ocean_volume_transport_across_line	float64
TRANS_UMO_PROXY	TIME	Sverdrup	ocean_volume_transport_across_line	float64

[11]:

# Plot timeseries
plotters.plot_amoc_timeseries(
    data=[standardfw2015],
    varnames=["MOC_PROXY"],
    labels=[""],
    colors=["darkblue"],
    resample_monthly=True,
    plot_raw=True,
    title="FW2015"
)

[11]:

(<Figure size 1000x300 with 1 Axes>,
 <Axes: title={'center': 'FW2015'}, xlabel='Time', ylabel='MOC$_{z proxy}$ [Sv]'>)

LOAD MOCHA 26.5°N

Note that AMOCatlas renames variables and updates units according to defaults specified in the code. For the MOCHA dataset, for example, the meridional heat transport is denoted by “Q”, whereas for other datasets it is “MHT”. To simplify intercomparison, we rename heat transport variables to “MHT”. When you use the read.mocha() this variable remapping has already taken place.

You can check the remapping applied in the docs: https://amoccommunity.github.io/AMOCatlas/

Additionally, some units such as “W” for Watts are converted to PetaWatts “PW” during the loading and standardisation. If instead you want to load the raw data, you can use read.mocha(raw=True).

[12]:

standardMOCHA = read.mocha()

plotters.show_variables(standardMOCHA)

Loading 1 MOCHA 26°N dataset(s):
  0. Johns_2023_mht_data_2020_ERA5.zip: No description available

information is based on xarray Dataset

/home/runner/work/AMOCatlas/AMOCatlas/amocatlas/reader_utils.py:78: SerializationWarning: Unable to decode time axis into full numpy.datetime64[ns] objects, continuing using cftime.datetime objects instead, reason: dates out of range. To silence this warning use a coarser resolution 'time_unit' or specify 'use_cftime=True'.
  ds = xr.open_dataset(file_path, **kwargs)

[12]:

	dims	units	comment	standard_name	dtype
name
MHT	TIME	PW		northward_ocean_heat_transport	float64
MHT_EKMAN	TIME	PW		northward_ocean_heat_transport_component	float64
MHT_FC	TIME	PW		northward_ocean_heat_transport_component	float64
MHT_GYRE	TIME	PW	as classically defined (e.g. see Johns et al., 2011).	northward_ocean_heat_transport_due_to_gyre	float64
MHT_INT	TIME	PW	This only represents the contribution by the zonal mean v and T	northward_ocean_heat_transport_component	float64
MHT_MO	TIME	PW	(Q_int + Q_wedge + Q_eddy)	northward_ocean_heat_transport_component	float64
MHT_OT	TIME	PW	as classically defined (e.g. see Johns et al., 2011).	northward_ocean_heat_transport_due_to_meridional_overturning	float64
MHT_WEDGE	TIME	PW		northward_ocean_heat_transport_component	float64
MOC	TIME	Sverdrup		ocean_meridional_overturning_transport	float64
Q_eddy	TIME	PW	derived from an objective analysis of interior ARGO T/S data merged with the mooring T/S data from moorings, and smoothly merged into the EN4 climatology along 26.5°N below 2000m. Q_eddy is not dependent on the temperature reference	northward_ocean_heat_transport_component	float64
TEMP_FC_FWT	TIME	degree_C		sea_water_potential_temperature	float64
TIME	TIME	datetime64[ns]		time	datetime64[ns]
TRANS_EKMAN	TIME	Sverdrup		ocean_volume_transport_across_line	float64
TRANS_FC	TIME	Sverdrup	from the cable	ocean_volume_transport_across_line	float64
DEPTH	depth	m		depth	float64
TEMP_BASIN_MEAN	depth	degree_C		sea_water_potential_temperature	float64
TRANSPROF_BASIN_MEAN	depth	Sverdrup/m		northward_sea_water_velocity	float64
TRANSPROF_FC_MEAN	depth	Sverdrup/m		northward_sea_water_velocity	float64
TEMP_BASIN	string	degree_C		sea_water_potential_temperature	float64
TRANSPROF_BASIN	string	Sverdrup/m		northward_sea_water_velocity	float64
TRANSPROF_FC	string	Sverdrup/m		northward_sea_water_velocity	float64
moc	string	Sverdrup		ocean_meridional_overturning_streamfunction	float64

[13]:

rawMOCHA = read.mocha(raw=True)
plotters.show_variables(rawMOCHA)

/home/runner/work/AMOCatlas/AMOCatlas/amocatlas/reader_utils.py:78: SerializationWarning: Unable to decode time axis into full numpy.datetime64[ns] objects, continuing using cftime.datetime objects instead, reason: dates out of range. To silence this warning use a coarser resolution 'time_unit' or specify 'use_cftime=True'.
  ds = xr.open_dataset(file_path, **kwargs)

Loading 1 MOCHA 26°N dataset(s):
  0. Johns_2023_mht_data_2020_ERA5.zip: No description available

information is based on xarray Dataset

/home/runner/work/AMOCatlas/AMOCatlas/amocatlas/plotters.py:270: SerializationWarning: Unable to decode time axis into full numpy.datetime64[ns] objects, continuing using cftime.datetime objects instead, reason: dates out of range. To silence this warning use a coarser resolution 'time_unit' or specify 'use_cftime=True'.
  "dtype": str(var.dtype) if isinstance(data, str) else str(var.data.dtype),

[13]:

	dims	units	comment	standard_name	dtype
name
T_basin_mean	depth	degree_C			float64
V_basin_mean	depth	1e6 m2 s-1			float64
V_fc_mean	depth	1e6 m2 s-1			float64
z	depth	m		depth	float64
T_basin	string	degree_C			float64
V_basin	string	1e6 m2 s-1			float64
V_fc	string	1e6 m2 s-1			float64
moc	string	1e6 m3 s-1			float64
Q_eddy	time	W	derived from an objective analysis of interior ARGO T/S data merged with the mooring T/S data from moorings, and smoothly merged into the EN4 climatology along 26.5°N below 2000m. Q_eddy is not dependent on the temperature reference		float64
Q_ek	time	W			float64
Q_fc	time	W			float64
Q_gyre	time	W	as classically defined (e.g. see Johns et al., 2011).		float64
Q_int	time	W	This only represents the contribution by the zonal mean v and T		float64
Q_mo	time	W	(Q_int + Q_wedge + Q_eddy)		float64
Q_ot	time	W	as classically defined (e.g. see Johns et al., 2011).		float64
Q_sum	time	W			float64
Q_wedge	time	W			float64
T_fc_fwt	time	degree_C			float64
day	time				float64
hour	time				float64
julian_day	time				object
maxmoc	time	1e6 m3 s-1			float64
month	time				float64
time	time			time	datetime64[ns]
trans_ek	time	1e6 m3 s-1			float64
trans_fc	time	1e6 m3 s-1	from the cable		float64
year	time				float64

[14]:

rawMOCHA

[15]:

# Plot timeseries
fig, ax = plotters.plot_amoc_timeseries(
    data=[standardMOCHA,standardMOCHA,standardMOCHA],
    varnames=["MHT", "MHT_OT","MHT_GYRE"],
    labels=["Total", "Overturning","Gyre"],
    colors=["red","darkblue","black"],
    resample_monthly=True,
    plot_raw=False,
    title="MOCHA"
)
ax.legend(loc="lower right")

[15]:

<matplotlib.legend.Legend at 0x7f337f031550>

LOAD 41°N

Besides array-based datasets, some additional data sources are integrated within AMOCatlas. For instance, the Willis and Hobbs estimates of heat transport at 41°N and the Willis transport estimates using Argo and altimetry are available as datasource “WH41N”.

[16]:

file_list = read.wh41n.list_files()
print("Available WH41N files:")
print(file_list)

standard41n = read.wh41n()

plotters.plot_amoc_timeseries(
    data=[standard41n],
    varnames=["MOC"],
    labels=[""],
    resample_monthly=True,
    plot_raw=False,
    colors=["darkblue"],
    title="41N"
)

Available WH41N files:
['hobbs_willis_amoc41N_tseries.txt', 'trans_ARGO_ERA5.nc', 'Q_ARGO_obs_dens_2000depth_ERA5.nc']
Loading 1 Willis & Hobbs 41°N dataset(s):
  0. hobbs_willis_amoc41N_tseries.txt: Transport time series of Ekman volume, Northward geostrophc, Meridional Overturning volume and Meridional Overturning Heat

[16]:

(<Figure size 1000x300 with 1 Axes>,
 <Axes: title={'center': '41N'}, xlabel='Time', ylabel='MOC$_{z}$ [Sv]'>)

Load Denmark Strait overflow and Faroe Bank Channel overflow transports

Overflow transports for Denmark Strait and Faroe Bank Channel are also available.

Note that in the current version of AMOCatlas we have not standardised the sign of the transports. In this case, a stronger DSO is more negative, whereas a stronger FBC is more positive.

[17]:

standardDSO = read.dso()
standardFBC = read.fbc()

plotters.plot_amoc_timeseries(
    data=[standardDSO, standardFBC],
    varnames=["TRANS_DSO","TRANS_FBC"],
    labels=["DSO", "FBC"],
    resample_monthly=True,
    plot_raw=True,
    colors=["yellow", "orange"],
    title="DSO and FBC"
)

Loading 1 Denmark Strait Overflow dataset(s):
  0. DSO_transport_hourly_1996_2021.nc: Overflow time-series through Denmark Strait

Loading 1 Faroe Bank Channel dataset(s):
  0. FBC_overflow_transport.txt: Daily averaged kinematic FBC-overflow flux (transport) in Sv

[17]:

(<Figure size 1000x300 with 1 Axes>,
 <Axes: title={'center': 'DSO and FBC'}, xlabel='Time', ylabel='DS Overflow [Sv]'>)

Load Calafat2025

Meridional heat transport from a Bayesian method to produce a North Atlantic heat budget is also available. However, it has 4000 realisations of the time series (from which uncertainties can be estimated), so is less straightforward to plot.

[18]:

standardCALAFAT2025 = read.calafat2025()

# declare latitude index (between 1 and 11)
lat_idx = 5
lat_val = standardCALAFAT2025['LATITUDE'].values[lat_idx]

if lat_val<0:
    title_str = f'CALAFAT2025 (lat = {-lat_val:.2f}°S)'
else:
    title_str = f'CALAFAT2025 (lat = {lat_val:.2f}°N)'

plotters.plot_amoc_timeseries(
data=[standardCALAFAT2025],
varnames=["MHT"],
labels=[""],
colors=["darkred"],
resample_monthly=True,
plot_raw=True,
lat_idx=lat_idx,
ylabel='MHT (PW)',
title=title_str
)

Loading 1 Calafat et al. 2025 dataset(s):
  0. Bayesian_estimates_Atlantic_MHT.zip: No description available

[18]:

(<Figure size 1000x300 with 1 Axes>,
 <Axes: title={'center': 'CALAFAT2025 (lat = 26.00°N)'}, xlabel='Time', ylabel='MHT (PW)'>)

Load Zheng2024

Freshwater transports also available.

[19]:

standardZHENG2024 = read.zheng2024()
# Declare latitude index (between 0 and 100)
lat_idx = 61
lat_val = standardZHENG2024['LATITUDE'].values[lat_idx]

# Set title string based on latitude value
if lat_val<0:
    title_str = f'ZHENG2024 (lat = {-lat_val:.2f}°S)'
else:
    title_str = f'ZHENG2024 (lat = {lat_val:.2f}°N)'

# Subselect data based on latitude index
data = standardZHENG2024['MFT'][:, lat_idx]

# Plot timeseries
plotters.plot_amoc_timeseries(
    data=[data],
    varnames=["MFT"],
    labels=[""],
    colors=["darkgreen"],
    resample_monthly=True,
    plot_raw=True,
    lat_idx=lat_idx,
    ylabel='MFT (Sv)',
    title=title_str
    )

Loading 1 Zheng et al. 2024 dataset(s):
  0. atl_mft_2000_extend_gpcp_oaflux.nc: An observation-based estimate of the Atlantic meridional freshwater transport

[19]:

(<Figure size 1000x300 with 1 Axes>,
 <Axes: title={'center': 'ZHENG2024 (lat = 26.50°N)'}, xlabel='Time', ylabel='MFT (Sv)'>)

Monthly Anomalies Overview

[20]:

plotters.plot_monthly_anomalies(
    osnap_data=ds_osnap["MOC_SIGMA0"],
    fortyone_data = standard41n["MOC"],
    rapid_data=standardRAPID[0]["MOC"],
    move_data=-ds_move["MOC"],
    samba_data=standardSAMBA[1]["MOC"],
    fw2015_data=standardfw2015["MOC_PROXY"],
    dso_data = standardDSO["TRANS_DSO"],
    osnap_label="OSNAP",
    fortyone_label = "41°N",
    rapid_label="RAPID 26°N",
    move_label="MOVE 16°N",
    samba_label="SAMBA 34.5°S",
    fw2015_label="FW2015",
    dso_label = "DS Overflow Transport"
)

[20]:

(<Figure size 1000x1600 with 7 Axes>,
 array([<Axes: title={'center': 'DS Overflow Transport'}, ylabel='Transport [Sv]'>,
        <Axes: title={'center': 'OSNAP'}, ylabel='Transport [Sv]'>,
        <Axes: title={'center': '41°N'}, ylabel='Transport [Sv]'>,
        <Axes: title={'center': 'RAPID 26°N'}, ylabel='Transport [Sv]'>,
        <Axes: title={'center': 'FW2015'}, ylabel='Transport [Sv]'>,
        <Axes: title={'center': 'MOVE 16°N'}, ylabel='Transport [Sv]'>,
        <Axes: title={'center': 'SAMBA 34.5°S'}, xlabel='Time', ylabel='Transport [Sv]'>],
       dtype=object))

Other components

It is also possible to manipulate (filter) and plot other components of the AMOC, depending on what is available in the datasets.

[21]:

clim = standardRAPID[0].groupby("TIME.month").mean("TIME")
tmp = standardRAPID[0].groupby("TIME.month") - clim
filtRAPID = tmp.rolling(TIME = 500, center = True).mean()

fig,ax = plotters.plot_amoc_timeseries(
    data=[filtRAPID],
    varnames=["TRANS_3000_5000"],
    labels=[""],
    resample_monthly=True,
    plot_raw=True,
    title="RAPID 26°N - t_ld10"
)
ax.set_ylim(4, -3)

fig.show()