meta/src

Classes

LabelAlignmentError

Defined in: packages-ts/meta/src/labels.ts:91

Raised by the BYO aligner. Carries a stable reason (for structured branching) plus optional namespace/column context, mirroring the Python LabelAlignmentError.

Extends

Error

Constructors

new LabelAlignmentError()

new LabelAlignmentError(reason, message, ctx?): LabelAlignmentError

Defined in: packages-ts/meta/src/labels.ts:95

Parameters

reason

message

string

ctx?

column?

string

namespace?

string

Returns

LabelAlignmentError

Overrides

Error.constructor

Properties

column?

readonly optional column: string

Defined in: packages-ts/meta/src/labels.ts:94

namespace?

readonly optional namespace: string

Defined in: packages-ts/meta/src/labels.ts:93

reason

readonly reason: "missing_date" | "missing_station_panel" | "station_disagree" | "collision" | "publication_lag_no_published_at" | "duplicate_settlement_day"

Defined in: packages-ts/meta/src/labels.ts:92

Interfaces

DiscoverResult

Defined in: packages-ts/meta/src/discover.ts:25

Envelope mirrors the Python df.attrs pattern.

Properties

city

readonly city: string

Defined in: packages-ts/meta/src/discover.ts:27

rows

readonly rows: readonly DiscoverRow[]

Defined in: packages-ts/meta/src/discover.ts:26

source

readonly source: "discover"

Defined in: packages-ts/meta/src/discover.ts:28

DiscoverRow

Defined in: packages-ts/meta/src/discover.ts:12

One row per station in the resolved city neighborhood.

Properties

city

readonly city: string

Defined in: packages-ts/meta/src/discover.ts:14

Echo of the input city.

settlesFor

readonly settlesFor: readonly string[]

Defined in: packages-ts/meta/src/discover.ts:21

"<issuer>:<ticker>" markers that resolve against this station. Empty array = denylist backstop surfaced for explicit awareness.

station

readonly station: string

Defined in: packages-ts/meta/src/discover.ts:16

4-char K-prefix ICAO.

ResearchBySourceOptions

Defined in: packages-ts/meta/src/mode2.ts:237

Source-pinned caller-supplied options. Subset of ResearchOptions — source-pinned dispatch returns observations only, so forecast + climate + cache opts are intentionally excluded.

Properties

awcHours?

optional awcHours: number

Defined in: packages-ts/meta/src/mode2.ts:241

AWC lookback window in hours (clamped by the fetcher). Default 168.

iemPolitenessMs?

optional iemPolitenessMs: number

Defined in: packages-ts/meta/src/mode2.ts:243

Polite-delay (ms) between IEM ASOS yearly chunks. Default 1000.

signal?

optional signal: AbortSignal

Defined in: packages-ts/meta/src/mode2.ts:239

Forward to the underlying fetcher; aborts the dispatch.

ResearchOptions

Defined in: packages-ts/meta/src/research.ts:141

Extends

ResearchKwargsExtension

Properties

awcHours?

optional awcHours: number

Defined in: packages-ts/meta/src/research.ts:145

AWC lookback window in hours. Default 168 (AWC max). Clamped by the fetcher.

backend?

optional backend: "pandas" | "polars"

Defined in: packages-ts/meta/src/research.types.ts:59

D-03: accepted but no-op in TS. backend="polars" raises DataAvailabilityError (no Polars in browser/Node TS). Default "pandas" mirrors Python; in TS this is informational only.

Inherited from

ResearchKwargsExtension.backend

cache?

optional cache: null | CacheStore

Defined in: packages-ts/meta/src/research.ts:163

Pluggable cache backend (TS-W3). When omitted, uses defaultCacheStore() (auto-detects IndexedDB → FsStore → MemoryStore). Pass null to opt out of caching entirely.

city?

optional city: string

Defined in: packages-ts/meta/src/research.ts:176

Cross-issuer city selector. Returns rows for every station that any issuer settles against (Kalshi + Polymarket + denylist backstops).

cliPolitenessMs?

optional cliPolitenessMs: number

Defined in: packages-ts/meta/src/research.ts:151

Polite-delay (ms) between successive CLI year requests. Default 1000.

contract?

optional contract: string

Defined in: packages-ts/meta/src/research.ts:180

Single-contract selector. Format: "<issuer>:<id>" (e.g. "kalshi:KXHIGHNYC-25MAY26-T79"). Auto-resolves to the contract’s canonical settlement station via the Phase 8 catalog.

contracts?

optional contracts: readonly string[]

Defined in: packages-ts/meta/src/research.ts:182

Multi-contract selector for basis-trade research.

forecast_model?

optional forecast_model: string

Defined in: packages-ts/meta/src/research.types.ts:35

Single forecast model name (e.g. "gfs", "nbm"). Requires include_forecast=true. Mutually exclusive with forecast_models.

Inherited from

ResearchKwargsExtension.forecast_model

forecast_models?

optional forecast_models: readonly string[]

Defined in: packages-ts/meta/src/research.types.ts:41

Multi-model forecast fan-out. Requires include_forecast=true. Mutually exclusive with forecast_model.

Inherited from

ResearchKwargsExtension.forecast_models

ghcnhPolitenessMs?

optional ghcnhPolitenessMs: number

Defined in: packages-ts/meta/src/research.ts:149

Polite-delay (ms) between successive GHCNh year requests. Default 1000.

granularity?

optional granularity: DatasetGranularity

Defined in: packages-ts/meta/src/research.types.ts:85

Phase 31 31-02 (D-17) — output grain for dataset()/research().

"daily" (default) — one row per LST day; byte-identical to the pre-31 output (parity untouched). Returns PairsRow[].
"observation" — the per-report rows (identical set to obs(granularity="observation")) LEFT-joined by settlementDate with all daily columns. Returns ObservationDatasetRow[]. Row count preserved; label-less days keep null cli_*, rows never dropped.
"hourly" (and any other value) — rejected loudly with a vocabulary error naming the accepted set, validated BEFORE any network fetch. Mirrors the Python dataset() granularity guard.

Inherited from

ResearchKwargsExtension.granularity

iemPolitenessMs?

optional iemPolitenessMs: number

Defined in: packages-ts/meta/src/research.ts:147

Polite-delay (ms) between successive IEM ASOS year chunks. Default 1000.

include_forecast?

optional include_forecast: boolean

Defined in: packages-ts/meta/src/research.types.ts:29

When true, attach fcst_* columns. Phase 17 wired this end-to-end for IEM MOS; other forecast models require Phase 21 follow-up plans.

Default: false.

Inherited from

ResearchKwargsExtension.include_forecast

includeTrades?

optional includeTrades: boolean

Defined in: packages-ts/meta/src/research.ts:199

Attach per-issuer trade timeseries via @mostlyrightmd/markets/trades. Requires contract or contracts.

label?

optional label: LabelValue

Defined in: packages-ts/meta/src/research.ts:219

labels_as_known?

optional labels_as_known: LabelsAsKnown

Defined in: packages-ts/meta/src/research.ts:226

Phase 32 32-05 — labels_as_known discipline for a BYO label. "settled" (default) or "publication_lag" (per-day as_of = settlement-day market close; withholds labels published after close). Only meaningful with a BYO label row-array.

now?

optional now: Date

Defined in: packages-ts/meta/src/research.ts:157

Reference clock for the AWC-window overlap check (test-only seam). Defaults to new Date(). Pass an override to force-include AWC for historical date ranges in unit tests.

onWarning()?

optional onWarning: (w) => void

Defined in: packages-ts/meta/src/research.ts:202

Callback receiving Phase 10 StationOverrideWarning (no warnings.warn() analogue in JS).

Parameters

w

StationOverrideWarning

Returns

void

qc?

optional qc: boolean

Defined in: packages-ts/meta/src/research.types.ts:46

When true, run QC passes and surface QC columns. Default false.

Inherited from

ResearchKwargsExtension.qc

return_type?

optional return_type: "dataframe" | "frame" | "wrapper"

Defined in: packages-ts/meta/src/research.types.ts:70

D-06 output-knob reconciliation (Phase 30 30-04): the canonical value is "dataframe" (matches Python’s winning backend+return_type convention). "frame" is retained as a back-compat alias — both are accepted and validate. "wrapper" remains a no-op in TS (Python returns a MostlyRightResult wrapper when return_type="wrapper"; TS returns plain object arrays with no .attrs divergence to bridge, so the wrapper carries no extra signal). Documented in docs/source-identity.md (30-05).

