The ecco_access library¶
Andrew Delman, updated 2025-11-13
Important Note: The
ecco_accessmodules are now available in their own Python package, which can be installed using conda or pip! Supporting documentation can be found here. Hence, theecco_accessfunctions are no longer included inecco_v4_pyas of version 1.8. This tutorial is for users of earlier versions ofecco_v4_py, but will be removed at a later date.
The ecco_access library for users of ecco_v4_py >=1.7.4,<1.8¶
Introduction¶
In the past several years since ECCOv4 release 4 output was made available on the Physical Oceanography Distributed Active Archive Center or PO.DAAC, a number of Python scripts/functions have been written to facilitate requests of this output, authored by Jack McNelis, Ian Fenty, and Andrew Delman. These codes have been consolidated into the ecco_access modules, in order to standardize the format of the requests.
This tutorial will help you to start using the ecco_access library, which is comprised of a set of Python modules. Here we introduce the two top-level functions in ecco_access:
ecco_podaac_to_xrdataset: takes as input a text query or ECCO dataset identifier, and returns an xarray Datasetecco_podaac_access: takes the same input, but returns the URLs/paths or local files where the data is located
ECCO output on PO.DAAC¶
Setting up Earthdata login credentials¶
An account with NASA Earthdata is required to access ECCO output hosted in the AWS Cloud by PO.DAAC. Please visit https://urs.earthdata.nasa.gov/home to make an account.
The Earthdata Login provides a single mechanism for user registration and profile management for all EOSDIS system components (DAACs, Tools, Services). Your Earthdata login also helps the EOSDIS program better understand the usage of EOSDIS services to improve user experience through customization of tools and improvement of services. EOSDIS data are openly available to all and free of charge except where governed by international agreements.
Note: some Earthdata password characters may cause problems depending on your system. To be safe, do not use any of the following characters in your password: backslash (), space, hash (#), quotes (single or double), or greater than (>). Set/change your Earthdata password here: https://urs.earthdata.nasa.gov/change_password
After creating a NASA Earthdata account, create a file called
.netrcin your home directory (linux, Mac):
/home/<username>/.netrc
or _netrc (Windows):
C:\Users\<username>\_netrc
The netrc file must have the following structure and must include your Earthdata account login name and password:
machine urs.earthdata.nasa.gov
login <your username>
password <your password>
Set permissions on your
netrcfile to be readable only by the current user. If not, you will receive the error “netrc access too permissive.”
$ chmod 0600 ~/.netrc
ECCO output structure on PO.DAAC¶
On PO.DAAC and in the NASA Earthdata Cloud, ECCO output is organized in the following hierarchy:
Dataset: Typically contains a few variables, spanning the time range of the ECCO v4r4 output (currently 1992-2017). Most datasets are divided (in the time dimension) into hundreds or thousands of granules.
Granule: Dataset variables at a specific time (monthly mean, daily mean, or snapshot). Exceptions are 1-D time series where the entire dataset only consists of one granule.
Variable: A specific geophysical parameter (or flux) representing the state of the ocean, atmosphere, or sea ice/snow cover. Individual variables are not visible through the NASA Earthdata website, but can be seen after a granule file has been opened.
Each dataset has a dataset code called a ShortName which is used to identify it on the cloud. In order to download particular variable(s), you need to identify the ShortName associated with the dataset containing those variables. You can search for the variables in the linked text files below, or download these files for your reference.
Dataset ShortNames and variables associated with them¶
ECCO v4r4 llc90 Grid Dataset Variables - Monthly Means
ECCO v4r4 llc90 Grid Dataset Variables - Daily Means
ECCO v4r4 llc90 Grid Dataset Variables - Daily Snapshots
ECCO v4r4 0.5-Deg Interp Grid Dataset Variables - Monthly Means
ECCO v4r4 0.5-Deg Interp Grid Dataset Variables - Daily Means
ECCO v4r4 Time Series and Grid Parameters
Note that unlike earlier releases of ECCO v4, in v4r4 all monthly mean variables are also available for download as daily means. Snapshots (typically at daily intervals) are available for a few variables, and can be used to help close budgets as shown in later tutorials.
Importing ecco_access to your workspace¶
As of the April 2025 update, ecco_access modules are included in ecco_v4_py. To use them, you should install the ecco_v4_py Python package (version 1.7.8 or later), e.g.,
conda install "ecco_v4_py>=1.7.8"
Then you can import the ecco_access modules in your Python code and notebooks:
import ecco_v4_py.ecco_access as ea
Note: You can also import ecco_access into your workspace just by importing
ecco_v4_pyrather thanecco_v4_py.ecco_access. The high-level functions discussed below should work either way. Importingecco_v4_py.ecco_accessis just a little more direct, especially if you are only using the access-related functions ofecco_v4_py.
If you installed a recent version of ecco_v4_py using conda install ecco_v4_py or pip install ecco_v4_py and you are encountering errors, try cloning the ECCOv4-py Github repository that contains ecco_v4_py, as the Github repository may have bug fixes that have not been pushed to conda-forge or pypi yet. Then add the
repository to the beginning of your Python path by putting the following code in your notebooks:
import sys
sys.path.insert(0,'path/to/ECCOv4-py')
import ecco_v4_py.ecco_access as ea
Using the ecco_podaac_to_xrdataset function¶
Perhaps the most convenient way to use ecco_access is the ecco_podaac_to_xrdataset; it takes as input a query consisting of NASA Earthdata dataset ShortName(s), ECCO variables, or text strings in the variable descriptions, and outputs an xarray Dataset. Let’s look at the syntax:
[1]:
import xarray as xr
import matplotlib.pyplot as plt
from os.path import join,expanduser
import ecco_v4_py as ecco
import ecco_v4_py.ecco_access as ea
# identify user's home directory
user_home_dir = expanduser('~')
[2]:
help(ea.ecco_podaac_to_xrdataset)
Help on function ecco_podaac_to_xrdataset in module ecco_v4_py.ecco_access:
ecco_podaac_to_xrdataset(query, version='v4r4', grid=None, time_res='all', StartDate=None, EndDate=None, snapshot_interval=None, mode='download_ifspace', download_root_dir=None, **kwargs)
This function queries and accesses ECCO datasets from PO.DAAC. The core query and download functions
are adapted from Jupyter notebooks created by Jack McNelis and Ian Fenty
(https://github.com/ECCO-GROUP/ECCO-ACCESS/blob/master/PODAAC/Downloading_ECCO_datasets_from_PODAAC/README.md)
and modified by Andrew Delman (https://ecco-v4-python-tutorial.readthedocs.io).
It is similar to ecco_podaac_access, except instead of a list of URLs or files,
an xarray Dataset with all of the queried ECCO datasets is returned.
Parameters
----------
query: str, list, or dict, defines datasets or variables to access.
If query is str, it specifies either a dataset ShortName (if query
matches a NASA Earthdata ShortName), or a text string that can be
used to search the ECCO ShortNames, variable names, and descriptions.
A query may also be a list of multiple ShortNames and/or text searches,
or a dict that contains grid,time_res specifiers as keys and ShortNames
or text searches as values, e.g.,
{'native,monthly':['ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4',
'THETA']}
will query the native grid monthly SSH datasets, and all native grid
monthly datasets with variables or descriptions matching 'THETA'.
version: ('v4r4','v4r5'), specifies ECCO version to query.
Currently 'v4r5' only works with ['s3_open','s3_get','s3_get_ifspace'] modes,
or if the files are already stored in download_root_dir/ShortName/.
Otherwise an error is returned.
grid: ('native','latlon',None), specifies whether to query datasets with output
on the native grid or the interpolated lat/lon grid.
The default None will query both types of grids, unless specified
otherwise in a query dict (e.g., the example above).
time_res: ('monthly','daily','snapshot','all'), specifies which time resolution
to include in query and downloads. 'all' includes all time resolutions,
and datasets that have no time dimension, such as the grid parameter
and mixing coefficient datasets.
StartDate,EndDate: str, in 'YYYY', 'YYYY-MM', or 'YYYY-MM-DD' format,
define date range [StartDate,EndDate] for download.
EndDate is included in the time range (unlike typical Python ranges).
Full ECCOv4r4 date range (default) is '1992-01-01' to '2017-12-31'.
For 'SNAPSHOT' datasets, an additional day is added to EndDate to enable
closed budgets within the specified date range.
snapshot_interval: ('monthly', 'daily', or None), if snapshot datasets are included in ShortNames,
this determines whether snapshots are included for only the beginning/end
of each month ('monthly'), or for every day ('daily').
If None or not specified, defaults to 'daily' if any daily mean ShortNames
are included and 'monthly' otherwise.
mode: str, one of the following:
'download': Download datasets using NASA Earthdata URLs
'download_ifspace': Check storage availability before downloading.
Download only if storage footprint of downloads
<= max_avail_frac*(available storage)
'download_subset': Download spatial and temporal subsets of datasets
via Opendap; query help(ecco_access.ecco_podaac_download_subset)
to see keyword arguments that can be used in this mode.
The following modes work within the AWS cloud only:
's3_open': Access datasets on S3 without downloading.
's3_open_fsspec': Use json files (generated with `fsspec` and `kerchunk`)
for expedited opening of datasets.
's3_get': Download from S3 (to AWS EC2 instance).
's3_get_ifspace': Check storage availability before downloading;
download if storage footprint
<= max_avail_frac*(available storage).
Otherwise data are opened "remotely" from S3 bucket.
download_root_dir: str, defines parent directory to download files to.
Files will be downloaded to directory download_root_dir/ShortName/.
If not specified, parent directory defaults to '~/Downloads/ECCO_V4r4_PODAAC/',
or '~/Downloads/ECCO_V4r5_PODAAC/' if version == 'v4r5'.
Additional keyword arguments*:
*This is not an exhaustive list, especially for
'download_subset' mode; use help(ecco_access.ecco_podaac_download_subset) to display
options specific to that mode
max_avail_frac: float, maximum fraction of remaining available disk space to
use in storing ECCO datasets.
If storing the datasets exceeds this fraction, an error is returned.
Valid range is [0,0.9]. If number provided is outside this range, it is replaced
by the closer endpoint of the range.
jsons_root_dir: str, for s3_open_fsspec mode only, the root/parent directory where the
fsspec/kerchunk-generated jsons are found.
jsons are generated using the steps described here:
https://medium.com/pangeo/fake-it-until-you-make-it-reading-goes-netcdf4-data-on-aws-s3
as-zarr-for-rapid-data-access-61e33f8fe685.
If None (default), jsons_root_dir will be set to ~/MZZ/{version}/.
The jsons need to be stored in the following directories/formats:
For v4r4: {jsons_root_dir}/MZZ_{GRIDTYPE}_{TIME_RES}/{SHORTNAME}.json.
GRIDTYPE is '05DEG' or 'LLC0090GRID' for v4r4;
TIME_RES is one of: ('MONTHLY','DAILY','SNAPSHOT','GEOMETRY','MIXING_COEFFS').
For v4r5: {jsons_root_dir}/MZZ_{TIME_RES}_{GRIDTYPE}/{SHORTNAME_core}_{TIME_RES}_{GRIDTYPE}_llc090_ECCOV4r5.json.
TIME_RES is one of: ('mon_mean','day_mean','snap');
GRIDTYPE is one of: ('native','latlon').
The SHORTNAME_core is the SHORTNAME without the 'ECCO_L4_' at the beginning,
or the grid/time/version IDs at the end (e.g., 'LLC0090GRID_MONTHLY_V4R5').
jsons_retrieve: bool, if True (default), and jsons are not already stored in jsons_root_dir,
retrieve from S3 bucket and store locally in jsons_root_dir.
If False, and jsons are not stored in jsons_root_dir,
the data retrieval will fail.
n_workers: int, number of workers to use in concurrent downloads. Benefits typically taper off above 5-6.
force_redownload: bool, if True, existing files will be redownloaded and replaced;
if False (default), existing files will not be replaced.
show_noredownload_msg: bool, if True (default), and force_redownload=False,
display message for each file that is already
downloaded (and therefore not re-downloaded);
if False, these messages are not shown.
prompt_request_payer: bool, if True (default), user is prompted to approve
(by entering "y" or "Y") any access to a
requester pays bucket, otherwise request is canceled;
if False, data access proceeds without prompting.
Returns
-------
ds_out: xarray Dataset or dict of xarray Datasets (with ShortNames as keys),
containing all of the accessed datasets.
This function does not work with the query modes: 'ls','query','s3_ls','s3_query'.
There are a lot of options that you can use to “submit” a query with this function. Let’s consider a simple case, where we already have the ShortName for the monthly native grid SSH from ECCOv4r4 (ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4), and we want to access output from the year 2017. The ShortName goes in the query field, and we can specify start and end dates (in YYYY-MM or YYYY-MM-DD format). The other options that matter most for this request are the mode, and depending on the mode, the download_root_dir or the jsons_root_dir.
Direct download over the internet (mode = ‘download’)¶
Let’s try the download mode, which retrieves the data over the Internet using NASA Earthdata URLs (this should work on any machine with Internet access, including cloud environments):
[3]:
# download data and open xarray dataset
curr_shortname = 'ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4'
ds_SSH = ea.ecco_podaac_to_xrdataset(curr_shortname,\
StartDate='2017-01',EndDate='2017-12',\
mode='download',\
download_root_dir=join(user_home_dir,'Downloads','ECCO_V4r4_PODAAC'))
Creating download directory /home/jpluser/Downloads/ECCO_V4r4_PODAAC/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4
DL Progress: 100%|#########################| 12/12 [00:04<00:00, 2.47it/s]
=====================================
total downloaded: 71.02 Mb
avg download speed: 14.6 Mb/s
Time spent = 4.863487720489502 seconds
We specified a root directory for the download (which also happens to be the default setting), and the data files are then placed under download_root_dir / ShortName. We can verify that the contents of the file are what we queried:
[4]:
ds_SSH
[4]:
<xarray.Dataset> Size: 25MB
Dimensions: (time: 12, tile: 13, j: 90, i: 90, i_g: 90, j_g: 90, nv: 2, nb: 4)
Coordinates: (12/13)
* i (i) int32 360B 0 1 2 3 4 5 6 7 8 9 ... 81 82 83 84 85 86 87 88 89
* i_g (i_g) int32 360B 0 1 2 3 4 5 6 7 8 ... 81 82 83 84 85 86 87 88 89
* j (j) int32 360B 0 1 2 3 4 5 6 7 8 9 ... 81 82 83 84 85 86 87 88 89
* j_g (j_g) int32 360B 0 1 2 3 4 5 6 7 8 ... 81 82 83 84 85 86 87 88 89
* tile (tile) int32 52B 0 1 2 3 4 5 6 7 8 9 10 11 12
* time (time) datetime64[ns] 96B 2017-01-16T12:00:00 ... 2017-12-16T0...
... ...
YC (tile, j, i) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
XG (tile, j_g, i_g) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
YG (tile, j_g, i_g) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
time_bnds (time, nv) datetime64[ns] 192B dask.array<chunksize=(1, 2), meta=np.ndarray>
XC_bnds (tile, j, i, nb) float32 2MB dask.array<chunksize=(13, 90, 90, 4), meta=np.ndarray>
YC_bnds (tile, j, i, nb) float32 2MB dask.array<chunksize=(13, 90, 90, 4), meta=np.ndarray>
Dimensions without coordinates: nv, nb
Data variables:
SSH (time, tile, j, i) float32 5MB dask.array<chunksize=(1, 13, 90, 90), meta=np.ndarray>
SSHIBC (time, tile, j, i) float32 5MB dask.array<chunksize=(1, 13, 90, 90), meta=np.ndarray>
SSHNOIBC (time, tile, j, i) float32 5MB dask.array<chunksize=(1, 13, 90, 90), meta=np.ndarray>
ETAN (time, tile, j, i) float32 5MB dask.array<chunksize=(1, 13, 90, 90), meta=np.ndarray>
Attributes: (12/57)
acknowledgement: This research was carried out by the Jet Pr...
author: Ian Fenty and Ou Wang
cdm_data_type: Grid
comment: Fields provided on the curvilinear lat-lon-...
Conventions: CF-1.8, ACDD-1.3
coordinates_comment: Note: the global 'coordinates' attribute de...
... ...
time_coverage_duration: P1M
time_coverage_end: 2017-02-01T00:00:00
time_coverage_resolution: P1M
time_coverage_start: 2017-01-01T00:00:00
title: ECCO Sea Surface Height - Monthly Mean llc9...
uuid: a21a5c30-400c-11eb-a9e0-0cc47a3f49c3In-cloud direct access with pre-generated json files (mode = ‘s3_open_fsspec’)¶
If you are working on an instance in the Amazon Web Services (AWS) Cloud (region us-west-2), you can use one of the access modes specifically intended for in-cloud S3 data access. One of these modes is s3_open_fsspec, which opens the files from S3 (no download necessary), and uses json files with the data chunking information to open the files exceptionally fast. If you have these files
already stored in a specific directory on your instance, or want to specify where to store them, you can use the jsons_root_dir option. Otherwise, by default the json files will be accessed from the s3://ecco-model-granules bucket and stored under your user home directory in ~/MZZ/v4r4.
[5]:
curr_shortname = 'ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4'
ds_SSH_s3 = ea.ecco_podaac_to_xrdataset(curr_shortname,\
StartDate='2017-01',EndDate='2017-12',\
mode='s3_open_fsspec')
[6]:
ds_SSH_s3
[6]:
<xarray.Dataset> Size: 25MB
Dimensions: (time: 12, tile: 13, j: 90, i: 90, nb: 4, j_g: 90, i_g: 90, nv: 2)
Coordinates: (12/13)
* time (time) datetime64[ns] 96B 2017-01-16T12:00:00 ... 2017-12-16T0...
XC (tile, j, i) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
XC_bnds (tile, j, i, nb) float32 2MB dask.array<chunksize=(13, 90, 90, 4), meta=np.ndarray>
XG (tile, j_g, i_g) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
YC (tile, j, i) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
YC_bnds (tile, j, i, nb) float32 2MB dask.array<chunksize=(13, 90, 90, 4), meta=np.ndarray>
... ...
* i (i) int32 360B 0 1 2 3 4 5 6 7 8 9 ... 81 82 83 84 85 86 87 88 89
* i_g (i_g) int32 360B 0 1 2 3 4 5 6 7 8 ... 81 82 83 84 85 86 87 88 89
* j (j) int32 360B 0 1 2 3 4 5 6 7 8 9 ... 81 82 83 84 85 86 87 88 89
* j_g (j_g) int32 360B 0 1 2 3 4 5 6 7 8 ... 81 82 83 84 85 86 87 88 89
* tile (tile) int32 52B 0 1 2 3 4 5 6 7 8 9 10 11 12
time_bnds (time, nv) datetime64[ns] 192B dask.array<chunksize=(12, 2), meta=np.ndarray>
Dimensions without coordinates: nb, nv
Data variables:
ETAN (time, tile, j, i) float32 5MB dask.array<chunksize=(12, 13, 90, 90), meta=np.ndarray>
SSH (time, tile, j, i) float32 5MB dask.array<chunksize=(12, 13, 90, 90), meta=np.ndarray>
SSHIBC (time, tile, j, i) float32 5MB dask.array<chunksize=(12, 13, 90, 90), meta=np.ndarray>
SSHNOIBC (time, tile, j, i) float32 5MB dask.array<chunksize=(12, 13, 90, 90), meta=np.ndarray>
Attributes: (12/57)
Conventions: CF-1.8, ACDD-1.3
acknowledgement: This research was carried out by the Jet Pr...
author: Ian Fenty and Ou Wang
cdm_data_type: Grid
comment: Fields provided on the curvilinear lat-lon-...
coordinates_comment: Note: the global 'coordinates' attribute de...
... ...
time_coverage_duration: P1M
time_coverage_end: 1992-02-01T00:00:00
time_coverage_resolution: P1M
time_coverage_start: 1992-01-01T12:00:00
title: ECCO Sea Surface Height - Monthly Mean llc9...
uuid: 9302811e-400c-11eb-b69e-0cc47a3f49c3Now plot the SSH for Jan 2017 in tile 10 (Python numbering convention; 11 in Fortran/MATLAB numbering convention). Here we use the “RdYlBu” colormap, one of many built-in colormaps that the matplotlib package provides, or you can create your own. The “_r” at the end reverses the direction of the colormap, so red
corresponds to the maximum values.
[7]:
ds_SSH_s3.SSH.isel(time=0,tile=10).plot(cmap='RdYlBu_r')
[7]:
<matplotlib.collections.QuadMesh at 0x7f90819eef30>
We can also use the ecco_v4_py package to plot a global map of Jan 2017 SSH, using the plot_proj_to_latlon_grid function which regrids from the native LLC grid to a lat/lon grid.
[8]:
plt.figure(figsize=(12,6), dpi= 90)
ecco.plot_proj_to_latlon_grid(ds_SSH_s3.XC, ds_SSH_s3.YC, \
ds_SSH_s3.SSH.isel(time=0), \
user_lon_0=-160,\
projection_type='robin',\
plot_type='pcolormesh', \
cmap='RdBu_r',\
dx=1,dy=1,cmin=-1.2, cmax=1.2,show_colorbar=True)
plt.title('Monthly mean SSH [m], Jan 2017')
plt.show()
What if you don’t know the ShortName already?¶
NASA Earthdata datasets are identified by ShortNames, but you might not know the ShortName of the variable or category of variables that you are seeking. One way to find the ShortName is to consult these ECCOv4r4 variable lists. But the “query” in ecco_access functions does not have to be
a ShortName; it can also be a text string representing a variable name, or a word or phrase in the variable description.
For example, perhaps you are looking to open the dataset that has native grid monthly sea ice concentration in 2007. If the query is not identified as a ShortName, then a text search of the variable lists is conducted using query, grid, and time_res. Then of the identified matches, the user is asked to select one.
[9]:
ds_seaice_conc = ea.ecco_podaac_to_xrdataset('ice',grid='native',time_res='monthly',\
StartDate='2007-01',EndDate='2007-12',\
mode='s3_open_fsspec')
ShortName Options for query "ice":
Variable Name Description (units)
Option 1: ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
SSH Dynamic sea surface height anomaly. Suitable for
comparisons with altimetry sea surface height data
products that apply the inverse barometer
correction. (m)
SSHIBC The inverted barometer correction to sea surface
height due to atmospheric pressure loading. (m)
SSHNOIBC Sea surface height anomaly without the inverted
barometer correction. Suitable for comparisons
with altimetry sea surface height data products
that do NOT apply the inverse barometer
correction. (m)
ETAN Model sea level anomaly, without corrections for
global mean density changes, inverted barometer
effect, or volume displacement due to submerged
sea-ice and snow. (m)
Option 2: ECCO_L4_STRESS_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
EXFtaux Wind stress in the model +x direction (N/m^2)
EXFtauy Wind stress in the model +y direction (N/m^2)
oceTAUX Ocean surface stress in the model +x direction,
due to wind and sea-ice (N/m^2)
oceTAUY Ocean surface stress in the model +y direction,
due to wind and sea-ice (N/m^2)
Option 3: ECCO_L4_HEAT_FLUX_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
EXFhl Open ocean air-sea latent heat flux (W/m^2)
EXFhs Open ocean air-sea sensible heat flux (W/m^2)
EXFlwdn Downward longwave radiative flux (W/m^2)
EXFswdn Downwelling shortwave radiative flux (W/m^2)
EXFqnet Open ocean net air-sea heat flux (W/m^2)
oceQnet Net heat flux into the ocean surface (W/m^2)
SIatmQnt Net upward heat flux to the atmosphere (W/m^2)
TFLUX Rate of change of ocean heat content per m^2
accounting for mass (e.g. freshwater) fluxes
(W/m^2)
EXFswnet Open ocean net shortwave radiative flux (W/m^2)
EXFlwnet Net open ocean longwave radiative flux (W/m^2)
oceQsw Net shortwave radiative flux across the ocean
surface (W/m^2)
SIaaflux Conservative ocean and sea-ice advective heat flux
adjustment, associated with temperature difference
between sea surface temperature and sea-ice,
excluding latent heat of fusion (W/m^2)
Option 4: ECCO_L4_FRESH_FLUX_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
EXFpreci Precipitation rate (m/s)
EXFevap Open ocean evaporation rate (m/s)
EXFroff River runoff (m/s)
SIsnPrcp Snow precipitation on sea-ice (kg/(m^2 s))
EXFempmr Open ocean net surface freshwater flux from
precipitation, evaporation, and runoff (m/s)
oceFWflx Net freshwater flux into the ocean (kg/(m^2 s))
SIatmFW Net freshwater flux into the open ocean, sea-ice,
and snow (kg/(m^2 s))
SFLUX Rate of change of total ocean salinity per m^2
accounting for mass fluxes (g/(m^2 s))
SIacSubl Freshwater flux to the atmosphere due to
sublimation-deposition of snow or ice (kg/(m^2 s))
SIrsSubl Residual sublimation freshwater flux (kg/(m^2 s))
SIfwThru Precipitation through sea-ice (kg/(m^2 s))
Option 5: ECCO_L4_SEA_ICE_CONC_THICKNESS_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
SIarea Sea-ice concentration (fraction between 0 and 1)
SIheff Area-averaged sea-ice thickness (m)
SIhsnow Area-averaged snow thickness (m)
sIceLoad Average sea-ice and snow mass per unit area
(kg/m^2)
Option 6: ECCO_L4_SEA_ICE_VELOCITY_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
SIuice Sea-ice velocity in the model +x direction (m/s)
SIvice Sea-ice velocity in the model +y direction (m/s)
Option 7: ECCO_L4_SEA_ICE_HORIZ_VOLUME_FLUX_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
ADVxHEFF Lateral advective flux of sea-ice thickness in the
model +x direction (m^3/s)
ADVyHEFF Lateral advective flux of sea-ice thickness in the
model +y direction (m^3/s)
DFxEHEFF Lateral diffusive flux of sea-ice thickness in the
model +x direction (m^3/s)
DFyEHEFF Lateral diffusive flux of sea-ice thickness in the
model +y direction (m^3/s)
ADVxSNOW Lateral advective flux of snow thickness in the
model +x direction (m^3/s)
ADVySNOW Lateral advective flux of snow thickness in the
model +y direction (m^3/s)
DFxESNOW Lateral diffusive flux of snow thickness in the
model +x direction (m^3/s)
DFyESNOW Lateral diffusive flux of snow thickness in the
model +y direction (m^3/s)
Option 8: ECCO_L4_SEA_ICE_SALT_PLUME_FLUX_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
oceSPflx Net salt flux into the ocean due to brine
rejection (g/(m^2 s))
oceSPDep Salt plume depth (m)
Please select option [1-8]: 5
Using dataset with ShortName: ECCO_L4_SEA_ICE_CONC_THICKNESS_LLC0090GRID_MONTHLY_V4R4
Files will be accessed from a requester pays S3 bucket.
Requester is responsible for any data transfer fees.
Do you want to proceed? [y/n]: y
We select option 5, corresponding to ShortName ECCO_L4_SEA_ICE_CONC_THICKNESS_LLC0090GRID_MONTHLY_V4R4. Let’s look at the dataset contents.
[10]:
ds_seaice_conc
[10]:
<xarray.Dataset> Size: 25MB
Dimensions: (time: 12, tile: 13, j: 90, i: 90, nb: 4, j_g: 90, i_g: 90, nv: 2)
Coordinates: (12/13)
* time (time) datetime64[ns] 96B 2007-01-16T12:00:00 ... 2007-12-16T1...
XC (tile, j, i) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
XC_bnds (tile, j, i, nb) float32 2MB dask.array<chunksize=(13, 90, 90, 4), meta=np.ndarray>
XG (tile, j_g, i_g) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
YC (tile, j, i) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
YC_bnds (tile, j, i, nb) float32 2MB dask.array<chunksize=(13, 90, 90, 4), meta=np.ndarray>
... ...
* i (i) int32 360B 0 1 2 3 4 5 6 7 8 9 ... 81 82 83 84 85 86 87 88 89
* i_g (i_g) int32 360B 0 1 2 3 4 5 6 7 8 ... 81 82 83 84 85 86 87 88 89
* j (j) int32 360B 0 1 2 3 4 5 6 7 8 9 ... 81 82 83 84 85 86 87 88 89
* j_g (j_g) int32 360B 0 1 2 3 4 5 6 7 8 ... 81 82 83 84 85 86 87 88 89
* tile (tile) int32 52B 0 1 2 3 4 5 6 7 8 9 10 11 12
time_bnds (time, nv) datetime64[ns] 192B dask.array<chunksize=(12, 2), meta=np.ndarray>
Dimensions without coordinates: nb, nv
Data variables:
SIarea (time, tile, j, i) float32 5MB dask.array<chunksize=(12, 13, 90, 90), meta=np.ndarray>
SIheff (time, tile, j, i) float32 5MB dask.array<chunksize=(12, 13, 90, 90), meta=np.ndarray>
SIhsnow (time, tile, j, i) float32 5MB dask.array<chunksize=(12, 13, 90, 90), meta=np.ndarray>
sIceLoad (time, tile, j, i) float32 5MB dask.array<chunksize=(12, 13, 90, 90), meta=np.ndarray>
Attributes: (12/57)
Conventions: CF-1.8, ACDD-1.3
acknowledgement: This research was carried out by the Jet Pr...
author: Ian Fenty and Ou Wang
cdm_data_type: Grid
comment: Fields provided on the curvilinear lat-lon-...
coordinates_comment: Note: the global 'coordinates' attribute de...
... ...
time_coverage_duration: P1M
time_coverage_end: 1992-02-01T00:00:00
time_coverage_resolution: P1M
time_coverage_start: 1992-01-01T12:00:00
title: ECCO Sea-Ice and Snow Concentration and Thi...
uuid: cc62f1c2-400d-11eb-9f11-0cc47a3f49c3Now plot the sea ice concentration/fraction in tile 6 (which approximately covers the Arctic Ocean), during Sep 2007 which at the time was a record minimum for Arctic sea ice.
[11]:
ds_seaice_conc.SIarea.isel(time=8,tile=6).plot(cmap='cool')
[11]:
<matplotlib.collections.QuadMesh at 0x7f90804fa690>
Using the ecco_podaac_access function¶
In-cloud direct access (mode = ‘s3_open’)¶
The ecco_podaac_to_xrdataset function that was previously used invokes ecco_podaac_access under the hood, and ecco_podaac_access can also be called directly. This can be useful if you want to obtain a list of file objects/paths or URLs that you can then process with your own code. Let’s use this function with mode = s3_open (all S3 modes only work from an AWS Cloud environment in region us-west-2).
[12]:
curr_shortname = 'ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4'
files_dict = ea.ecco_podaac_access(curr_shortname,\
StartDate='2015-01',EndDate='2015-12',\
mode='s3_open')
{'ShortName': 'ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4', 'temporal': '2015-01-02,2015-12-31'}
Total number of matching granules: 12
[13]:
files_dict[curr_shortname]
[13]:
[<File-like object S3FileSystem, podaac-ops-cumulus-protected/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4/SEA_SURFACE_HEIGHT_mon_mean_2015-01_ECCO_V4r4_native_llc0090.nc>,
<File-like object S3FileSystem, podaac-ops-cumulus-protected/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4/SEA_SURFACE_HEIGHT_mon_mean_2015-02_ECCO_V4r4_native_llc0090.nc>,
<File-like object S3FileSystem, podaac-ops-cumulus-protected/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4/SEA_SURFACE_HEIGHT_mon_mean_2015-03_ECCO_V4r4_native_llc0090.nc>,
<File-like object S3FileSystem, podaac-ops-cumulus-protected/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4/SEA_SURFACE_HEIGHT_mon_mean_2015-04_ECCO_V4r4_native_llc0090.nc>,
<File-like object S3FileSystem, podaac-ops-cumulus-protected/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4/SEA_SURFACE_HEIGHT_mon_mean_2015-05_ECCO_V4r4_native_llc0090.nc>,
<File-like object S3FileSystem, podaac-ops-cumulus-protected/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4/SEA_SURFACE_HEIGHT_mon_mean_2015-06_ECCO_V4r4_native_llc0090.nc>,
<File-like object S3FileSystem, podaac-ops-cumulus-protected/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4/SEA_SURFACE_HEIGHT_mon_mean_2015-07_ECCO_V4r4_native_llc0090.nc>,
<File-like object S3FileSystem, podaac-ops-cumulus-protected/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4/SEA_SURFACE_HEIGHT_mon_mean_2015-08_ECCO_V4r4_native_llc0090.nc>,
<File-like object S3FileSystem, podaac-ops-cumulus-protected/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4/SEA_SURFACE_HEIGHT_mon_mean_2015-09_ECCO_V4r4_native_llc0090.nc>,
<File-like object S3FileSystem, podaac-ops-cumulus-protected/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4/SEA_SURFACE_HEIGHT_mon_mean_2015-10_ECCO_V4r4_native_llc0090.nc>,
<File-like object S3FileSystem, podaac-ops-cumulus-protected/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4/SEA_SURFACE_HEIGHT_mon_mean_2015-11_ECCO_V4r4_native_llc0090.nc>,
<File-like object S3FileSystem, podaac-ops-cumulus-protected/ECCO_L4_SSH_LLC0090GRID_MONTHLY_V4R4/SEA_SURFACE_HEIGHT_mon_mean_2015-12_ECCO_V4r4_native_llc0090.nc>]
The output of ecco_podaac_access is in the form of a dictionary with ShortNames as keys. In this case, the value associated with this ShortName is a list of 12 file objects. These are files on S3 (AWS’s cloud storage system) that have been opened, which is a necessary step for the files’ data to be accessed. The list of open files can be passed directly to xarray.open_mfdataset.
[14]:
ds_SSH_fromlist = xr.open_mfdataset(files_dict[curr_shortname],\
compat='override',data_vars='minimal',coords='minimal',\
parallel=True)
[14]:
ds_SSH_fromlist
[14]:
<xarray.Dataset> Size: 25MB
Dimensions: (time: 12, tile: 13, j: 90, i: 90, i_g: 90, j_g: 90, nv: 2, nb: 4)
Coordinates: (12/13)
* i (i) int32 360B 0 1 2 3 4 5 6 7 8 9 ... 81 82 83 84 85 86 87 88 89
* i_g (i_g) int32 360B 0 1 2 3 4 5 6 7 8 ... 81 82 83 84 85 86 87 88 89
* j (j) int32 360B 0 1 2 3 4 5 6 7 8 9 ... 81 82 83 84 85 86 87 88 89
* j_g (j_g) int32 360B 0 1 2 3 4 5 6 7 8 ... 81 82 83 84 85 86 87 88 89
* tile (tile) int32 52B 0 1 2 3 4 5 6 7 8 9 10 11 12
* time (time) datetime64[ns] 96B 2015-01-16T12:00:00 ... 2015-12-16T1...
... ...
YC (tile, j, i) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
XG (tile, j_g, i_g) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
YG (tile, j_g, i_g) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
time_bnds (time, nv) datetime64[ns] 192B dask.array<chunksize=(1, 2), meta=np.ndarray>
XC_bnds (tile, j, i, nb) float32 2MB dask.array<chunksize=(13, 90, 90, 4), meta=np.ndarray>
YC_bnds (tile, j, i, nb) float32 2MB dask.array<chunksize=(13, 90, 90, 4), meta=np.ndarray>
Dimensions without coordinates: nv, nb
Data variables:
SSH (time, tile, j, i) float32 5MB dask.array<chunksize=(1, 13, 90, 90), meta=np.ndarray>
SSHIBC (time, tile, j, i) float32 5MB dask.array<chunksize=(1, 13, 90, 90), meta=np.ndarray>
SSHNOIBC (time, tile, j, i) float32 5MB dask.array<chunksize=(1, 13, 90, 90), meta=np.ndarray>
ETAN (time, tile, j, i) float32 5MB dask.array<chunksize=(1, 13, 90, 90), meta=np.ndarray>
Attributes: (12/57)
acknowledgement: This research was carried out by the Jet Pr...
author: Ian Fenty and Ou Wang
cdm_data_type: Grid
comment: Fields provided on the curvilinear lat-lon-...
Conventions: CF-1.8, ACDD-1.3
coordinates_comment: Note: the global 'coordinates' attribute de...
... ...
time_coverage_duration: P1M
time_coverage_end: 2015-02-01T00:00:00
time_coverage_resolution: P1M
time_coverage_start: 2015-01-01T00:00:00
title: ECCO Sea Surface Height - Monthly Mean llc9...
uuid: a4955186-400c-11eb-8c14-0cc47a3f49c3Accessing ECCOv4 release 5 output in the AWS Cloud¶
In addition to accessing the ECCOv4r4 Central Estimate output released on PO.DAAC, ecco_access functions can also retrieve output from the newer release 5 (ECCOv4r5). Unlike v4r4, for which many fields can be accessed at monthly/daily/snapshot time resolutions and native/latlon grid configurations, only the v4r5 monthly mean native grid outputs are currently accessible, and ecco_access can only retrieve them within the AWS Cloud. However, a number of fields were archived in v4r5 that
were not archived in v4r4, including the terms of momentum and sea-ice budgets.
SST comparison: v4r4 vs. v4r5¶
First let’s consider a field that is archived in both releases: potential temperature in the top layer, or SST. Accessing the monthly mean potential temperature for 1998 from v4r4 (and assuming we don’t know the ShortName already):
[15]:
ds_T_v4r4 = ea.ecco_podaac_to_xrdataset('temperature',\
version='v4r4',grid='native',time_res='monthly',\
StartDate='1998-01',EndDate='1998-12',\
mode='s3_open_fsspec')
ShortName Options for query "temperature":
Variable Name Description (units)
Option 1: ECCO_L4_ATM_STATE_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
EXFatemp Atmosphere surface (2 m) air temperature (degK)
EXFaqh Atmosphere surface (2 m) specific humidity (kg/kg)
EXFuwind Wind speed at 10m in the model +x direction (m/s)
EXFvwind Wind speed at 10m in the model +y direction (m/s)
EXFwspee Wind speed (m/s)
EXFpress Atmosphere surface pressure (N/m^2)
Option 2: ECCO_L4_HEAT_FLUX_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
EXFhl Open ocean air-sea latent heat flux (W/m^2)
EXFhs Open ocean air-sea sensible heat flux (W/m^2)
EXFlwdn Downward longwave radiative flux (W/m^2)
EXFswdn Downwelling shortwave radiative flux (W/m^2)
EXFqnet Open ocean net air-sea heat flux (W/m^2)
oceQnet Net heat flux into the ocean surface (W/m^2)
SIatmQnt Net upward heat flux to the atmosphere (W/m^2)
TFLUX Rate of change of ocean heat content per m^2
accounting for mass (e.g. freshwater) fluxes
(W/m^2)
EXFswnet Open ocean net shortwave radiative flux (W/m^2)
EXFlwnet Net open ocean longwave radiative flux (W/m^2)
oceQsw Net shortwave radiative flux across the ocean
surface (W/m^2)
SIaaflux Conservative ocean and sea-ice advective heat flux
adjustment, associated with temperature difference
between sea surface temperature and sea-ice,
excluding latent heat of fusion (W/m^2)
Option 3: ECCO_L4_MIXED_LAYER_DEPTH_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
MXLDEPTH Mixed-layer depth diagnosed using the temperature
difference criterion of Kara et al., 2000 (m)
Option 4: ECCO_L4_TEMP_SALINITY_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
THETA Potential temperature, i.e., temperature of water
parcel at sea level pressure (degC)
SALT Salinity (1e-3, or parts per thousand)
Option 5: ECCO_L4_OCEAN_3D_TEMPERATURE_FLUX_LLC0090GRID_MONTHLY_V4R4 *native grid,monthly means*
ADVx_TH Lateral advective flux of potential temperature in
the model +x direction (degC m^3/s)
ADVy_TH Lateral advective flux of potential temperature in
the model +y direction (degC m^3/s)
ADVr_TH Vertical advective flux of potential temperature
(degC m^3/s)
DFxE_TH Lateral diffusive flux of potential temperature in
the model +x direction (degC m^3/s)
DFyE_TH Lateral diffusive flux of potential temperature in
the model +y direction (degC m^3/s)
DFrE_TH Vertical diffusive flux of potential temperature,
explicit term (degC m^3/s)
DFrI_TH Vertical diffusive flux of potential temperature,
implicit term (degC m^3/s)
Please select option [1-5]: 4
Using dataset with ShortName: ECCO_L4_TEMP_SALINITY_LLC0090GRID_MONTHLY_V4R4
Select option 4 (the dataset that contains variables THETA and SALT), and the requested output is included in the xarray dataset ds_T_v4r4. Here is the contents of that dataset:
[16]:
ds_T_v4r4
[16]:
<xarray.Dataset> Size: 510MB
Dimensions: (time: 12, k: 50, tile: 13, j: 90, i: 90, nb: 4, j_g: 90,
i_g: 90, nv: 2, k_l: 50, k_p1: 51, k_u: 50)
Coordinates: (12/22)
* time (time) datetime64[ns] 96B 1998-01-16T12:00:00 ... 1998-12-16T1...
XC (tile, j, i) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
XC_bnds (tile, j, i, nb) float32 2MB dask.array<chunksize=(13, 90, 90, 4), meta=np.ndarray>
XG (tile, j_g, i_g) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
YC (tile, j, i) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
YC_bnds (tile, j, i, nb) float32 2MB dask.array<chunksize=(13, 90, 90, 4), meta=np.ndarray>
... ...
* k (k) int32 200B 0 1 2 3 4 5 6 7 8 9 ... 41 42 43 44 45 46 47 48 49
* k_l (k_l) int32 200B 0 1 2 3 4 5 6 7 8 ... 41 42 43 44 45 46 47 48 49
* k_p1 (k_p1) int32 204B 0 1 2 3 4 5 6 7 8 ... 43 44 45 46 47 48 49 50
* k_u (k_u) int32 200B 0 1 2 3 4 5 6 7 8 ... 41 42 43 44 45 46 47 48 49
* tile (tile) int32 52B 0 1 2 3 4 5 6 7 8 9 10 11 12
time_bnds (time, nv) datetime64[ns] 192B dask.array<chunksize=(12, 2), meta=np.ndarray>
Dimensions without coordinates: nb, nv
Data variables:
SALT (time, k, tile, j, i) float32 253MB dask.array<chunksize=(6, 50, 13, 90, 90), meta=np.ndarray>
THETA (time, k, tile, j, i) float32 253MB dask.array<chunksize=(6, 50, 13, 90, 90), meta=np.ndarray>
Attributes: (12/62)
Conventions: CF-1.8, ACDD-1.3
acknowledgement: This research was carried out by the Jet...
author: Ian Fenty and Ou Wang
cdm_data_type: Grid
comment: Fields provided on the curvilinear lat-l...
coordinates_comment: Note: the global 'coordinates' attribute...
... ...
time_coverage_duration: P1M
time_coverage_end: 1992-02-01T00:00:00
time_coverage_resolution: P1M
time_coverage_start: 1992-01-01T12:00:00
title: ECCO Ocean Temperature and Salinity - Mo...
uuid: f07693e6-4181-11eb-beb3-0cc47a3f44ffNow try the same thing, but with v4r5.
Attention: The v4r5 outputs are currently accessed not through PO.DAAC’s S3 bucket, but on the
s3://ecco-model-granules/bucket. This bucket is a “requester pays” bucket, which means that the entity requesting the data (i.e., you) would pay the data transfer fees. However, no need to get alarmed! When transferring data within the same AWS region as the bucket, the requester does not have to pay any data transfer fees. If your AWS EC2 instance is set up in the same region us-west-2 (Oregon) as theecco-model-granulesbucket, there will be no cost associated with the data transfer.When accessing data from the
ecco-model-granulesbucket, a prompt appears by default to remind the user that the data access is “requester pays”. This prompt can be suppressed by settingprompt_request_payer=False.
For mode = s3_open_fsspec, the json files will be stored under ~/MZZ/v4r5 by default, unless a different path is specified using the jsons_root_dir option.
[17]:
ds_T_v4r5 = ea.ecco_podaac_to_xrdataset('temperature',\
version='v4r5',grid='native',time_res='monthly',\
StartDate='1998-01',EndDate='1998-12',\
mode='s3_open_fsspec',\
prompt_request_payer=False)
ShortName Options for query "temperature":
Variable Name Description (units)
Option 1: ECCO_L4_ATM_SURFACE_TEMP_HUM_WIND_PRES_LLC0090GRID_MONTHLY_V4R5 *native grid,monthly means*
EXFatemp Surface (2 m) air temperature over open water.
(degK)
EXFaqh Surface (2 m) specific humidity over open water.
(kg/kg)
EXFpress Atmospheric pressure field at sea level. (N/m^2)
EXFuwind Wind speed at 10m in the +x direction at the
tracer cell on the native model grid. (m/s)
EXFvwind Wind speed at 10m in the +y direction at the
tracer cell on the native model grid. (m/s)
EXFwspee 10-m wind speed magnitude (>= 0 ) over open water.
(m/s)
Option 2: ECCO_L4_OCEAN_AND_ICE_SURFACE_HEAT_FLUX_LLC0090GRID_MONTHLY_V4R5 *native grid,monthly means*
EXFhl Air-sea latent heat flux per unit area of open
water not covered by sea-ice. (W/m^2)
EXFhs Air-sea sensible heat flux per unit area of open
water not covered by sea-ice. (W/m^2)
EXFlwdn Downward longwave radiative flux. (W/m^2)
EXFlwnet Net longwave radiative flux per unit area of open
water not covered by sea-ice. (W/m^2)
EXFswdn Downward shortwave radiative flux. (W/m^2)
EXFswnet Net shortwave radiative flux per unit area of open
water not covered by sea-ice. (W/m^2)
EXFqnet Net air-sea heat flux (turbulent and radiative)
per unit area of open water not covered by
sea-ice. (W/m^2)
SIatmQnt Net upward heat flux to the atmosphere across open
water and sea-ice or snow surfaces. (W/m^2)
SIaaflux Heat flux associated with the temperature
difference between sea surface temperature and
sea-ice (assume 0 degree C in the model). (W/m^2)
oceQnet Net heat flux into the ocean surface from all
processes: air-sea turbulent and radiative fluxes
and turbulent and conductive fluxes between the
ocean and sea-ice and snow. oceQnet does not
include the change in ocean heat content due to
changing ocean ocean mass, oceFWflx. (W/m^2)
oceQsw Net shortwave radiative flux across the ocean
surface. (W/m^2)
TFLUX The rate of change of ocean heat content due to
heat fluxes across the liquid surface and the
addition or removal of mass. Unlike oceQnet, TFLUX
includes the contribution to the ocean heat
content from changing ocean mass, oceFWflx.
(W/m^2)
Option 3: ECCO_L4_OCEAN_TEMPERATURE_FLUX_LLC0090GRID_MONTHLY_V4R5 *native grid,monthly means*
ADVx_TH Lateral advective flux of potential temperature
(THETA) in the +x direction through the 'u' face
of the tracer cell on the native model grid. (degC
m^3/s)
DFxE_TH Lateral diffusive flux of potential temperature
(THETA) in the +x direction through the 'u' face
of the tracer cell on the native model grid. (degC
m^3/s)
ADVy_TH Lateral advective flux of potential temperature
(THETA) in the +y direction through the 'v' face
of the tracer cell on the native model grid. (degC
m^3/s)
DFyE_TH Lateral diffusive flux of potential temperature
(THETA) in the +y direction through the 'v' face
of the tracer cell on the native model grid. (degC
m^3/s)
ADVr_TH Vertical advective flux of potential temperature
(THETA) in the +z direction through the top 'w'
face of the tracer cell on the native model grid.
(degC m^3/s)
DFrE_TH The explicit term of the vertical diffusive flux
of potential temperature (THETA) in the +z
direction through the top 'w' face of the tracer
cell on the native model grid. (degC m^3/s)
DFrI_TH The implicit term of the vertical diffusive flux
of potential temperature (THETA) in the +z
direction through the top 'w' face of the tracer
cell on the native model grid. (degC m^3/s)
Option 4: ECCO_L4_OCEAN_TEMPERATURE_SALINITY_LLC0090GRID_MONTHLY_V4R5 *native grid,monthly means*
THETA Sea water potential temperature, i.e., the
temperature a parcel of sea water would have if
moved adiabatically to sea level pressure. (degC)
SALT Sea water salinity. (1e-3, or parts per thousand)
Please select option [1-4]: 4
Using dataset with ShortName: ECCO_L4_OCEAN_TEMPERATURE_SALINITY_LLC0090GRID_MONTHLY_V4R5
Select option 4 again (the dataset with THETA and SALT).
[18]:
ds_T_v4r5
[18]:
<xarray.Dataset> Size: 510MB
Dimensions: (time: 12, k: 50, tile: 13, j: 90, i: 90, nb: 4, j_g: 90,
i_g: 90, nv: 2, k_l: 50, k_p1: 51, k_u: 50)
Coordinates: (12/22)
* time (time) datetime64[ns] 96B 1998-01-16T12:00:00 ... 1998-12-16T1...
XC (tile, j, i) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
XC_bnds (tile, j, i, nb) float32 2MB dask.array<chunksize=(13, 90, 90, 4), meta=np.ndarray>
XG (tile, j_g, i_g) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
YC (tile, j, i) float32 421kB dask.array<chunksize=(13, 90, 90), meta=np.ndarray>
YC_bnds (tile, j, i, nb) float32 2MB dask.array<chunksize=(13, 90, 90, 4), meta=np.ndarray>
... ...
* k (k) int32 200B 0 1 2 3 4 5 6 7 8 9 ... 41 42 43 44 45 46 47 48 49
* k_l (k_l) int32 200B 0 1 2 3 4 5 6 7 8 ... 41 42 43 44 45 46 47 48 49
* k_p1 (k_p1) int32 204B 0 1 2 3 4 5 6 7 8 ... 43 44 45 46 47 48 49 50
* k_u (k_u) int32 200B 0 1 2 3 4 5 6 7 8 ... 41 42 43 44 45 46 47 48 49
* tile (tile) int32 52B 0 1 2 3 4 5 6 7 8 9 10 11 12
time_bnds (time, nv) datetime64[ns] 192B dask.array<chunksize=(12, 2), meta=np.ndarray>
Dimensions without coordinates: nb, nv
Data variables:
SALT (time, k, tile, j, i) float32 253MB dask.array<chunksize=(6, 50, 13, 90, 90), meta=np.ndarray>
THETA (time, k, tile, j, i) float32 253MB dask.array<chunksize=(6, 50, 13, 90, 90), meta=np.ndarray>
Attributes: (12/63)
Conventions: CF-1.8, ACDD-1.3
acknowledgement: This research was carried out by the Jet...
author: Ian Fenty, Ou Wang, Ichiro Fukumori
cdm_data_type: Grid
comment: Fields provided on the curvilinear lat-l...
coordinates_comment: Note: the global 'coordinates' attribute...
... ...
time_coverage_duration: P1M
time_coverage_end: 1992-02-01T00:00:00
time_coverage_resolution: P1M
time_coverage_start: 1992-01-01T12:00:00
title: ECCO Ocean Temperature and Salinity - Mo...
uuid: 8a5175e0-2719-11f0-9a28-0a58a9feac02Now plot a map of the difference in surface potential temperature (i.e., SST) between the two releases, on tile 10 in May 1998.
[19]:
T_diff = ds_T_v4r5.THETA - ds_T_v4r4.THETA
plt.figure(figsize=(12,6), dpi= 90)
ecco.plot_proj_to_latlon_grid(ds_T_v4r4.XC, ds_T_v4r4.YC, \
T_diff.isel(time=4,k=0), \
user_lon_0=-160,\
projection_type='robin',\
plot_type='pcolormesh', \
cmap='RdBu_r',\
dx=1,dy=1,cmin=-1, cmax=1,show_colorbar=True)
plt.title('SST difference v4r5 - v4r4 [C], May 1998\n')
plt.show()
Momentum budget terms in v4r5¶
Now, let’s consider a dataset that was only archived in v4r5, not v4r4: the terms of the momentum budget. We will access and view the terms of the 
-momentum budget, i.e., the momentum along the 
-axis of the llc90 native grid.
Note: ECCOv4r5 has two different sets of momentum budget terms archived. The first set (options 1 and 2) below quantifies the effect of (lateral) vorticity advection vs. other advection terms that contribute to the momentum budget (vertical and kinetic energy gradient). The second set (options 5 and 6) consists of the primitive equation terms that describe
-momentum tendency, which you probably learned in introductory fluid dynamics classes. We consider the second set below.
[20]:
# u-momentum budget terms
ds_u_mom = ea.ecco_podaac_to_xrdataset('momentum',\
version='v4r5',grid='native',time_res='monthly',\
StartDate='1998-01',EndDate='1998-12',\
mode='s3_open_fsspec',\
prompt_request_payer=False)
ShortName Options for query "momentum":
Variable Name Description (units)
Option 1: ECCO_L4_OCEAN_3D_MOMENTUM_ADV_TEND_X_LLC0090GRID_MONTHLY_V4R5 *native grid,monthly means*
Um_AdvZ3 U momentum tendency from vorticity advection.
(m/s^2)
Um_AdvRe U momentum tendency from vertical advection,
explicit part. (m/s^2)
Um_dKEdx U momentum tendency from grad KE. (m/s^2)
Option 2: ECCO_L4_OCEAN_3D_MOMENTUM_ADV_TEND_Y_LLC0090GRID_MONTHLY_V4R5 *native grid,monthly means*
Vm_AdvZ3 V momentum tendency from vorticity advection.
(m/s^2)
Vm_AdvRe V momentum tendency from vertical advection,
explicit part. (m/s^2)
Vm_dKEdy V momentum tendency from grad KE. (m/s^2)
Option 3: ECCO_L4_OCEAN_3D_MOMENTUM_DISS_TEND_X_LLC0090GRID_MONTHLY_V4R5 *native grid,monthly means*
Um_Diss2 U momentum tendency from harmonic visc alone.
(m/s^2)
Um_Diss4 U momentum tendency from biharmonic visc alone.
(m/s^2)
UBotDrag U momentum tendency from bottom drag. (m/s^2)
USidDrag U momentum tendency from side drag. (m/s^2)
UShIDrag U momentum tendency from friction/no-slip at base
of shelf ice. (m/s^2)
Option 4: ECCO_L4_OCEAN_3D_MOMENTUM_DISS_TEND_Y_LLC0090GRID_MONTHLY_V4R5 *native grid,monthly means*
Vm_Diss2 V momentum tendency from harmonic visc alone.
(m/s^2)
Vm_Diss4 V momentum tendency from biharmonic visc alone.
(m/s^2)
VBotDrag V momentum tendency from bottom drag. (m/s^2)
VSidDrag V momentum tendency from side drag. (m/s^2)
VShIDrag V momentum tendency from friction/no-slip at base
of shelf ice. (m/s^2)
Option 5: ECCO_L4_OCEAN_3D_MOMENTUM_TEND_X_LLC0090GRID_MONTHLY_V4R5 *native grid,monthly means*
TOTUTEND Tendency of zonal component of velocity. (m/s/day)
Um_Cori U momentum tendency from Coriolis term. (m/s^2)
Um_Advec U momentum tendency from advection terms. (m/s^2)
Um_Diss U momentum tendency from dissipation, explicit
part. (m/s^2)
Um_Ext U momentum tendency from external forcing. (m/s^2)
Um_dPhiX U momentum tendency from pressure/potential grad.
(m/s^2)
AB_gU U momentum tendency from Adams-Bashforth. (m/s^2)
Um_ImplD U momentum tendency from dissipation, implicit
part. (m/s^2)
Option 6: ECCO_L4_OCEAN_3D_MOMENTUM_TEND_Y_LLC0090GRID_MONTHLY_V4R5 *native grid,monthly means*
TOTVTEND Tendency of meridional component of velocity.
(m/s/day)
Vm_Cori V momentum tendency from Coriolis term. (m/s^2)
Vm_Advec V momentum tendency from advection terms. (m/s^2)
Vm_Diss V momentum tendency from dissipation, explicit
part. (m/s^2)
Vm_Ext V momentum tendency from external forcing. (m/s^2)
Vm_dPhiY V momentum tendency from pressure/potential grad.
(m/s^2)
AB_gV V momentum tendency from Adams-Bashforth. (m/s^2)
Vm_ImplD V momentum tendency from dissipation, implicit
part. (m/s^2)
Please select option [1-6]: 5
Using dataset with ShortName: ECCO_L4_OCEAN_3D_MOMENTUM_TEND_X_LLC0090GRID_MONTHLY_V4R5
Select option 5 to look at the primitive equation -momentum terms.
Let’s plot the Coriolis and pressure gradient contributions to the model -momentum budget on tile 7 (North Pacific). This is a rotated tile, which means the positive direction is southward. Hence the -momentum budget corresponds to approximately the meridional momentum budget, with the sign reversed.
[21]:
import matplotlib as mpl
seismic_nanmasked = mpl.colormaps['seismic'].copy()
seismic_nanmasked.set_bad('gray')
plt.figure(figsize=(10,7), dpi= 90)
ds_u_mom.Um_Cori.isel(time=4,k=0,tile=7).plot(cmap=seismic_nanmasked)
plt.title('$u$-momentum Coriolis term [m s$^{-2}$], surface, May 1998\n')
plt.show()
[22]:
plt.figure(figsize=(10,7),dpi=90)
ds_u_mom.Um_dPhiX.isel(time=4,k=0,tile=7).plot(cmap=seismic_nanmasked)
plt.title('$u$-momentum pressure gradient term [m s$^{-2}$], surface, May 1998\n')
plt.show()
The fact that these two terms are nearly equal and opposite reflects the dominance of geostrophic balance. The sum of the Coriolis and pressure gradient terms (1st plot below) is balanced mostly by two frictional terms (2nd plot below): the sum of the surface (Ekman) stress included in the external forcing term Um_Ext, and the implicit dissipation of momentum Um_ImplD.
[23]:
Um_Cori_plus_pgrad = ds_u_mom.Um_Cori + ds_u_mom.Um_dPhiX
plt.figure(figsize=(10,7),dpi=90)
Um_Cori_plus_pgrad.isel(time=4,k=0,tile=7).plot(cmap=seismic_nanmasked)
plt.title('$u$-momentum Coriolis plus pressure gradient terms [m s$^{-2}$], surface, May 1998\n')
plt.show()
[24]:
Um_Ext_plus_ImplD = ds_u_mom.Um_Ext + ds_u_mom.Um_ImplD
plt.figure(figsize=(10,7),dpi=90)
Um_Ext_plus_ImplD.isel(time=4,k=0,tile=7).plot(cmap=seismic_nanmasked)
plt.title('$u$-momentum external forcing + implicit dissipation terms [m s$^{-2}$], surface, May 1998\n')
plt.show()
Notice that the two term combinations above are nearly equal in magnitude and opposite in sign.
If we look at a level well below the surface (~200 m), the residual after summing the Coriolis and pressure gradient terms is even smaller.
[25]:
k_plot = 16
plt.figure(figsize=(10,7),dpi=90)
Um_Cori_plus_pgrad.isel(time=4,k=k_plot,tile=7).plot(cmap=seismic_nanmasked)
# the syntax "%.0f" % X" rounds X to the nearest integer, with 0 digits after the decimal point
plt.title('$u$-momentum Coriolis plus pressure gradient terms [m s$^{-2}$], '\
+f'{"%.0f" % -Um_Cori_plus_pgrad.Z[k_plot].values} m depth, May 1998\n')
plt.show()
Exercise: Try plotting the terms of the meridional momentum budget globally. To do this successfully you will need both the
and
parameters in the grid file (you can use the v4r4 grid file for this). This tutorial is a good resource for how to do the interpolation/rotation on the llc90 grid.