Class NetCdfWeatherDataset

Namespace

EncDotNet.S100.Datasets.NetCdf

Assembly

EncDotNet.S100.Datasets.NetCdf.dll

A NetCDF-CF wind and wave file read into a WeatherGridSet: the grid, the parameters the weather table knows (and the ones it doesn't), their time steps, and where the data comes from. Time steps are read from the file only when they're decoded, so the dataset keeps the file open until it's disposed.

public sealed class NetCdfWeatherDataset : IDisposable

Inheritance

object

NetCdfWeatherDataset

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

How the file is read (design note weather-sources.md §7.1):

• Latitude, longitude and time are found by standard_name, by axis (Y, X, T), or by their units (degrees_north, degrees_east, "<unit> since …"). They must be one-dimensional and evenly spaced; 2-D latitude and longitude (a curvilinear grid) or a grid_mapping other than latitude_longitude fails with an UnsupportedWeatherGridException naming the grid type.
• Data variables are matched to the weather parameter table by their standard_name (FindByCfStandardName(string)) and converted to its stored units. A variable may have extra dimensions of length 1 (a single height or depth); a 10 m height is read as the wind level. When two variables map to the same parameter, the one whose standard name the table prefers is kept and the other is listed as unknown.
• Values have _FillValue, missing_value, valid_min, valid_max and valid_range applied to the stored values (and the NetCDF default fill value when there's no _FillValue), become NaN where missing, and are then unpacked with scale_factor and add_offset.
• The model is the global source, institution or title attribute, in that order; the run time is a forecast_reference_time variable or global attribute when there is one.

A file with no recognisable coordinates, or no variable the table knows, fails with a CfConventionsException that lists the variables found.

Properties

Conventions

The global Conventions attribute, for example "CF-1.6", or null.

public string? Conventions { get; }

Property Value

string

File

The open NetCDF file the steps are read from.

public NetCdfFile File { get; }

Property Value

NetCdfFile

Format

The file's format.

public NetCdfFormat Format { get; }

Property Value

NetCdfFormat

GridSet

The grid set: origin, grid and parameters with lazily read time steps.

public WeatherGridSet GridSet { get; }

Property Value

WeatherGridSet

IgnoredVariables

Data variables left out of the grid set, with why.

public IReadOnlyList<NetCdfIgnoredVariable> IgnoredVariables { get; }

Property Value

IReadOnlyList<NetCdfIgnoredVariable>

Institution

The global institution attribute, or null.

public string? Institution { get; }

Property Value

string

ReferenceTime

The model run's reference time (UTC), from a forecast_reference_time variable or global attribute, or null when the file doesn't give one (RunTime is then the first valid time).

public DateTime? ReferenceTime { get; }

Property Value

DateTime?

Source

The global source attribute (the model, in CF), or null.

public string? Source { get; }

Property Value

string

Times

The valid times of the time coordinate, in file order.

public IReadOnlyList<DateTime> Times { get; }

Property Value

IReadOnlyList<DateTime>

Title

The global title attribute, or null.

public string? Title { get; }

Property Value

string

Methods

Dispose()

Closes the file.

public void Dispose()

Open(Stream, string?, bool)

Opens and reads a NetCDF file from a seekable stream.

public static NetCdfWeatherDataset Open(Stream stream, string? name = null, bool leaveOpen = false)

Parameters

stream Stream

The file's bytes; readable and seekable.

name string

The file's name, used as the model name when the file names none.

leaveOpen bool

Whether disposing the dataset leaves stream open.

Returns

NetCdfWeatherDataset

The dataset.

Exceptions

NetCdfFormatException

The bytes aren't a NetCDF file this library can read.

CfConventionsException

The file doesn't follow the CF conventions this reader needs.

UnsupportedWeatherGridException

The grid isn't a regular latitude/longitude grid.

Open(string)

Opens and reads the NetCDF file at path.

public static NetCdfWeatherDataset Open(string path)

Parameters

path string

The file's path.

Returns

NetCdfWeatherDataset

The dataset; dispose it to close the file.

Exceptions

NetCdfFormatException

The file isn't a NetCDF file this library can read.

CfConventionsException

The file doesn't follow the CF conventions this reader needs.

UnsupportedWeatherGridException

The grid isn't a regular latitude/longitude grid.

Read(NetCdfFile, string?)

Reads an open NetCDF file as CF weather data. The dataset takes ownership of file, and disposes it if reading fails.

public static NetCdfWeatherDataset Read(NetCdfFile file, string? name = null)

Parameters

file NetCdfFile

The open file.

name string

The file's name, used as the model name when the file names none.

Returns

NetCdfWeatherDataset

The dataset.

Exceptions

CfConventionsException

The file doesn't follow the CF conventions this reader needs.

UnsupportedWeatherGridException

The grid isn't a regular latitude/longitude grid.