Inherited from

ResearchKwargsExtension.return_type

signal?

optional signal: AbortSignal

Defined in: packages-ts/meta/src/research.ts:143

Forward to all underlying fetchers; aborts the whole pipeline.

source?

optional source: string

Defined in: packages-ts/meta/src/research.ts:196

Mode 2 single-source pin. FUNCTIONAL: filters the merged observation rows to the requested source’s alias set before daily obs_* aggregation (cli_* unaffected). Accepts any name in RESEARCH_OBSERVATION_SOURCES (the four dotted forms plus bare iem/awc/ghcnh). Mutually exclusive with sources.

sources?

optional sources: readonly string[]

Defined in: packages-ts/meta/src/research.ts:190

Mode 1 multi-source SUBSET selector — dedupe within. Validated in v0.2; its dedupe-within-subset wiring lands in v0.3 (passing it throws). Mutually exclusive with source.

stationOverride?

optional stationOverride: string

Defined in: packages-ts/meta/src/research.ts:186

Override the contract’s canonical settlement station. Emits a StationOverrideWarning via onWarning?; output row carries settlementMismatch: true. Only valid with contract selector.

tz_override?

optional tz_override: string

Defined in: packages-ts/meta/src/research.types.ts:52

IANA timezone override for stations not in the canonical registry. Rarely needed for the 20-station Phase 1 set (all covered).

Inherited from

ResearchKwargsExtension.tz_override

SelectorArgs

Defined in: packages-ts/meta/src/compose.ts:93

Selector kwargs accepted by research(). Exactly one MUST be provided.

Properties

city?

readonly optional city: string

Defined in: packages-ts/meta/src/compose.ts:95

contract?

readonly optional contract: string

Defined in: packages-ts/meta/src/compose.ts:96

contracts?

readonly optional contracts: readonly string[]

Defined in: packages-ts/meta/src/compose.ts:97

station?

readonly optional station: string

Defined in: packages-ts/meta/src/compose.ts:94

StationOverrideWarning

Defined in: packages-ts/meta/src/compose.ts:85

Structured warning emitted when stationOverride deliberately mismatches the contract’s canonical settlement station. The output row carries settlementMismatch: true.

JS has no warnings.warn() analogue; callers receive these via the onWarning? callback in ResearchOptions.

Properties

contractStation

readonly contractStation: string

Defined in: packages-ts/meta/src/compose.ts:87

kind

readonly kind: "StationOverrideWarning"

Defined in: packages-ts/meta/src/compose.ts:86

message

readonly message: string

Defined in: packages-ts/meta/src/compose.ts:89

overrideStation

readonly overrideStation: string

Defined in: packages-ts/meta/src/compose.ts:88

Type Aliases

ByoLabelRow

ByoLabelRow: Readonly<Record<string, unknown>>

Defined in: packages-ts/meta/src/labels.ts:56

A BYO label row. Mirrors the Python BYO minimum contract (D-26): station + date required; published_at optional (enables the publication-discipline labels_as_known="publication_lag" path). Any other key is a label column subject to the collision guard.

DatasetGranularity

DatasetGranularity: "daily" | "observation"

Defined in: packages-ts/meta/src/research.types.ts:96

Phase 31 31-02 (D-17) — accepted dataset()/research() output grains.

Structural row-levels, NOT clock cadences: "hourly" is deliberately absent (native cadence is per-report incl. SPECI + sub-hourly routines — the "observation" grain already exposes that). Passing "hourly" throws a vocabulary error naming this set (mirrors Python).

LabelsAsKnown

LabelsAsKnown: "settled" | "publication_lag"

Defined in: packages-ts/meta/src/labels.ts:65

labels_as_known knob — parity with Python (per-day as_of discipline).

LabelValue

LabelValue: NamedRecipe | null | ReadonlyArray<ByoLabelRow>

Defined in: packages-ts/meta/src/labels.ts:62

The public label option value: a named recipe, an explicit null (features-only, == "none"), or a BYO row-array.

Mode2Source

Mode2Source: SourcePinnedSource

Defined in: packages-ts/meta/src/mode2.ts:81

Deprecated

Phase 30 30-04 (D-11): renamed to SourcePinnedSource. Alias retained for back-compat; scheduled for removal in 2.0.

NamedRecipe

NamedRecipe: typeof NAMED_RECIPES[number]

Defined in: packages-ts/meta/src/labels.ts:43

A named label recipe accepted by dataset({ label }).

ObservationDatasetRow

ObservationDatasetRow: ObsRow & Partial<Omit<PairsRow, "date">>

Defined in: packages-ts/meta/src/observationDataset.ts:67

One observation-grain dataset row: every field of the source ObsRow (report columns, incl. settlementDate) plus the repeated daily PairsRow columns. The daily columns are undefined when the report row’s settlementDate has no matching daily row (a pure LEFT-join miss — e.g. a pre-midnight-UTC report whose LST day fell just outside the window).

SelectorName

SelectorName: typeof SELECTOR_NAMES[number]

Defined in: packages-ts/meta/src/compose.ts:16

SourcePinnedSource

SourcePinnedSource: typeof SOURCE_PINNED_SOURCES[number]

Defined in: packages-ts/meta/src/mode2.ts:68

Source-identity type for source-pinned dispatch. Const-union derived from the SOURCE_PINNED_SOURCES tuple-literal (NOT a TS enum — enum defeats tree-shaking per TS Architect rubric §5).

Variables

MODE2_SOURCES

const MODE2_SOURCES: readonly ["iem.archive", "iem.live", "awc.live", "ghcnh.archive"] = SOURCE_PINNED_SOURCES

Defined in: packages-ts/meta/src/mode2.ts:75

Deprecated

Phase 30 30-04 (D-11): renamed to SOURCE_PINNED_SOURCES as part of the “Mode 1/Mode 2” vocabulary purge. This alias is the SAME tuple — kept working so no consumer breaks; scheduled for removal in 2.0.

NAMED_RECIPES

const NAMED_RECIPES: readonly ["cli", "daily_extremes", "none"]

Defined in: packages-ts/meta/src/labels.ts:40

The named label recipes. Parity with Python NAMED_RECIPES = {"cli", "daily_extremes"} plus the "none" string form of Python’s label=None features-only mode. TS uses the explicit string "none" (JSON-wire-safe; a JSON-round-tripped Python label=None also maps here — see resolveLabel).

Preprocessing

const Preprocessing: __module = preprocessing

Defined in: packages-ts/meta/src/index.ts:178

Deprecated

Use the lowercase preprocessing namespace instead — it matches the Python mostlyright.preprocessing namespace. The PascalCase alias is scheduled for removal in v2.0.0.

RESEARCH_OBSERVATION_SOURCES

const RESEARCH_OBSERVATION_SOURCES: ReadonlySet<string>

Defined in: packages-ts/meta/src/mode2.ts:152

Accepted research({ source }) names — the KEYS of RESEARCH_SOURCE_ALIASES. Byte-identical to Python _VALID_OBSERVATION_SOURCES: iem, iem.archive, iem.live, awc, awc.live, ghcnh, ghcnh.archive.

RESEARCH_SOURCE_ALIASES

const RESEARCH_SOURCE_ALIASES: ReadonlyMap<string, ReadonlySet<string>>

Defined in: packages-ts/meta/src/mode2.ts:136

research()-filter alias table — the Python-parity superset of SOURCE_ALIASES. Extends the narrow dispatch table (the four dotted forms) with the three bare parser tags (iem, awc, ghcnh) rather than re-declaring the shared dotted rows, so the dotted aliases have one source of truth. Mirrors Python _SOURCE_ALIASES (7 entries) verbatim.

SELECTOR_NAMES

const SELECTOR_NAMES: readonly ["station", "city", "contract", "contracts"]

Defined in: packages-ts/meta/src/compose.ts:15

The four mutually-exclusive selector names.

SOURCE_ALIASES

const SOURCE_ALIASES: ReadonlyMap<SourcePinnedSource, ReadonlySet<string>>

Defined in: packages-ts/meta/src/mode2.ts:93

Map each canonical dotted source to the bare parser-emitted tags that satisfy it. Parsers emit bare iem/awc/ghcnh per packages-ts/weather; mostlyright’ canonical vocab is dotted. The alias table bridges both at the boundary without rewriting the per-row source — downstream consumers see the truthful parser-emitted tag.

Mirrors packages/core/src/mostlyright/mode2.py:55-63.

SOURCE_PINNED_SOURCES

const SOURCE_PINNED_SOURCES: readonly ["iem.archive", "iem.live", "awc.live", "ghcnh.archive"]

Defined in: packages-ts/meta/src/mode2.ts:56

Source-pinned dispatch vocabulary. Exactly four dotted values.

Phase 30 30-04 (D-11/D-02/D-04): renamed from MODE2_SOURCES as part of the “Mode 1/Mode 2” vocabulary purge. MODE2_SOURCES remains exported as a deprecated alias (same tuple) so no consumer breaks; removal at 2.0.

version

const version: "1.15.0" = "1.15.0"

Defined in: packages-ts/meta/src/index.ts:187

Placeholder version string for the meta package. The authoritative package version lives in package.json#version (currently 0.1.0-rc.7); this constant has not been bumped. Sibling packages (@mostlyrightmd/core / weather / markets) each export their own version constant, exposed here via the namespaced module objects.

Functions

_resetDefaultLabelWarning()

_resetDefaultLabelWarning(): void

Defined in: packages-ts/meta/src/research.ts:238

Reset the one-time D-22 default-label FutureWarning latch — TEST USE ONLY.

Returns

void

annotateSettlesFor()

annotateSettlesFor(station, city): readonly string[]

Defined in: packages-ts/meta/src/compose.ts:225

Return the list of "<issuer>:<ticker>" markers that settle against station for city. Empty array when no issuer settles against this station (typically a denylist backstop).

Parameters

station

string

city

null | string

Returns

readonly string[]

assertSourceIdentity()

assertSourceIdentity<Row>(rows, expected, role): void

Defined in: packages-ts/meta/src/mode2.ts:194

Throw SourceMismatchError if any row’s source field disagrees with the expected source vocabulary. Rows missing the source field (undefined / null / non-string) are skipped (matches Python mode2.py:181-182 — if "source" not in df.columns: return). Empty rows passes silently.

The expected parameter accepts EITHER:

a single string — the most common case; downstream callers can pass "iem.archive" and the check is src === "iem.archive".
a ReadonlySet<string> — used by researchBySource to pass the SOURCE_ALIASES entry so bare-form parser tags ('iem') are accepted alongside the dotted canonical form ('iem.archive'). Without this, the per-row source-preserved invariant (Python mode2.py:161-166) would force the assertion to fire on every source-pinned call.

Type Parameters

• Row extends object

Parameters

rows

readonly Row[]

rows to check (any shape with source?: string)

expected

the source string OR alias-set the caller asked for

string | ReadonlySet<string>

role

SourceMismatchRole = "observations"

role-name vocabulary; defaults to ‘observations’

Returns

void

Throws

SourceMismatchError with schemaSource = the expected label (the input string, or [...accept].sort().join("|") when an alias-set was passed), dataSource = first sorted distinct mismatched source, role = the caller-provided role, catalogWarning = null.

buildOverrideWarning()

buildOverrideWarning(contractStation, overrideStation): StationOverrideWarning

Defined in: packages-ts/meta/src/compose.ts:251

Build a structured StationOverrideWarning payload. Callers receive these via the optional onWarning? callback on research options.

Parameters

contractStation

string

overrideStation

string

Returns

StationOverrideWarning

dataset()

Call Signature

dataset(station, fromDate, toDate, opts): Promise<readonly ObservationDatasetRow[]>

Defined in: packages-ts/meta/src/research.ts:1506

Leakage-safe composed training table for a station + date window — the PRIMARY documented name (30-04 D-02).

dataset() is the general-first entry point: an OMITTED label still returns the cli_* columns byte-identically today, but emits a ONE-TIME D-22 FutureWarning (“default flips to label=null at 2.0 — pass label=‘cli’ or label=null”). Pass an explicit label to silence the bridge and pin the output ("cli" for today’s shape, null/"none" for features-only, "daily_extremes" for the WU/NOAA-WRH quantity, or a BYO row-array).

See ResearchOptions for the full options surface.

Parameters

station

string

fromDate

string

toDate

string

opts

ResearchOptions & object

Returns

Promise<readonly ObservationDatasetRow[]>

Call Signature

dataset(station, fromDate, toDate, opts?): Promise<readonly PairsRow[]>

Defined in: packages-ts/meta/src/research.ts:1512

Leakage-safe composed training table for a station + date window — the PRIMARY documented name (30-04 D-02).

See ResearchOptions for the full options surface.

Parameters

station

string

fromDate

string

toDate

string

opts?

ResearchOptions & object

Returns

Promise<readonly PairsRow[]>

Call Signature

dataset(station, fromDate, toDate, opts?): Promise<readonly PairsRow[] | readonly ObservationDatasetRow[]>

Defined in: packages-ts/meta/src/research.ts:1518

Leakage-safe composed training table for a station + date window — the PRIMARY documented name (30-04 D-02).

See ResearchOptions for the full options surface.

Parameters

station

string

fromDate

string

toDate

string

opts?

ResearchOptions

Returns

Promise<readonly PairsRow[] | readonly ObservationDatasetRow[]>

discover()

discover(args): DiscoverResult

Defined in: packages-ts/meta/src/discover.ts:46

Return per-station discovery table for city.

Each row shows one settlement station + the issuer:ticker markers that resolve against it. Stations in the per-city Polymarket denylist also appear with empty settlesFor so quants see the full neighborhood before deciding whether to use stationOverride.

Parameters

args

city

string

Returns

DiscoverResult

Example

1
const result = discover({ city: "NYC" });
2
  // rows include {station: "KNYC", settlesFor: ["kalshi:NYC"]},
3
  //              {station: "KLGA", settlesFor: ["polymarket:nyc"]},
4
  //              {station: "KJFK", settlesFor: []},  // denylist
5
  //              {station: "KEWR", settlesFor: []}.

isMode2Source()

isMode2Source(value): value is “iem.archive” | “iem.live” | “awc.live” | “ghcnh.archive”

Defined in: packages-ts/meta/src/mode2.ts:117

Parameters

value

unknown

Returns

value is “iem.archive” | “iem.live” | “awc.live” | “ghcnh.archive”

Deprecated

Phase 30 30-04 (D-11): renamed to isSourcePinnedSource. Alias retained for back-compat; scheduled for removal in 2.0.

isNamedRecipe()

isNamedRecipe(v): v is “cli” | “none” | “daily_extremes”

Defined in: packages-ts/meta/src/labels.ts:46

True when v is one of the named recipes.

Parameters

v

unknown

Returns

v is “cli” | “none” | “daily_extremes”

isResearchObservationSource()

isResearchObservationSource(value): boolean

Defined in: packages-ts/meta/src/mode2.ts:161

Type-guard: true iff value is an accepted research({ source }) name. WIDER than isMode2Source — accepts bare parser tags too, matching Python’s source in _VALID_OBSERVATION_SOURCES membership check.

Parameters

value

unknown

Returns

boolean

isSourcePinnedSource()

isSourcePinnedSource(value): value is “iem.archive” | “iem.live” | “awc.live” | “ghcnh.archive”

Defined in: packages-ts/meta/src/mode2.ts:109

Type-guard: narrow an unknown value to SourcePinnedSource. Returns true iff value is one of the four canonical dotted strings. Bare-form inputs ('iem', 'awc', 'ghcnh') return false — TS narrows what Python widens.

Parameters

value

unknown

Returns

value is “iem.archive” | “iem.live” | “awc.live” | “ghcnh.archive”

research()

Call Signature

research(station, fromDate, toDate, opts): Promise<readonly ObservationDatasetRow[]>

Defined in: packages-ts/meta/src/research.ts:1466

Leakage-safe composed training table for a station + date window.

research() is the legacy entry point: an OMITTED label returns the cli_* columns and NEVER emits the D-22 FutureWarning (the implicit-cli behavior is retained for the legacy name until 2.0). Prefer dataset() for new code — it is the primary documented name and surfaces the D-22 bridge warning so callers migrate before the 2.0 default flip.

See ResearchOptions for the full options surface (label axis, granularity, source pin, forecast, cache).

Parameters

station

string

fromDate

string

toDate

string

opts

ResearchOptions & object

Returns

Promise<readonly ObservationDatasetRow[]>

Call Signature

research(station, fromDate, toDate, opts?): Promise<readonly PairsRow[]>

Defined in: packages-ts/meta/src/research.ts:1472

Leakage-safe composed training table for a station + date window.

See ResearchOptions for the full options surface (label axis, granularity, source pin, forecast, cache).

