Add the Labrador Current retroflection index (Jutras et al. 2023)

[chross22]

Adds LCR to the climate index catalog, alongside NAO, AO, AMO, and PDO.

lcr <- fetch_climate_index("LCR")          # monthly, 1993-2014
observations <- attach_climate_index(observations, "LCR")

Why this is in datamatch and not derivoce

The first instinct was derivoce, since the index is defined by Lagrangian particle tracking and derivoce already does FTLE/FSLE over the same velocity fields. But Jutras et al. publish the computed index as source data with the paper, so this fetches the authors' own values rather than reimplementing them — which makes it a catalog entry, exactly the thing fetch_climate_index() already does.

Recomputation would still belong in derivoce, and is only needed to extend the record past 2014. For scale: 966 particles per release, weekly from 1993 to 2015, each tracked 3 years at a 10-minute step, via OceanParcels.

Why it is worth having

The other four indices are atmospheric patterns. This one describes a current — how much of the Labrador Current turns east at the Grand Banks instead of continuing along the shelf, and so how much cold, fresh, oxygen-rich water reaches the Scotian Shelf and Gulf of Maine. For shelf water properties that is a shorter causal chain than the NAO.

Citation

It is the output of one study rather than an operational product, so the citation travels with it: a new reference field on the catalog entry, surfaced by index_dictionary() as both a column and printed output, and repeated in the fetch_climate_index() docs and the README.

Jutras M, Dufour CO, Mucci A, Talbot LC (2023) Large-scale control of the retroflection of the Labrador Current. Nature Communications 14:2623. https://doi.org/10.1038/s41467-023-38321-y

The NOAA indices have no single paper to point at, so their reference is NA rather than invented.

Format details, established from the file rather than assumed

• Decimal years on a fixed 365-day year. The step between rows is 1/365 to eleven significant figures. Reading them as 365.25 would walk the derived dates off by several days across the record and move values into neighbouring months.
• Daily averaged to monthly, since every other index here is monthly and attach_climate_index() joins on year and month. The underlying index is already 12-month smoothed, so little is lost.
• Months backed by fewer than half their days are dropped. The 365-day convention rolls the final record into a January of its own, which would otherwise appear as a confident-looking January 2015 value resting on a single day — the failure mode min_coverage guards against elsewhere in the package.

One thing I did not do: the Methods describe normalizing the index to [-1, 1], but the published Figure 3 source data spans -0.089 to 0.175. The docs describe what the file actually contains rather than restating the Methods.

Verification

• R CMD check — Status: OK, no errors, warnings, or notes.
• Full suite green; 12 new tests covering the parser, the 365-day convention, the short-month guard, and the citation.
• Parser tests run against a local fixture, so the suite stays offline.
• Verified against the live file: 260 monthly values, May 1993 to December 2014, attaching correctly to observations.

Note: repo CI could not run — GitHub's hosted runners have been failing at "Set up job" and queueing 2h+. Verification above is local.

🤖 Generated with Claude Code