Class GribWeatherDataset

Namespace

EncDotNet.S100.Datasets.Grib

Assembly

EncDotNet.S100.Datasets.Grib.dll

A GRIB2 file read into a WeatherGridSet: its fields grouped into parameters by code and level, their steps in valid-time order, and where the data comes from. Steps are decoded from the file only when they're needed, so the dataset keeps the GribFile open until it's disposed.

public sealed class GribWeatherDataset : IDisposable

Inheritance

object

GribWeatherDataset

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 §3.4 and §7.2):

• Files. One file with many messages, or several files appended one after another (what the NOMADS GRIB filter returns for several forecast hours, or cat f000 f003 f006): the order of the messages doesn't matter.
• Fields left out (IgnoredFields, with why): fields the decoder can't read (UnsupportedReason, for example template 5.42 CCSDS, or a Lambert grid); fields on another grid than the dataset's (the grid of the first readable field the parameter table knows); fields of an older model run; and a field whose parameter, level and valid time repeat an earlier one's.
• Parameters. The fields are grouped by GRIB2 code and level, and each group's steps are ordered by valid time (reference time plus forecast time; for a time-interval statistic, template 4.8, such as ECMWF's 10fg gust, the end of the interval). A group maps to the canonical table (FindByGribCode(GribParameterCode)) when its level matches the row's. Each parameter group of the table (Group) is read at one level, so a drawn group never mixes levels:
  • the row's own level when the file has it (10 m for the wind, mean sea level for pressure);
  • for the wind, the surface when the file has no 10 m wind: GFS-Wave labels the 10 m wind that drives the wave model (its UGRD, VGRD, WIND and WDIR) as at the surface;
  • for rows with no level of their own, a proper level (surface, mean sea level, a height) before NCEP's numbered partitions (local fixed surface 241, "1 in sequence", "2 in sequence"…), and partition 1 before the others: so GFS-Wave's swell height is its first swell partition.

  Within the chosen level, where a row lists several codes the most preferred one the file has is used. Every other group is kept as an unknown parameter ("grib2:discipline,category,number"): listed, with why in UnusedReasons, but not drawn or sampled.

• Grid. The fields' WeatherNativeGrid (scanning mode as signed increments) normalised by WeatherGridLayout: rows flipped to run north, 0 to 360 longitudes moved into −180 to 180. Bitmapped points are NaN.
• Model runs. The run is the fields' reference time. When the fields have several reference times and every one is an analysis (valid at its reference time), the file is an analysis series: ReferenceTime is null and each analysis is a step. Otherwise the latest run is used and the older runs' fields are left out, so a file of appended runs shows the newest forecast.
• Model name. GRIB2 doesn't carry one; see Model.

Properties

File

The open GRIB2 file the steps are decoded from.

public GribFile File { get; }

Property Value

GribFile

GridSet

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

public WeatherGridSet GridSet { get; }

Property Value

WeatherGridSet

IgnoredFields

Fields left out of the grid set, with why, in file order.

public IReadOnlyList<GribIgnoredField> IgnoredFields { get; }

Property Value

IReadOnlyList<GribIgnoredField>

Model

The model name (Model). GRIB2 doesn't name the model, so it's taken from NCEP's generating process number (81, 82 and 96 are the GFS, 11 is GFS-Wave), else from the file name as the sources name their files (gfs.t00z…, gfswave.t00z…, filter_gfs_0p25.pl, ECMWF's …-oper-fc for the IFS and …-wave-fc for ECMWF WAM), else the originating centre ("ECMWF"). Several models are joined: "GFS + GFS-Wave".

public string Model { get; }

Property Value

string

ReferenceTime

The model run's reference time (UTC), or null for an analysis series: fields of several reference times, each valid at its own (RunTime is then the first analysis).

public DateTime? ReferenceTime { get; }

Property Value

DateTime?

Times

The valid times of the parameters the table knows, in time order.

public IReadOnlyList<DateTime> Times { get; }

Property Value

IReadOnlyList<DateTime>

UnusedReasons

Why each unknown parameter of GridSet isn't used: not in the parameter table, at a level the table doesn't use, a less preferred code, or another swell partition.

public IReadOnlyDictionary<WeatherParameter, string> UnusedReasons { get; }

Property Value

IReadOnlyDictionary<WeatherParameter, string>

Methods

Dispose()

Closes the file.

public void Dispose()

Open(IReadOnlyList<string>)

Opens and reads several GRIB2 files as one dataset, as if appended (one run published a file per forecast hour, #1075): fields are merged by parameter and level, and each parameter's steps ordered by valid time, whatever the files' order. Files of several runs keep the latest run and list the older runs' fields (IgnoredFields).

public static GribWeatherDataset Open(IReadOnlyList<string> paths)

Parameters

paths IReadOnlyList<string>

The files; at least one.

Returns

GribWeatherDataset

The dataset; dispose it to close the files.

Exceptions

ArgumentException

paths is empty.

GribFormatException

A file isn't valid GRIB2.

UnsupportedGribException

A file is GRIB edition 1, or none of the fields can be decoded.

UnsupportedWeatherGridException

The grid can't be normalised (it crosses the antimeridian).

Open(Stream, string?, bool)

Opens and reads a GRIB2 file from a seekable stream.

public static GribWeatherDataset 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 for the model name when the file's codes don't give it.

leaveOpen bool

Whether disposing the dataset leaves stream open.

Returns

GribWeatherDataset

The dataset.

Exceptions

GribFormatException

The bytes aren't valid GRIB2.

UnsupportedGribException

The data is GRIB edition 1, or none of its fields can be decoded.

UnsupportedWeatherGridException

The grid can't be normalised (it crosses the antimeridian).

Open(string)

Opens and reads the GRIB2 file at path.

public static GribWeatherDataset Open(string path)

Parameters

path string

The file's path.

Returns

GribWeatherDataset

The dataset; dispose it to close the file.

Exceptions

GribFormatException

The file isn't valid GRIB2.

UnsupportedGribException

The file is GRIB edition 1, or none of its fields can be decoded.

UnsupportedWeatherGridException

The grid can't be normalised (it crosses the antimeridian).

OpenFolder(string)

Opens a folder holding one model run (GribRunFolder): its GRIB2 files, in name order, read as one dataset (see Open(IReadOnlyList<string>)).

public static GribWeatherDataset OpenFolder(string folder)

Parameters

folder string

The folder.

Returns

GribWeatherDataset

The dataset; dispose it to close the files.

Exceptions

UnsupportedGribException

The folder holds no GRIB2 file, or none of the fields can be decoded.

Read(GribFile, string?)

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

public static GribWeatherDataset Read(GribFile file, string? name = null)

Parameters

file GribFile

The open file.

name string

The file's name, used for the model name when the file's codes don't give it.

Returns

GribWeatherDataset

The dataset.

Exceptions

UnsupportedGribException

None of the file's fields can be decoded.

UnsupportedWeatherGridException

The grid can't be normalised (it crosses the antimeridian).