Matchups with point data

Matching at specific locations

Matching gridded data to point observations is handled by match_points. We'll illustrate this with ocean nitrate from NOAA's World Ocean Atlas, cropped to part of the North Atlantic:

import nctoolkit as nc
ds = nc.open_thredds("https://data.nodc.noaa.gov/thredds/dodsC/ncei/woa/nitrate/all/1.00/woa18_all_n01_01.nc", checks=False)
ds.crop(lon=[-40, 20], lat=[40, 70], nco=True)
ds.subset(variables="n_an")
ds.plot()

ds.plot() — interactive output Open interactive

That covers nitrate from the sea surface to the sea floor. The dataframe of points must use column names from lon, lat, depth, year, month or day. Given a dataframe of four coordinates and depths:

import pandas as pd
df = pd.DataFrame({"lon":[-10, -12, -14, -16], "lat":[45, 50, 53, 55], "depth":[4, 2, 30, 40]})
df

Note: the dataframe columns must be named one of lon, lat, depth, year, month or day. To match our dataset to this dataframe:

ds.match_points(df)

match_points returns a pandas dataframe with the matched-up values added. Watch for messages confirming assumptions NCToolkit made while matching — usually safe to ignore, except around depths, which are derived from the dataset unless you provide them explicitly. For the example above, NCToolkit reports:

Spatial matchup approach

Data is first regridded horizontally using bilinear interpolation to the given lon/lat pairs. If depths are provided, the result is then interpolated vertically using 1D interpolation (via scipy).

Spatiotemporal matchups

The same method handles matchups over time — illustrated here with daily air temperature from the CMIP6 model GFDL-CM4. Given a dataframe with lon, lat, year, month and day columns for two points at different times:

df = pd.DataFrame({"lon": [50, 60], "lat": [50, 45], "year":[1850, 1852], "month":[1, 3], "day":[2, 3]})
df

This only contains two data points, but for different times. Match up as before:

ds = nc.open_data("tas_day_GFDL-CM4_historical_r1i1p1f1_gr1_18500101-18691231.nc", checks=False)
df_match = ds.match_points(df)
df_match

As expected, a dataframe with surface air temperature for the locations and times specified. match_points works like pandas' merge: specify only year and month, omitting day, and every day for those years and months is returned:

df_match = ds.match_points(df.drop(columns="day"))
df_match

We now have every day for the given times.

Optional arguments

A handful of arguments refine the matchup process: variables, tmean, top and nan.

• variables

  Restrict the matchup to a subset of variables, e.g. ds.match_points(df, variables="tas").

• tmean

  Apply ds.tmean() with the temporal grouping implied by the dataframe columns before matching — useful when point data is coarser than the dataset (e.g. monthly points, daily data). This is equivalent to running ds.tmean(["year", "month"]) beforehand.

• top

  When the dataset has multiple vertical levels but you only want the top one.

• nan

  Values in the dataset that should be treated as missing.

Using tmean with monthly points against the daily dataset above:

df = pd.DataFrame({"lon": [50, 60], "lat": [50, 45], "year":[1850, 1852], "month":[1, 3]})
df_match = ds.match_points(df, tmean=True)
df_match