EncDotNet.S100.Datasets.TropicalCyclones 0.27.0

EncDotNet.S100.Datasets.TropicalCyclones

EncDotNet.S100.Datasets.TropicalCyclones reads tropical cyclone advisories from the US National Hurricane Center's GIS data (https://www.nhc.noaa.gov/gis/) into one model: the storm, the advisory, every forecast point with its intensity and wind radii, the cone of uncertainty, and the storm's track so far.

It depends on EncDotNet.S100.Core and NetTopologySuite. The pipeline processor that loads it, TropicalCycloneDatasetProcessor, is in EncDotNet.S100.Datasets.Pipelines, under the format name TC. The portrayal, TropicalCycloneStyle, is in EncDotNet.S100.Datasets.Weather.

Not for navigation. NHC advisories aren't S-100 products or official navigational warnings. Hosts label them so wherever they appear.

The design is in the vector weather design note (docs/design/vector-weather.md, §8.1 and §3.1).

Install

dotnet add package EncDotNet.S100.Datasets.TropicalCyclones

Read an advisory

NHC publishes each advisory as three shapefile zips. Download them into one folder:

Then read the forecast zip. The reader finds the other two beside it:

using EncDotNet.S100.Datasets.TropicalCyclones;

var advisory = NhcAdvisoryReader.Read("al092022_5day_020.zip");

Console.WriteLine($"{advisory.Storm.Name} ({advisory.Storm.AtcfId}), advisory {advisory.Advisory}");
Console.WriteLine($"Issued {advisory.IssueTime:u}");

foreach (var point in advisory.Forecast)
{
    Console.WriteLine($"+{point.Tau} h {point.ValidTime:u}: {point.Position}, {point.MaxWindKnots} kt, {point.Classification}");
    foreach (var radius in point.Radii)
        Console.WriteLine($"  {radius.ThresholdKnots} kt: NE {radius.NortheastNauticalMiles} nm, SE {radius.SoutheastNauticalMiles} nm, ...");
}

You can also pass a folder holding one storm's zips. The reader takes its latest advisory, so 20A comes after 20. To read zips that aren't on disk, pass their streams to NhcAdvisoryReader.Read(forecast, windRadii, bestTrack). The last two can be null.

What the model holds

TropicalCycloneAdvisory holds:

• Storm. The ATCF id (AL092022), the name, and the basin, number and year the id gives.
• Advisory. The number as NHC writes it ("20", or "20A" for an intermediate advisory), and the issue time. The issue time keeps the offset of NHC's local time, such as EDT. Hosts show it in the viewer's own zone.
• Forecast. One TropicalCycloneForecastPoint per forecast time, in tau order. Each has the valid time in UTC, the position, the maximum wind and gusts, and the class (TropicalCycloneClass, with NHC's code and letter). The point at tau 0 also has the pressure and the storm's motion. Values NHC doesn't forecast are null.
• Wind radii. Each forecast point's 34, 50 and 64 kt radii, as nautical miles in each quadrant (NE, SE, SW, NW) and NHC's polygon. A radius whose quadrants are all 0 is left out, so a tropical depression has none. QuadrantSurface(centre, pointsPerQuadrant) builds the area from the four quadrants, a quarter circle each, for a radius that has no polygon of NHC's.
• Cone. TropicalCycloneCone holds NHC's polygon unchanged, and the same area split at 72 hours into DaysOneToThree and DaysFourToFive. It is null when the advisory has no cone, as some final advisories don't.
• Past track. The best-track points up to the advisory's synoptic time, with the intensity, class and observed radii at each. A best track downloaded later holds the storm's whole life, so points after the advisory are left out.
• Final advisory. IsFinal is true for a storm's last advisory, when NHC has stopped issuing advisories for it. NHC's files don't say so: a host that sees the storm leave NHC's active list writes a marker beside the zips (NhcAdvisoryFiles.FinalMarkerName, al092022_final.txt), and NhcAdvisoryFiles.Find reports it (IsFinal) so the reader marks the advisory.

All positions are WGS-84 degrees. NHC computes on a sphere, and the difference is far smaller than the data's precision.

How the cone is split

NHC's GIS files give only the whole five-day cone. The split that the chart draws (days 1 to 3 plain, days 4 and 5 stippled) is made by cutting the cone with a line through the 72-hour position, square to the track there. This matches NHC's own graphic for any track that doesn't double back within the cone. When the forecast ends at or before 72 hours, the whole cone is days 1 to 3.

The storm at a time

advisory.StormAt(time) gives the storm at any time in the advisory's range as a TropicalCycloneStormAt: its Point (position, intensity, class, motion and radii, as a forecast point valid at that time) and its Source:

• ForecastPoint on one of the advisory's forecast points;
• Estimated between two, interpolated linearly in time: the position on the geodesic between them, the wind, gusts, pressure and each quadrant of each wind radius in between, and the earlier point's class. A radius that's zero at one end shrinks to nothing; when a point has no radii at all the radii are left out. The motion is the direction and speed between the two points. NHC doesn't forecast these positions;
• BestTrack before the advisory's synoptic time, interpolated the same way along the past track, with the observed radii where both points have them.

It's null before the first best-track point and after the last forecast point. Across the antimeridian the longitude stays on the earlier point's side, so it can pass 180°.

var storm = advisory.StormAt(new DateTime(2022, 9, 28, 6, 0, 0, DateTimeKind.Utc));
if (storm is { IsEstimated: true })
    Console.WriteLine($"est. {storm.Point.Position}, {storm.Point.MaxWindKnots} kt");

Field names

The reader uses these fields, checked against NHC's archived files for 2022 and 2023:

NHC writes 9999 for a value it leaves out, and the reader returns null for it. The watches and warnings layer (_ww_wwlin) and the best track's wind swath aren't read yet.

The shapefiles are read by a small managed SHP and DBF reader in this package. It reads points, lines and polygons, including their Z and M forms. It isn't public API.