Skip to content

ncextract

Jump to bottom
Jesús Casado Rodríguez edited this page Feb 25, 2025 · 6 revisions

The ncextract tool extracts time series from (multiple) NetCDF or GRIB file(s) at user defined coordinates.

Input

The tool takes as input a CSV file containing point coordinates and a directory containing one or more NetCDF or GRIB files. The CSV file must contain only three columns: point identifier, and its two coordinates. The name of the coordinate fields must match those in the NetCDF or GRIB files. For example:

ID,lat,lon
0010,40.6083,-4.2250
0025,37.5250,-6.2750
0033,40.5257,-6.4753

By default, the tool extracts the values at the closest pixel in the model with respect to the input coordinates. However, to be able to extract the inflow into lakes and reservoirs, you can also provide a local drainage direction (LDD) map and ask the tool to compute the sum of all the timeseries of neighbouring pixels draining into the specified points.

Output

The tool will produce one file (in NetCDF format) for each of the points in the input CSV. These files contain the time series extracted from the input maps for the closest pixel.

Usage

In the command prompt

The tool can be run from the command prompt by indicating the CSV file of points of interest, the directory containing the NetCDF or GRIB files, and the name of the output directory.

usage: ncextract.py [-h] -p POINTS -d DIR -o OUTPUT [-s START] [-e END] [-i] [-l LDD] [-w]

Utility to extract time series of values from (multiple) NetCDF or GRIB files at specific coordinates.
Coordinates of points of interest must be included in a CSV file with at least 3 columns with the point
identifier and the two coordinates (e.g. 'id', 'lat', 'lon').
options:
  -h, --help            
                        show this help message and exit
  -p POINTS, --points POINTS
                        CSV file of points of interest (id, lat, lon)
  -d DIR, --dir DIR
                        Input directory with NetCDF or GRIB files
  -o OUTPUT, --output OUTPUT
                        Output directory for time series
  -s START, --start START
                        Start datetime (YYYY-MM-DD) (default: None)
  -e END, --end END
                        End datetime (YYYY-MM-DD) (default: None)
  -i, --inflow
                        Extract the aggregation of pixels flowing into the points of interest
  -l LDD, -ldd LDD       
                        Map of local drainage directions. Only necessary if --inflow is flagged
  -w, --overwrite
                        Overwrite existing files (default: False). Only necessary if --output is provided

Example

The following command extracts the discharge time series from EFAS simulations (NetCDF files in the directory EFAS5/discharge/maps) in a series of points where gauging stations are located (file gauging_stations.csv), and saves the extraction as NetCDF files (default option).

ncextract -p ./gauging_stations.csv -d ./EFAS5/discharge/maps/ -o ./EFAS5/discharge/time_series/

In a Python script

The function can be imported in a Python script. It takes as inputs two xarray.Dataset: one defining the input maps and the other the points of interest. The result of the extraction can be another xarray.Dataset, or saved as a file either in CSV or NetCDF format.

Example

In the snippet below, we want to extract the time series of inflow (dataset dis) into a set of lakes (dataset lakes). To do so, we need to flag the inflow argument and provide the LDD map (dataarray ldd).

from lisfloodutilities.ncextract import extract_timeseries

# load desired input maps and points
# dis: xarray.Dataset ('lat', 'lon', 'time')
# lakes: xarray.Dataset ('id')
# ldd: xarray.DataArray ('lat', 'lon')

# extract the inflow time series and save in a xarray.Dataset
inflow = extract_timeseries(dis, lakes, inflow=True, ldd=ldd, output_dir=None)
Clone this wiki locally