Parameters

station

string

fromDate

string

toDate

string

opts?

ResearchOptions & object

Returns

Promise<readonly PairsRow[]>

Call Signature

research(station, fromDate, toDate, opts?): Promise<readonly PairsRow[] | readonly ObservationDatasetRow[]>

Defined in: packages-ts/meta/src/research.ts:1478

Leakage-safe composed training table for a station + date window.

See ResearchOptions for the full options surface (label axis, granularity, source pin, forecast, cache).

Parameters

station

string

fromDate

string

toDate

string

opts?

ResearchOptions

Returns

Promise<readonly PairsRow[] | readonly ObservationDatasetRow[]>

researchBySource()

researchBySource(station, source, fromDate, toDate, opts): Promise<readonly Observation[]>

Defined in: packages-ts/meta/src/mode2.ts:368

Source-pinned observation fetch.

Dispatches to a single source’s fetcher (no merge) and returns raw Observations tagged with that source. Mirrors Python mostlyright.mode2.research_by_source (packages/core/src/mostlyright/mode2.py).

The four supported sources:

'iem.archive' → IEM ASOS historical CSVs (METAR + SPECI).
'iem.live' → v0.1.0 parity gap; throws. Use 'iem.archive'.
'awc.live' → AWC live METAR JSON (≤168h lookback).
'ghcnh.archive' → NCEI GHCNh PSV (US stations only).

The returned rows preserve the parser-emitted per-row source field verbatim — NEVER rewritten to the dotted canonical form. Bare tags ('iem', 'awc', 'ghcnh') survive intact so downstream Validator schemas see the truthful provenance. Source-pinned dispatch still calls assertSourceIdentity internally (defense-in-depth) before returning — using the SOURCE_ALIASES entry so the bare-form tags pass.

Parameters

station

string

NWS 3-letter code (e.g. "NYC") OR 4-letter ICAO (e.g. "KNYC").

source

One of SOURCE_PINNED_SOURCES.

"iem.archive" | "iem.live" | "awc.live" | "ghcnh.archive"

fromDate

string

Inclusive start, ISO YYYY-MM-DD.

toDate

string

Inclusive end, ISO YYYY-MM-DD.

opts

ResearchBySourceOptions = {}

See ResearchBySourceOptions.

Returns

Promise<readonly Observation[]>

Frozen array of Observations whose source is in SOURCE_ALIASES.get(source). Empty array on no data (NOT a throw).

Throws

Error if source is not one of SOURCE_PINNED_SOURCES. Throws BEFORE any network call — no quota burn on invalid input.

Throws

Error if source === 'iem.live' (v0.1.0 parity gap; v0.2 will add per-month live IEM).

Throws

Error if station is unknown, or dates are malformed.

Throws

NotFoundError if source === 'ghcnh.archive' and station is non-US (GHCNh PSV files are US-only).

Throws

SourceMismatchError if a row’s source disagrees with the alias set for source (defense-in-depth; should never fire under correct fetcher behavior).

resolveCity()

resolveCity(city): readonly string[]

Defined in: packages-ts/meta/src/compose.ts:187

Resolve a city slug to all stations any issuer settles against. Returns deduplicated array in stable order: Kalshi → Polymarket default/high/low → Polymarket denylist backstops.

Parameters

city

string

Returns

readonly string[]

resolveContract()

resolveContract(contractId): readonly [string, string]

Defined in: packages-ts/meta/src/compose.ts:133

Resolve a "<issuer>:<id>" contract id to [station, issuer].

Supported: kalshi:KHIGH<CITY> / kalshi:KXHIGH<CITY>-<DATE>-<STRIKE> and kalshi:KLOW<CITY> / kalshi:KXLOW<CITY>-<DATE>-<STRIKE>.

Polymarket contract resolution requires an event_id → station lookup (via polymarket-discover); Phase 10 v0.2 defers to v0.3 and throws.

Parameters

contractId

string

Returns

readonly [string, string]

validateSelectors()

validateSelectors(args): "station" | "city" | "contracts" | "contract"

Defined in: packages-ts/meta/src/compose.ts:104

Validate selector arity. Returns the active selector name; throws when zero or >1 selectors are provided.

Parameters

args

SelectorArgs

Returns

"station" | "city" | "contracts" | "contract"