NCToolkit v1.3.1 (archived)
Home / Quickstart

Quickstart

A ten-minute tour of NCToolkit's core abilities, using a historical global sea-surface temperature dataset served over a thredds server.

We'll use monthly average sea-surface temperature for 1991–2020 from NOAA's COBE-SST 2 dataset, read directly from a thredds server — no download needed.

Importing NCToolkit

The preferred way to import the package is as nc:

python
import nctoolkit as nc

It lets you quickly visualize data

NCToolkit offers automatic plotting for almost any netCDF file. Calculating and plotting mean historical sea surface temperature is as simple as:

python
ds = nc.open_thredds("https://psl.noaa.gov/thredds/dodsC/Datasets/COBE2/sst.mon.ltm.1991-2020.nc")
ds.plot()
ds.plot() — interactive output Open interactive
Mean historical sea surface temperature

It lets you easily subset data

To look at a particular region, use subset. Here we select January and crop to a European box:

python
ds = nc.open_thredds("https://psl.noaa.gov/thredds/dodsC/Datasets/COBE2/sst.mon.ltm.1991-2020.nc")
ds.subset(month=1, lon=[-13, 38], lat=[30, 67])
ds.plot()
ds.plot() — interactive output Open interactive
January sea surface temperature over Europe

It lets you calculate temporal averages

A suite of methods prefixed with t calculate temporal statistics. A seasonal average:

python
ds = nc.open_thredds("https://psl.noaa.gov/thredds/dodsC/Datasets/COBE2/sst.mon.ltm.1991-2020.nc")
ds.tmean("season")
ds.plot()
ds.plot() — interactive output Open interactive
Seasonal climatology of sea surface temperature

And spatial averages are just as simple:

python
ds = nc.open_thredds("https://psl.noaa.gov/thredds/dodsC/Datasets/COBE2/sst.mon.ltm.1991-2020.nc")
ds.subset(variables="sst")
ds.subset(lon=[-13, 38], lat=[30, 67])
ds.spatial_mean()
ds.plot()
ds.plot() — interactive output Open interactive
Spatial mean sea surface temperature over Europe

It lets you do mathematical operations

The assign method works like pandas' assign. Here's how much warmer each part of the ocean is than the global mean:

python
ds = nc.open_thredds("https://psl.noaa.gov/thredds/dodsC/Datasets/COBE2/sst.mon.ltm.1991-2020.nc")
ds.tmean()
ds.assign(delta=lambda x: x.sst - spatial_mean(x.sst), drop=True)
ds.plot()
ds.plot() — interactive output Open interactive
Temperature difference from the global mean

It lets you regrid data

Built-in methods handle horizontal and vertical interpolation. to_latlon regrids to a regular lon/lat grid — just give it the extent, resolution and method:

python
ds = nc.open_thredds("https://psl.noaa.gov/thredds/dodsC/Datasets/COBE2/sst.mon.ltm.1991-2020.nc")
ds.to_latlon(lon=[-13, 38], lat=[30, 67], res=1, method="bil")
ds.plot()
ds.plot() — interactive output Open interactive
Sea surface temperature regridded to a regular lon/lat grid

It lets you calculate zonal averages

python
ds = nc.open_thredds("https://psl.noaa.gov/thredds/dodsC/Datasets/COBE2/sst.mon.ltm.1991-2020.nc")
ds.zonal_mean()
ds.plot()
ds.plot() — interactive output Open interactive
Zonal mean sea surface temperature

Next steps

That's the shape of it: open a dataset, chain a few methods, and plot or export the result. From here: