@mark1russell7/stack-hazards 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mark Russell
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,81 @@
1
- # Temporary Holding Version
1
+ # @mark1russell7/stack-hazards
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Hazard cases as reference data. Each case tells the public supplies that it can stop, and the source of each claim. Each cut has a law of the duration of the stop, or no read.
4
+
5
+ It is an add-on of [`@mark1russell7/system-stack`](../system-stack/README.md). It gives the values of `CaseCuts` of the core, and [`@mark1russell7/stack-endurance`](../stack-endurance/README.md) calculates with them. The cases have generic names and codes of an alert taxonomy, for example `met.winter.storm`. The data names no person and no place.
6
+
7
+ Each function is a plain function with no clock, no network and no file.
8
+
9
+ ## The records
10
+
11
+ | Record | What it tells |
12
+ | --- | --- |
13
+ | `SUPPLY_PARTS` | The reference parts: the public supplies that a case can stop, for example `power.grid` and `water.main`. Each one is a failure domain of many stacks. |
14
+ | `Source` | A public page or dataset: its URL, its publisher, its license, the date of its last change and the date of the read. |
15
+ | `Claim` | The reason for a cut: a source that tells that the case can stop the part, or the definition of the case. The text is in own words, not a quote. |
16
+ | `DurationLaw` | A survival curve of the duration for each region of its source, with its fit. |
17
+ | `NoLaw` | No law is read yet. The cut has no curve, so its draws are no read. |
18
+ | `Hazard` | A case: its code, its name, its cuts and the sources that the dataset examined for it. |
19
+
20
+ ## The rules of the data
21
+
22
+ 1. A cut is in a case only when a source names it, or when the case is the stop of the part by definition.
23
+ 2. A supply with no cut in a case is no read, not a pass. `supplyState` tells it.
24
+ 3. Each cut has a law with its source, its license and its fit, or an explicit no read.
25
+ 4. A regional law covers each region of its source, not only one chosen region. The region of the user is input data.
26
+ 5. The fits come from `@mark1russell7/rigor-statistics`. The fetches of a source go through `polite-crawler`.
27
+
28
+ `checkHazards` is the gate of the rules. It refuses a law with no source or no license, and a law with no curve for a region of its source. It gives a warning for each cut with no law.
29
+
30
+ ## A first look
31
+
32
+ ```ts
33
+ import { HAZARD_LIST, hazardCase, hazardOf, supplyState } from "@mark1russell7/stack-hazards";
34
+
35
+ const storm = hazardOf(HAZARD_LIST, "met.winter.storm");
36
+ if (storm !== undefined) {
37
+ // The values of CaseCuts, for a stack with its own id of the grid.
38
+ const cuts = hazardCase(HAZARD_LIST, storm, { parts: { "power.grid": ["home-power"] } });
39
+ console.log(cuts.cuts.map((cut) => cut.part)); // ["home-power", "phone.network", "road.local"]
40
+ console.log(supplyState(storm, "water.main")); // { state: "no-read" }
41
+ }
42
+ ```
43
+
44
+ A part of a stack that needs a public supply names a reference id in its needs. Or the option `parts` maps each reference id to the ids of the stack. An empty list tells that the stack does not have the supply.
45
+
46
+ ## The sources
47
+
48
+ The claims of 0.1.0 come from the hazard pages of FEMA (Ready.gov) and of the National Weather Service. Each is a work of the United States federal government, in the public domain. The record of each source has the page of its terms of reuse.
49
+
50
+ The law of the grid cut of a power outage comes from EAGLE-I of Oak Ridge National Laboratory (CC BY 4.0, DOI `10.6084/m9.figshare.24237376`). It has one curve for each state, the District of Columbia, Puerto Rico and the US Virgin Islands. The curves are a derived work.
51
+
52
+ This law is for all causes. The grid cut of each storm case has a law of its own, from the outages that start in a storm event of the case. The law has a source of its own. Its regions are the states with 30 such outages or more. Each other cut has no law.
53
+
54
+ ## The laws from outage records
55
+
56
+ These functions make a law of a duration from the records of a source of outages. They do no fetch.
57
+
58
+ | Function | What it does |
59
+ | --- | --- |
60
+ | `outageReader(options)` | It reads the counts of the customers out of power in each area at each time of the collection. It gives the events and a tally. |
61
+ | `eagleLine(line)`, `eagleCustomers(text)`, `eagleRegion(area)` | They read a line of an outage file of EAGLE-I, the file of the customers of each county, and the state of a county. |
62
+ | `outageCurves(events, region)` | It gives the Kaplan-Meier curve of the durations of each region, with its counts and its median. |
63
+ | `survivalOf(curve)` | It gives a Kaplan-Meier curve in the form of the core, read at the days of `LAW_DAYS`, from 15 minutes to 90 days. |
64
+
65
+ - An event is a run of the times of an area with a count at or above the threshold of the area. The threshold is a share of the customers of the area.
66
+ - A gap of the collection, or the end of the data, censors an event. A run that starts at the start of the data or after a gap is not an event.
67
+ - A line of an area with no count stops the observation of that area. It censors an open event, and a run at the next time of the area is not an event.
68
+ - The order of the areas is free. A file in the order of the counties and a file in the order of the times give the same events.
69
+ - An open tail is a curve that does not get to 0. Its last chance falls to 0 at two times the largest observed time.
70
+
71
+ EAGLE-I is the dataset of the outages of each county of the United States from Oak Ridge National Laboratory. Its license is CC BY 4.0. A curve from it is a derived work, and it keeps the attribution of the source. The dataset does not reliably have outages of less than 15 minutes.
72
+
73
+ The workflow `hazards-fit` of the repository makes the curves of EAGLE-I in CI. The script `scripts/eaglei-fit.ts` reads each file in range requests through `polite-crawler` and examines its MD5. The output is the artifact `eaglei-laws`. Then the script `scripts/eaglei-law.ts` makes the module `src/eaglei-law.ts` from the artifact. A state with fewer than 30 events gets no curve. The package on npm does not have the scripts.
74
+
75
+ The fit job also reads the details files of NOAA Storm Events and the zone-county file of the National Weather Service. Each is in the public domain. An outage is in a case when a storm event of the case covers its county at its start. The window starts 1 hour before the event and ends 3 hours after it. The table `STORM_CLASSES` gives the event types of each case. The match is in time and place only, so it does not prove the cause of an outage.
76
+
77
+ ## The entries
78
+
79
+ | Entry | What it has |
80
+ | --- | --- |
81
+ | `@mark1russell7/stack-hazards` | The records, the reference data, the gate and `hazardCase`. |
@@ -0,0 +1,385 @@
1
+ import { CaseCuts, Fault, Part, Survival } from "@mark1russell7/system-stack";
2
+ import { SurvivalCurve } from "@mark1russell7/rigor-statistics";
3
+ /** A date as `YYYY-MM-DD`. */
4
+ export type IsoDate = string;
5
+ /**
6
+ * The reference parts: the public supplies that a hazard case can stop. Each part is one failure domain of many stacks.
7
+ * A part of a stack that needs a public supply names one of these ids in its needs. Or the option `parts` of `hazardCase` maps the id.
8
+ * The `kind` of each part is the kind of a part of system-stack.
9
+ */
10
+ export declare const SUPPLY_PARTS: readonly Part[];
11
+ /** The license of a source. */
12
+ export interface License {
13
+ /** The name of the license, for example "Public domain". */
14
+ readonly name: string;
15
+ /** The page that tells the terms of the reuse. */
16
+ readonly url: string;
17
+ }
18
+ /** The regions of a source: the scheme of the codes and each code that the source covers. */
19
+ export interface Regions {
20
+ /** The scheme of the codes, for example `us-state`. */
21
+ readonly scheme: string;
22
+ readonly codes: readonly string[];
23
+ }
24
+ /** A source: a public page or a public dataset. */
25
+ export interface Source {
26
+ /** A short name of the source. */
27
+ readonly name: string;
28
+ readonly url: string;
29
+ /** The organization that publishes the source. */
30
+ readonly publisher: string;
31
+ readonly license: License;
32
+ /** The date that the source shows as its last change. */
33
+ readonly updated?: IsoDate | undefined;
34
+ /** The date of the read of the source. */
35
+ readonly read: IsoDate;
36
+ /** The regions that the source covers. A source of a law of a duration must have its regions. */
37
+ readonly regions?: Regions | undefined;
38
+ }
39
+ /**
40
+ * A claim: the reason to put a cut in a case. A claim is a source that tells that the case can stop the part.
41
+ * Or a claim is the definition of the case, when the case is the stop of the part. The text `says` tells the claim in own words.
42
+ * It is not a quote.
43
+ */
44
+ export type Claim = {
45
+ readonly source: string;
46
+ readonly definition?: never;
47
+ readonly says: string;
48
+ } | {
49
+ readonly definition: true;
50
+ readonly source?: never;
51
+ readonly says: string;
52
+ };
53
+ /** The fit of a law of a duration. */
54
+ export interface Fit {
55
+ /** The family of the law, for example `lognormal`. */
56
+ readonly family: string;
57
+ /** The method of the fit, for example `maximum likelihood`. The fit comes from `@mark1russell7/rigor-statistics`. */
58
+ readonly method: string;
59
+ /** The count of the events of the fit. */
60
+ readonly count: number;
61
+ }
62
+ /**
63
+ * A law of the duration of a cut: a survival curve for each region of its source.
64
+ * A regional law covers each region of its source, not only one chosen region. The region of a user is input data.
65
+ */
66
+ export interface DurationLaw {
67
+ readonly read: true;
68
+ /** The id of the source of the law. The source must have a license and regions. */
69
+ readonly source: string;
70
+ readonly fit: Fit;
71
+ /** The scheme of the region codes. It is the scheme of the regions of the source. */
72
+ readonly scheme: string;
73
+ /** The survival curve of the duration in each region, by the code of the region. */
74
+ readonly curves: Readonly<Record<string, Survival>>;
75
+ }
76
+ /** No law of a duration: no source with a law is read yet. A cut with no law has no curve, so its draws are no read, not a pass. */
77
+ export interface NoLaw {
78
+ readonly read: false;
79
+ /** The reason, in plain words. */
80
+ readonly reason: string;
81
+ }
82
+ /** A cut of a hazard case: a reference part that the case can stop, the claims of the cut and the law of the duration. */
83
+ export interface HazardCut {
84
+ /** The `id` of a reference part of `SUPPLY_PARTS`. */
85
+ readonly part: string;
86
+ /** The printed name of the cut, for example "No power from the grid". */
87
+ readonly title: string;
88
+ /** The claims of the cut. A cut has one claim or more. */
89
+ readonly claims: readonly Claim[];
90
+ readonly duration: DurationLaw | NoLaw;
91
+ }
92
+ /**
93
+ * A hazard case: an event that can stop some public supplies at the same time.
94
+ * A supply with no cut in the case is no read: no source that the dataset read tells that the case can stop it. It is not a pass.
95
+ */
96
+ export interface Hazard {
97
+ /** The code of the case, a code of the alert taxonomy, for example `met.winter.storm`. */
98
+ readonly case: string;
99
+ /** The printed name of the case. */
100
+ readonly title: string;
101
+ readonly cuts: readonly HazardCut[];
102
+ /** The ids of the sources that the dataset read for the case, also the sources that name no cut. */
103
+ readonly examined: readonly string[];
104
+ }
105
+ /** The name of the format of a list of hazard cases. */
106
+ export declare const HAZARDS_SCHEMA = "hazards/1";
107
+ /** A list of hazard cases with the table of its sources. */
108
+ export interface HazardList {
109
+ readonly schema: typeof HAZARDS_SCHEMA;
110
+ /** The sources, by id. */
111
+ readonly sources: Readonly<Record<string, Source>>;
112
+ readonly hazards: readonly Hazard[];
113
+ }
114
+ /** The sources of the reference data, by id. */
115
+ export declare const HAZARD_SOURCES: Readonly<Record<string, Source>>;
116
+ /** The duration of each cut with no law yet. Only the grid cuts have laws, from EAGLE-I: for all causes, and for each storm case. */
117
+ export declare const NO_LAW: NoLaw;
118
+ /** The duration of the grid cut of a storm case with no state of 30 outages of EAGLE-I in the storm events of the case. */
119
+ export declare const NO_STORM_LAW: NoLaw;
120
+ /**
121
+ * The reference list of hazard cases. A case has a generic name and a code of the alert taxonomy.
122
+ * The list names no person and no place. The region of a user is input data of `hazardCase`.
123
+ */
124
+ export declare const HAZARD_LIST: HazardList;
125
+ /**
126
+ * These are the codes of the gate. Each code is an error, except `hazards-no-law`, which is a warning.
127
+ *
128
+ * - `hazards-twice`: two cases have one code, or a case cuts one part two times.
129
+ * - `hazards-part-unknown`: a cut names a part that is not a reference part.
130
+ * - `hazards-no-claim`: a cut has no claim.
131
+ * - `hazards-source`: a claim, a law or the list `examined` names a source that the table does not have.
132
+ * Or a source has no name, no URL, no publisher or a wrong date.
133
+ * - `hazards-license`: a source has no license name or no license URL.
134
+ * - `hazards-law-region`: the source of a law has no regions, or the law has another scheme.
135
+ * Or the law has no curve for a region of its source.
136
+ * - `hazards-fit`: the fit of a law has no family, no method, or a count of events that is not a whole number above 0.
137
+ * - `hazards-curve`: a curve of a law does not have the form of a survival curve.
138
+ * - `hazards-no-law` (warning): a cut has no law of its duration. Its draws are no read in the shortfall.
139
+ */
140
+ export declare const HAZARD_CODES: readonly ["hazards-twice", "hazards-part-unknown", "hazards-no-claim", "hazards-source", "hazards-license", "hazards-law-region", "hazards-fit", "hazards-curve", "hazards-no-law"];
141
+ /** A code of the gate of a list of hazard cases. */
142
+ export type HazardCode = (typeof HAZARD_CODES)[number];
143
+ /** A fault of a list of hazard cases. */
144
+ export interface HazardFault extends Fault {
145
+ readonly code: HazardCode;
146
+ }
147
+ /**
148
+ * This function gives each fault of a list of hazard cases. A list with no error tells that the gate passes.
149
+ * The reference parts are `SUPPLY_PARTS` by default. The faults are in the order of the list. The function is pure.
150
+ */
151
+ export declare function checkHazards(list: HazardList, parts?: readonly Part[]): HazardFault[];
152
+ /** This function tells if a list of faults has an error. */
153
+ export declare function hasHazardError(faults: readonly HazardFault[]): boolean;
154
+ /** The options of `hazardCase`. */
155
+ export interface HazardCaseOptions {
156
+ /** The region of the user, as a code of a scheme. A law with no curve for it gives a cut with no curve. */
157
+ readonly region?: {
158
+ readonly scheme: string;
159
+ readonly code: string;
160
+ } | undefined;
161
+ /**
162
+ * The ids of the parts of the stack for each reference part, when the stack does not use the reference ids.
163
+ * A reference part with an empty list is not in the stack, so the case has no cut of it. The default is the reference id.
164
+ */
165
+ readonly parts?: Readonly<Record<string, readonly string[]>> | undefined;
166
+ }
167
+ /** The state of a supply in a case: the cut, or no read when no source that the dataset read names the cut. */
168
+ export type SupplyState = {
169
+ readonly state: "cut";
170
+ readonly cut: HazardCut;
171
+ } | {
172
+ readonly state: "no-read";
173
+ };
174
+ /** This function gives the case of a code, or `undefined`. */
175
+ export declare function hazardOf(list: HazardList, code: string): Hazard | undefined;
176
+ /** This function gives the state of a reference part in a case. A part with no cut is no read, not a pass. */
177
+ export declare function supplyState(hazard: Hazard, part: string): SupplyState;
178
+ /**
179
+ * This function gives a hazard case as the values of `CaseCuts` of stack-endurance. Each cut gets the curve of the region of the user.
180
+ * A cut with no law, or with no curve for the region, has no `duration`. Then the shortfall gives no read for its draws.
181
+ * The source of each cut is the URL of the source of its law, or the URLs of its claims. The function is pure.
182
+ */
183
+ export declare function hazardCase(list: HazardList, hazard: Hazard, options?: HazardCaseOptions): CaseCuts;
184
+ /** One count of a source of outages: the customers out of power in an area at one time of the collection. */
185
+ export interface OutageCount {
186
+ /** The code of the area, for example the FIPS code of a county. */
187
+ readonly area: string;
188
+ /**
189
+ * The count of the customers out of power. It is `undefined` when the source has a line of the area at the time with no count.
190
+ * Then the observation of the area stops at that time. An open run is censored, and a run at the next time has no known start.
191
+ */
192
+ readonly out: number | undefined;
193
+ /** The time of the collection, in seconds from 1970-01-01T00:00:00Z. */
194
+ readonly time: number;
195
+ }
196
+ /** An event of an area: a run of the times of the collection with a count at or above the threshold of the area. */
197
+ export interface OutageEvent {
198
+ readonly area: string;
199
+ /** The first time of the run, in seconds from 1970-01-01T00:00:00Z. */
200
+ readonly start: number;
201
+ /** The duration in seconds: the last time of the run, less the first time, plus one interval of the collection. */
202
+ readonly seconds: number;
203
+ /** The largest count of the run. */
204
+ readonly peak: number;
205
+ /** When `censored` is true, a gap of the collection or the end of the data stopped the observation. Then `seconds` is a lower bound. */
206
+ readonly censored: boolean;
207
+ }
208
+ /** The options of a read of outage counts. */
209
+ export interface OutageOptions {
210
+ /** The customers of each area, by the code of the area. */
211
+ readonly customers: ReadonlyMap<string, number>;
212
+ /** The threshold of an area as a share of its customers. The default is 0.01. With 0, the threshold is `least` and needs no customers. */
213
+ readonly share?: number | undefined;
214
+ /** The lowest threshold, as a count of customers. The default is 1. */
215
+ readonly least?: number | undefined;
216
+ /** The interval of the collection in seconds. The default is 900, 15 minutes. A step of more than 1.5 intervals is a gap. */
217
+ readonly interval?: number | undefined;
218
+ }
219
+ /** The counts of a read. */
220
+ export interface OutageTally {
221
+ /** The counts that the reader took. */
222
+ readonly counts: number;
223
+ /** The times of the collection: each time with one count or more. */
224
+ readonly times: number;
225
+ /** The counts with a time that is not after the last time of their area. The reader does not use them. */
226
+ readonly repeats: number;
227
+ /** The counts of an area with no count of customers. The reader does not use them. */
228
+ readonly unknown: number;
229
+ /** The lines of an area at a time with no count (`out` is `undefined`). The observation of the area stops at each of them. */
230
+ readonly missing: number;
231
+ /** The runs that start at the start of the data, after a gap or after a line with no count. Their start is not known, so they are not events. */
232
+ readonly truncated: number;
233
+ }
234
+ /** The result of a read: the events, from the earliest start, and the tally. */
235
+ export interface OutageRuns {
236
+ readonly events: readonly OutageEvent[];
237
+ readonly tally: OutageTally;
238
+ }
239
+ /** A reader of outage counts. It keeps only the open run of each area, the runs and the set of the times of the collection. */
240
+ export interface OutageReader {
241
+ /** This function adds one count. The times of each area must increase. */
242
+ add(count: OutageCount): void;
243
+ /** This function gives the events and the tally. After it, the reader takes no count. */
244
+ finish(): OutageRuns;
245
+ }
246
+ /**
247
+ * This function gives a reader of outage counts.
248
+ *
249
+ * - The threshold of an area is the larger of `least` and `share` times its customers, up to the next whole number.
250
+ * - A run ends at a count under the threshold, or at a time of the collection with no count of the area.
251
+ * - The end of a run is observed when the collection has a time within 1.5 intervals after the run. Else the event is censored.
252
+ * - The start of a run is known when the collection has a time within 1.5 intervals before the run. Else the run is truncated.
253
+ * - A line with no count stops the observation of its area. An open run is censored. A run at the next time of the area is truncated.
254
+ *
255
+ * @param options - The customers of each area and the threshold
256
+ * @returns The reader
257
+ */
258
+ export declare function outageReader(options: OutageOptions): OutageReader;
259
+ /** The scheme of the region codes of a law from EAGLE-I: the 2-digit FIPS code of a state. */
260
+ export declare const EAGLE_SCHEME = "us-state-fips";
261
+ /** The interval of the collection of EAGLE-I, in seconds. */
262
+ export declare const EAGLE_INTERVAL = 900;
263
+ /**
264
+ * This function reads one line of an outage file of EAGLE-I. It gives `undefined` for the header and for a line that it cannot read.
265
+ * The columns change from year to year. This function reads the FIPS code in the first column, the time and the count before the time.
266
+ * A county name with a comma in quotes does not move these columns. The function reads each time as UTC.
267
+ *
268
+ * An empty count gives `out: undefined`: the file has the county at the time, with no count.
269
+ */
270
+ export declare function eagleLine(line: string): OutageCount | undefined;
271
+ /** This function reads the file of the modeled customers of each county of EAGLE-I (`MCC.csv`). It gives the customers by the 5-digit FIPS code. */
272
+ export declare function eagleCustomers(text: string): Map<string, number>;
273
+ /** This function gives the region of a county of EAGLE-I: the 2-digit FIPS code of its state, in the scheme `us-state-fips`. */
274
+ export declare function eagleRegion(area: string): string;
275
+ /**
276
+ * The days at which a law reads a curve, from 15 minutes to 90 days. Each day under 1 is a count of minutes over 1440.
277
+ * Thus it is equal to a count of seconds over 86400 for the same time.
278
+ */
279
+ export declare const LAW_DAYS: readonly number[];
280
+ /** The options of the form of a curve. */
281
+ export interface SurvivalOptions {
282
+ /** The days at which the curve is read. They are more than 0 and they increase. The default is `LAW_DAYS`. */
283
+ readonly days?: readonly number[] | undefined;
284
+ /** The day at which an open tail gets to 0. It is more than the largest observed time. The default is two times that time. */
285
+ readonly end?: number | undefined;
286
+ }
287
+ /**
288
+ * This function gives a survival curve of the core from a Kaplan-Meier curve in days.
289
+ * It reads the chance at each day of `days`, up to the largest observed time. Between two days, the chance of the core is linear.
290
+ * An open tail is a curve that does not get to 0, because of a censored time at the end. Its last chance falls linearly to 0 at `end`.
291
+ */
292
+ export declare function survivalOf(curve: SurvivalCurve, options?: SurvivalOptions): Survival;
293
+ /** The curve of the durations of one region, with its counts. */
294
+ export interface RegionCurve {
295
+ /** The survival curve of the duration, in days. */
296
+ readonly curve: Survival;
297
+ /** The count of the events of the region. */
298
+ readonly count: number;
299
+ /** The count of the censored events. */
300
+ readonly censored: number;
301
+ /** The chance at the largest observed time. The curve closes it to 0 at its end. It is 0 when the curve gets to 0. */
302
+ readonly open: number;
303
+ /** The median duration in days, or `undefined` when the curve does not get to a chance of 0.5. */
304
+ readonly median: number | undefined;
305
+ }
306
+ /**
307
+ * This function gives the curve of the durations of the events of each region. The keys are the codes of the regions, in their order.
308
+ *
309
+ * @param events - The events, for example of `outageReader`
310
+ * @param region - The region of an area, for example `eagleRegion`
311
+ * @param options - The form of each curve
312
+ * @returns The curve of each region with one event or more
313
+ */
314
+ export declare function outageCurves(events: readonly OutageEvent[], region: (area: string) => string, options?: SurvivalOptions): Readonly<Record<string, RegionCurve>>;
315
+ /**
316
+ * The event types of NOAA Storm Events for each hazard case, by the names of NWS Instruction 10-1605.
317
+ * A type that is not in the table gives no case. A type is in one case only.
318
+ */
319
+ export declare const STORM_CLASSES: Readonly<Record<string, readonly string[]>>;
320
+ /** The kind of the area of a row of Storm Events: a county (`C`), a public forecast zone (`Z`) or a marine zone (`M`). */
321
+ export type StormArea = "C" | "Z" | "M";
322
+ /** One row of a details file of Storm Events. */
323
+ export interface StormRow {
324
+ /** The event type, for example `Tornado`. */
325
+ readonly type: string;
326
+ readonly kind: StormArea;
327
+ /** The FIPS code of the state (2 digits) and the code of the county or the zone (3 digits). */
328
+ readonly area: string;
329
+ /** The start of the event, in seconds of UTC. */
330
+ readonly begin: number;
331
+ /** The end of the event, in seconds of UTC. */
332
+ readonly end: number;
333
+ }
334
+ /**
335
+ * This function reads one line of a details file of Storm Events. It reads only the first 19 fields, before the narratives.
336
+ * The file gives each time in the local standard time of the area. The field `CZ_TIMEZONE` has the offset, for example `CST-6`.
337
+ *
338
+ * @returns The row, or undefined for the header, a part of a broken line or a line with a wrong field
339
+ */
340
+ export declare function stormLine(line: string): StormRow | undefined;
341
+ /**
342
+ * This function reads the zone-county file of the National Weather Service. The file has one line for each pair of a zone and a county, with `|` between the fields.
343
+ *
344
+ * @returns The FIPS codes of the counties of each zone, by the code of the state (2 digits) and of the zone (3 digits)
345
+ */
346
+ export declare function zoneCounties(text: string): Map<string, readonly string[]>;
347
+ /** The default seconds before the start of a storm event in which an outage can start: 1 hour. */
348
+ export declare const CAUSE_BEFORE = 3600;
349
+ /** The default seconds after the end of a storm event in which an outage can start: 3 hours. */
350
+ export declare const CAUSE_AFTER = 10800;
351
+ /** The options of `stormCauses`. */
352
+ export interface CauseOptions {
353
+ /** The seconds before the start of a storm event in which an outage can start. The default is `CAUSE_BEFORE`. */
354
+ readonly before?: number | undefined;
355
+ /** The seconds after the end of a storm event in which an outage can start. The default is `CAUSE_AFTER`. */
356
+ readonly after?: number | undefined;
357
+ }
358
+ /** The counts of the rows that `stormCauses` got. */
359
+ export interface CauseTally {
360
+ readonly rows: number;
361
+ /** The rows of a type of a case with one county or more. */
362
+ readonly placed: number;
363
+ /** The rows of a type of a case in a marine zone, or in a zone that the zone-county file does not have. */
364
+ readonly unplaced: number;
365
+ /** The count of the rows of each type that no case has. */
366
+ readonly other: Readonly<Record<string, number>>;
367
+ }
368
+ /** The index of the storm events by county. */
369
+ export interface StormCauses {
370
+ /** This function adds one row of Storm Events. */
371
+ add(row: StormRow): void;
372
+ /** This function gives the cases of the storm events that cover the county of an outage at its start, in the order of the table. */
373
+ causes(event: Pick<OutageEvent, "area" | "start">): readonly string[];
374
+ tally(): CauseTally;
375
+ }
376
+ /**
377
+ * This function makes the index of the storm events of the cases by county. A row of a zone covers each county of the zone.
378
+ * An outage is in a case when it starts from `before` seconds before a storm event of the case to `after` seconds after its end.
379
+ *
380
+ * @param classes - The event types of each case, for example `STORM_CLASSES`
381
+ * @param zones - The counties of each zone, from `zoneCounties`
382
+ * @throws {RangeError} When a margin is not a finite number of 0 or more, or when a type is in two cases
383
+ */
384
+ export declare function stormCauses(classes: Readonly<Record<string, readonly string[]>>, zones: ReadonlyMap<string, readonly string[]>, options?: CauseOptions): StormCauses;
385
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/hazard.ts","../src/data.ts","../src/check.ts","../src/case.ts","../src/outages.ts","../src/eaglei.ts","../src/law.ts","../src/storms.ts"],"mappings":";;;YAKY;;;;;;qBAOC,uBAAuB;;iBAgBnB;;WAEN;;WAEA;;;iBAIM;;WAEN;WACA;;;iBAIM;;WAEN;WACA;;WAEA;WACA,SAAS;;WAET,UAAU;;WAEV,MAAM;;WAEN,UAAU;;;;;;;YAQT;WAAmB;WAAyB;WAA6B;;WAA4B;WAA2B;WAAyB;;;iBAGpJ;;WAEN;;WAEA;;WAEA;;;;;;iBAOM;WACN;;WAEA;WACA,KAAK;;WAEL;;WAEA,QAAQ,SAAS,eAAe;;;iBAI1B;WACN;;WAEA;;;iBAIM;;WAEN;;WAEA;;WAEA,iBAAiB;WACjB,UAAU,cAAc;;;;;;iBAOlB;;WAEN;;WAEA;WACA,eAAe;;WAEf;;;qBAIE;;iBAGI;WACN,eAAe;;WAEf,SAAS,SAAS,eAAe;WACjC,kBAAkB;;;qBCnHhB,gBAAgB,SAAS,eAAe;;qBA0BxC,QAAQ;;qBAGR,cAAc;;;;;qBAed,aAAa;;;;;;;;;;;;;;;;qBCvCb;;YAaD,qBAAqB;;iBAGhB,oBAAoB;WAC1B,MAAM;;;;;;wBAOD,aAAa,MAAM,YAAY,iBAAgB,SAAwB;;wBAqEvE,eAAe,iBAAiB;;iBC3G/B;;WAEN;aAAoB;aAAyB;;;;;;WAK7C,QAAQ,SAAS;;;YAIhB;WAAyB;WAAuB,KAAK;;WAAyB;;;wBAG1E,SAAS,MAAM,YAAY,eAAe;;wBAK1C,YAAY,QAAQ,QAAQ,eAAe;;;;;;wBAU3C,WAAW,MAAM,YAAY,QAAQ,QAAQ,UAAS,oBAAyB;;iBC9B9E;;WAEN;;;;;WAKA;;WAEA;;;iBAIM;WACN;;WAEA;;WAEA;;WAEA;;WAEA;;;iBAIM;;WAEN,WAAW;;WAEX;;WAEA;;WAEA;;;iBAIM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;iBAIM;WACN,iBAAiB;WACjB,OAAO;;;iBAID;;EAEf,IAAI,OAAO;;EAEX,UAAU;;;;;;;;;;;;;;wBA8CI,aAAa,SAAS,gBAAgB;;qBCxGzC;;qBAGA;;;;;;;;wBAWG,UAAU,eAAe;;wBAgBzB,eAAe,eAAe;;wBAU9B,YAAY;;;;;qBCzCf;;iBAMI;;WAEN;;WAEA;;;;;;;wBAQK,WAAW,OAAO,eAAe,UAAS,kBAAuB;;iBA4BhE;;WAEN,OAAO;;WAEP;;WAEA;;WAEA;;WAEA;;;;;;;;;;wBAWK,aAAa,iBAAiB,eAAe,SAAS,yBAAyB,UAAS,kBAAuB,SAAS,eAAe;;;;;qBCpE1I,eAAe,SAAS;;YASzB;;iBAGK;;WAEN;WACA,MAAM;;WAEN;;WAEA;;WAEA;;;;;;;;wBA0DK,UAAU,eAAe;;;;;;wBAiBzB,aAAa,eAAe;;qBAc/B;;qBAEA;;iBAGI;;WAEN;;WAEA;;;iBAIM;WACN;;WAEA;;WAEA;;WAEA,OAAO,SAAS;;;iBAIV;;EAEf,IAAI,KAAK;;EAET,OAAO,OAAO,KAAK;EACnB,SAAS;;;;;;;;;;wBAuBK,YAAY,SAAS,SAAS,oCAAoC,OAAO,wCAAwC,UAAS,eAAoB"}