gea-program 0.9.0__tar.gz → 0.10.0__tar.gz

{gea_program-0.9.0 → gea_program-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.9.0
+Version: 0.10.0
 Summary: GEA-Program: downhole gauge monitoring - canonical measurement records, quality rules, drift evaluation with a re-fit change log, well-test validation, alarm management, model cards, store-and-forward, monthly SLA measurement, FAT/SAT protocols and a dashboard, generated from live objects in the client's reporting outline.
 Author: Daniel T. Murphy
 License: MPL-2.0
@@ -125,7 +125,7 @@ gea dashboard --catalog-well volve_f12_f14_production_excerpt:15/9-F-12:10000 --
 gea client-report --report accuracy --out client_report
 gea model-cards --out model_cards
 gea sbom --out sbom
-gea accept                     # the product gate (308 checks)
+gea accept                     # the product gate (314 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")

{gea_program-0.9.0 → gea_program-0.10.0}/README.md

@@ -86,7 +86,7 @@ gea dashboard --catalog-well volve_f12_f14_production_excerpt:15/9-F-12:10000 --
 gea client-report --report accuracy --out client_report
 gea model-cards --out model_cards
 gea sbom --out sbom
-gea accept                     # the product gate (308 checks)
+gea accept                     # the product gate (314 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")

{gea_program-0.9.0 → gea_program-0.10.0}/gea/__init__.py

@@ -122,7 +122,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.9.0"
+__version__ = "0.10.0"
 __all__ = [
     "aging_rate", "rate_psi_yr", "accuracy_psi",
     "Sensor", "SimulatorConfig", "DownholeEngine",

{gea_program-0.9.0 → gea_program-0.10.0}/gea/__main__.py

@@ -282,7 +282,7 @@ def main(argv=None) -> int:
                       choices=["init", "add-file", "add-catalog", "add-live", "remove", "list", "migrate", "refresh", "audit",
                                "add-seismic", "refresh-seismic", "remove-seismic", "sar-film", "refresh-all", "add-track", "refresh-track", "remove-track",
                                "seismic-dataset", "seismic-field", "add-site", "sites", "site-report", "remove-site", "rename",
-                               "set-well", "sra-define", "sra-report"])
+                               "set-well", "sra-define", "sra-report", "associate"])
     p_ws.add_argument("--stations", type=str, nargs="+", default=None, help="add-track: two or more array station ids of this workspace")
     p_ws.add_argument("--site", type=str, default=None, help="site-report/remove-site: the site id")
     p_ws.add_argument("--api", type=str, default=None, help="set-well: the API number")
@@ -308,6 +308,9 @@ def main(argv=None) -> int:
     p_ws.add_argument("--aftershocks", type=str, nargs="*", default=None, help="sra-report: catalogue ids the operator declares as aftershocks (exempt)")
     p_ws.add_argument("--start", type=str, default=None, help="sra-report: first day of the record, YYYY-MM-DD")
     p_ws.add_argument("--end", type=str, default=None, help="sra-report: last day of the record, YYYY-MM-DD")
+    p_ws.add_argument("--vp", type=float, default=5.8, help="associate: the P velocity of the model, km/s (declared)")
+    p_ws.add_argument("--depth-km", type=float, default=6.0, help="associate: the hypocentral depth the location is made under, km (declared)")
+    p_ws.add_argument("--rms-tol", type=float, default=0.15, help="associate: the RMS residual an event must fit within, s")
     p_ws.add_argument("--wells", type=str, nargs="+", default=None, help="add-site: well ids of this workspace")
     p_ws.add_argument("--seismic", type=str, nargs="+", default=None, help="add-site: seismic station ids of this workspace")
     p_ws.add_argument("--tracks", type=str, nargs="+", default=None, help="add-site: track ids of this workspace")
@@ -422,7 +425,8 @@ def main(argv=None) -> int:
     p_se.add_argument("--action", choices=["info", "spectrum", "lines", "fetch", "stations", "detect", "selftest", "convert", "response", "remove-response",
                                            "beam", "array-detect", "locate", "array-selftest", "sar-film", "bearings", "track", "track-selftest",
                                            "signatures", "multi-beam", "multi-bearings", "multi-track", "signature-selftest", "field-selftest",
-                                           "harmonics", "harmonic-selftest", "datum", "geodesy-selftest", "array-qc", "qc-selftest", "unlisted", "unlisted-selftest", "bearing-sigma", "coverage", "uncertainty-selftest"], default="info")
+                                           "harmonics", "harmonic-selftest", "datum", "geodesy-selftest", "array-qc", "qc-selftest", "unlisted", "unlisted-selftest", "bearing-sigma", "coverage", "uncertainty-selftest",
+                                           "assoc-selftest"], default="info")
     p_se.add_argument("--signatures", type=str, default=None, help="multi-beam/multi-bearings: the signatures JSON from --action signatures")
     p_se.add_argument("--histories", type=str, nargs="+", default=None, help="track: two or more bearing-history JSONs (from --action bearings), one per array")
     p_se.add_argument("--truth", type=str, default=None, help="track: ground truth CSV (point_id, lat, lon, utc[, note]) - the lateral's points in time")
@@ -878,6 +882,18 @@ def main(argv=None) -> int:
                           + (f"; verdict {v['verdict']} ({v['hit']} of {v['of']} inside their ellipse)" if v else "")
                           + (f" - {row.get('detail', '')}" if row.get("detail") else ""))
             return 0 if r["ok"] else 1
+        if a.action == "assoc-selftest":
+            from . import seismic_assoc as _SA
+            r = _SA.selftest()
+            print(f"association selftest [{r['label']}]: {r['status']} - {r['n_picks']} picks, {len(r['events'])} events, errors {r['errors_km']} km")
+            for k, v in r["checks"].items():
+                print(f"  {'ok ' if v else 'BAD'} {k}")
+            for e in r["events"]:
+                print(f"  {e['id']}: {e['origin_utc']}  {e['lat']:.4f}, {e['lon']:.4f}  {e['n_stations']} stations  RMS {e['rms_s']} s  "
+                      f"misfit region {e['region_km']['extent_east_km']} x {e['region_km']['extent_north_km']} km  magnitude: not estimated")
+            for x in r["catalogue"]["rows"]:
+                print(f"  vs catalogue: {x['event']} {x['standing']}")
+            return 0 if r["status"] == "OK" else 1
         if a.action == "uncertainty-selftest":
             from . import seismic_uncertainty as UQ
             r = UQ.selftest()
@@ -1697,6 +1713,16 @@ def main(argv=None) -> int:
                 r = ws.write_sra_packet(a.site, catalog_csv=a.catalog, aftershocks=a.aftershocks, start=a.start, end=a.end, actor=a.actor)
                 print(_sra_text(r["packet"]))
                 print("  report:", r["paths"]["html"]); print("  daily export:", r["paths"]["daily_csv"], f"({r['export_rows']} rows)"); return 0
+            elif a.action == "associate":
+                from .seismic_assoc import report_text as _assoc_text
+                if not a.site:
+                    raise SystemExit("associate needs --site <id>")
+                r = ws.associate_site(a.site, vp_km_s=a.vp, depth_km=a.depth_km, band=a.band, start=a.start, end=a.end, catalog_csv=a.catalog,
+                                      rms_tol_s=a.rms_tol, actor=a.actor)
+                for sid, x in r["stations"].items():
+                    print(f"  {sid}: {x['status']}, {x['picks']} pick(s)")
+                print(_assoc_text(r["association"], r["catalogue"]))
+                print("  written:", os.path.join(ws.path, "reports", "sites", a.site, "association.json")); return 0
             elif a.action == "seismic-dataset":
                 r = ws.write_seismic_dataset_report(actor=a.actor)
                 inv = r["inventory"]

{gea_program-0.9.0 → gea_program-0.10.0}/gea/acceptance_tests.py

@@ -4722,6 +4722,115 @@ def section_bc_sra(tmp: str) -> None:
        "labels it SIMULATION_SELF_TEST; the help page exists")
 
 
+def section_bd_association(tmp: str) -> None:
+    """Section BD - association: several stations heard the same thing, or they did not. The onset picker,
+    the associator with its grid search and its refusals, the location with its misfit region, the array as
+    one station, the catalogue comparison, and the workspace run that feeds the SRA packet."""
+    import csv as _csv
+    import subprocess as _sp
+    import numpy as _np
+    from . import seismic as S
+    from . import seismic_assoc as SA
+    from .workspace import Workspace, WorkspaceError
+    d = Path(tmp, "bd"); d.mkdir()
+
+    # -- the self-test -----------------------------------------------------------------------
+    r = SA.selftest()
+    ok(r["status"] == "OK" and all(r["checks"].values()) and r["label"] == "SIMULATION_SELF_TEST"
+       and r["errors_km"]["ev-A"] < 1.0 and r["errors_km"]["ev-B"] < 1.0,
+       "BD1 the self-test on a labelled scene: picks at every station, two events located to within a kilometre and a third of a second with all "
+       "five stations and RMS under 0.05 s, a two-station event refused rather than located, a spurious burst left unused, finite misfit "
+       "regions, no magnitude, and against the catalogue one AGREES, one DIFFERS by its separation and one catalogue event the stations did "
+       "not associate")
+
+    # -- the picker: the onset is the first energy, not half a window early ------------------
+    sc = SA.synthetic_scene()
+    fr = sc["frame"]
+    from .seismic_array import local_xy
+    devs = []
+    for sid, s in sc["stations"].items():
+        ex, ey = local_xy(sc["truth"][0]["lat"], sc["truth"][0]["lon"], fr["lat0"], fr["lon0"])
+        tt = SA.travel_time(ex, ey, s, sc["vp"], sc["depth_km"])
+        pk = [p for p in SA.picks(sc["traces"][sid], band=(2.0, 20.0)) if abs(p.time - (sc["truth"][0]["t0"] + tt)) < 2.0]
+        devs.append(pk[0].time - sc["truth"][0]["t0"] - tt if pk else 9.0)
+    quiet = S.Trace("XX", "Q", "", "HHZ", 0.0, 100.0, _np.random.default_rng(1).normal(0, 1, 60000).astype(_np.float32), "synthetic", "FLOAT32")
+    ok(all(abs(x) < 0.08 for x in devs) and not SA.picks(quiet, band=(2.0, 20.0)) and all(p.snr > 10 for p in SA.picks(sc["traces"]["STA5"], band=(2.0, 20.0))),
+       "BD2 the picker puts every onset within 80 ms of the true arrival (the first refinement walked back into the noise and every pick came "
+       "out 150 ms early, which the location absorbed into the origin time and nobody would have seen), picks nothing on a minute of plain "
+       "noise, and carries a signal-to-noise ratio on every pick")
+
+    # -- the locator: refuses two stations, refines about the coarse best, names the model ----
+    two = SA.locate({"STA1": 10.0, "STA2": 10.5}, sc["stations"], sc["vp"], sc["depth_km"])
+    ex, ey = local_xy(sc["truth"][1]["lat"], sc["truth"][1]["lon"], fr["lat0"], fr["lon0"])
+    pset = {sid: sc["truth"][1]["t0"] + SA.travel_time(ex, ey, s, sc["vp"], sc["depth_km"]) for sid, s in sc["stations"].items()}
+    exact = SA.locate(pset, sc["stations"], sc["vp"], sc["depth_km"])
+    off = SA.locate({**pset, "STA2": pset["STA2"] + 0.6}, sc["stations"], sc["vp"], sc["depth_km"])
+    ok(two["status"] == "NOT ASSOCIATED" and "three" in two["detail"]
+       and exact["status"] == "LOCATED" and abs(exact["best"]["x_km"] - ex) < 0.1 and abs(exact["best"]["y_km"] - ey) < 0.1 and exact["best"]["rms_s"] < 0.01
+       and abs(exact["best"]["t0"] - sc["truth"][1]["t0"]) < 0.02 and not exact["region_km"]["reaches_grid_edge"]
+       and "flat earth" in exact["model"]["basis"] and exact["model"]["depth_km"] == sc["depth_km"]
+       and off["best"]["rms_s"] > 0.15 and abs(off["residuals_s"]["STA2"]) == max(abs(v) for v in off["residuals_s"].values()),
+       "BD3 the locator refuses two stations, finds exact picks to within 100 m of the true epicentre and 20 ms of the origin time (the first "
+       "version refined about the stations' centroid instead of the coarse best node and lost every event more than a kilometre from the "
+       "centre), names the straight-ray flat-earth model and the declared depth on the result, and a pick 0.6 s off shows as the largest residual")
+
+    # -- the associator: the outlier is dropped, the event stands on the rest ----------------
+    picks_all = []
+    for sid, tr in sc["traces"].items():
+        picks_all += SA.picks(tr, band=(2.0, 20.0))
+    bad = [SA.Pick("STA4", sc["truth"][0]["t0"] + 3.2, 50.0, 1.0)]       # a wrong pick at STA4 near event A
+    picks_mix = [p for p in picks_all if not (p.station == "STA4" and abs(p.time - sc["truth"][0]["t0"]) < 3.0)] + bad
+    res = SA.associate(picks_mix, sc["stations"], sc["vp"], sc["depth_km"], frame_info=fr)
+    evA = sorted(res["events"], key=lambda e: e["origin_utc"])[0]
+    ok(res["n_events"] == 2 and evA["n_stations"] == 4 and evA["dropped"] == ["STA4"] and evA["rms_s"] < 0.05
+       and evA["magnitude"] is None and "not estimated" in evA["magnitude_basis"],
+       "BD4 a wrong pick at one station is dropped as the largest residual and the event stands on the other four; an event carries no "
+       "magnitude and says why")
+
+    # -- an array is one station ----------------------------------------------------------------
+    raw = [SA.Pick("ARR", 100.0 + k * 0.03, 20.0 + k, 1.0, channel=f"S{k}") for k in range(6)] + [SA.Pick("ARR", 130.0, 9.0, 0.5, channel="S3")]
+    col = SA.collapse_array_picks(raw, "ARR")
+    ok(len(col) == 1 and abs(col[0].time - 100.075) < 0.02 and "6 sensor" in col[0].channel,
+       "BD5 an array's sensors' picks within half a second become one pick at the median time at the array's position, and a burst one sensor "
+       "alone saw is not an arrival at the array")
+
+    # -- through the workspace and the command line, into the packet ---------------------------
+    for sid, tr in sc["traces"].items():
+        S.write_mseed([tr], str(d / f"{sid}.mseed"))
+    cat = d / "cat.csv"
+    with open(cat, "w", newline="") as f:
+        w = _csv.writer(f); w.writerow(["EventID", "Origin Time", "Local Magnitude", "Latitude", "Longitude", "Depth"])
+        for c in sc["catalog"]:
+            w.writerow([c["event_id"], c["time"], c["magnitude"], c["lat"], c["lon"], 6.0])
+    ws = Workspace.create(str(d / "ws"), "Pad 3", actor="tester")
+    ids = [ws.add_seismic_station(sid, [str(d / f"{sid}.mseed")], st.lat, st.lon, "tester", datum=st.datum, band=[2.0, 20.0])["id"]
+           for sid, st in sc["stations"].items()]
+    ws.add_site("Assoc block", seismic=ids[:2], client="Acme", actor="tester")
+    try:
+        ws.associate_site("Assoc-block"); few = False
+    except WorkspaceError as e:
+        few = "three" in str(e)
+    ws.add_site("Assoc block 5", seismic=ids, client="Acme", actor="tester")
+    run = lambda *a: _sp.run([sys.executable, "-m", "gea", "workspace", "--path", ws.path, "--actor", "tester", *a], capture_output=True, text=True)
+    r1 = run("--action", "associate", "--site", "Assoc-block-5", "--catalog", str(cat))
+    r2 = run("--action", "sra-define", "--site", "Assoc-block-5", "--name", "Test SRA", "--lat", "31.95", "--lon", "-102.25", "--radius-km", "9.08", "--plan-date", "2026-02-25")
+    r3 = run("--action", "sra-report", "--site", "Assoc-block-5", "--catalog", str(cat))
+    aj = json.loads(Path(ws.path, "reports", "sites", "Assoc-block-5", "association.json").read_text(encoding="utf-8"))
+    md = Path(ws.path, "reports", "sites", "Assoc-block-5", "sra_packet.md").read_text(encoding="utf-8")
+    pk = json.loads(Path(ws.path, "reports", "sites", "Assoc-block-5", "sra_packet.json").read_text(encoding="utf-8"))["packet"]
+    audit = Path(ws.path, "records", "audit.jsonl").read_text(encoding="utf-8")
+    r4 = _sp.run([sys.executable, "-m", "gea", "seismic", "--action", "assoc-selftest"], capture_output=True, text=True)
+    ok(few and r1.returncode == 0 and "2 event(s)" in r1.stdout and "AGREES" in r1.stdout and "DIFFERS" in r1.stdout and "NOT ASSOCIATED BY THE STATIONS" in r1.stdout
+       and aj["association"]["n_events"] == 2 and all(v["status"] == "PICKED" for v in aj["stations"].values())
+       and r2.returncode == 0 and r3.returncode == 0 and pk["association"]["n_inside"] == 2
+       and "Events located by the site's own stations" in md and "AGREES" in md and "no magnitude is estimated here" in md
+       and "site.associate" in audit and r4.returncode == 0 and "SIMULATION_SELF_TEST" in r4.stdout,
+       "BD6 `--action associate` refuses a site with fewer than three stations, picks five miniSEED stations, associates and locates two events, "
+       "sets them against the catalogue, writes association.json and audits it; the SRA packet then carries the events the site's own stations "
+       "located beside the catalogue's, inside or outside the area, with the model named and no magnitude; `gea seismic --action assoc-selftest` "
+       "runs the labelled scene from the command line")
+
+
 def main() -> int:
     print("GEA-Program - ACCEPTANCE SUITE (the product gate)")
     # a handle a job subprocess still holds at the end must not turn a finished gate into a traceback on Windows:
@@ -4780,6 +4889,7 @@ def main() -> int:
         section_ba_sites(tmp)
         section_bb_supervisor(tmp)
         section_bc_sra(tmp)
+        section_bd_association(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

{gea_program-0.9.0 → gea_program-0.10.0}/gea/client_reports.py

@@ -1644,6 +1644,30 @@ def sra_packet_report(pk: dict, evaluated_at: Optional[datetime] = None, program
     else:
         secs.append(Section(str(n), 'Seismicity against the plan', ['No catalogue export was handed in. This section is empty and the goal clock is not stated.']))
         n += 1
+    ao = pk.get('association')
+    if ao:
+        mo = ao.get('model') or {}
+        paras = [f"The site's own stations: {ao['n_picks']} arrival(s) picked at {ao['n_stations']} station(s), associated into {ao['n_events']} event(s) "
+                 f"under a straight-ray model at {mo.get('vp_km_s', '-')} km/s with the hypocentre at a declared {mo.get('depth_km', '-')} km; {ao['n_inside']} inside the area. "
+                 f"An event needs {mo.get('min_stations', 3)} or more stations within {mo.get('rms_tol_s', '-')} s; a depth is declared, not located; no magnitude is estimated here."]
+        rows = [[e['id'], e['origin_utc'][:19].replace('T', ' '), f"{e['lat']:.4f}, {e['lon']:.4f}", e['n_stations'], _fmt(e['rms_s']),
+                 f"{e['region_km']['extent_east_km']} x {e['region_km']['extent_north_km']}", _fmt(e['distance_km']), 'inside' if e['inside'] else 'outside']
+                for e in ao['events']]
+        tabs = [Table(['Event', 'Origin (UTC)', 'Epicentre (WGS84)', 'Stations', 'RMS (s)', 'Misfit region E x N (km)', 'From centre (km)', 'Area'], rows,
+                      'Events the stations located')]
+        cq = ao.get('catalogue')
+        if cq:
+            paras.append(f"Against the catalogue: {cq['n_agree']} agree, {cq['n_differ']} differ, {cq['n_not_in_catalogue']} not in the catalogue; "
+                         f"{len(cq['missed'])} catalogue event(s) the stations did not associate. Where they differ, both positions are printed and neither is chosen.")
+            tabs.append(Table(['Event', 'Catalogue event', 'Catalogue M', 'dt (s)', 'Separation (km)', 'Allowed (km)', 'Standing'],
+                              [[r['event'], r.get('catalog_event') or '-', _fmt(r.get('catalog_magnitude')), _fmt(r.get('dt_s')), _fmt(r.get('separation_km')),
+                                _fmt(r.get('allowed_km')), r['standing']] for r in cq['rows']]
+                              + [['-', m['catalog_event'], _fmt(m['magnitude']), '-', '-', '-', m['standing']] for m in cq['missed']], 'Against the catalogue'))
+        if ao['refused']:
+            paras.append(f"{len(ao['refused'])} candidate arrival(s) not associated: " + '; '.join(f"{r['first_pick'][:19]} at {r['station']} - {r['why']}" for r in ao['refused'][:5])
+                         + ('; ...' if len(ao['refused']) > 5 else '') + '.')
+        secs.append(Section(str(n), 'Events located by the site\'s own stations', paras, tabs))
+        n += 1
     secs.append(Section(str(n), 'The schedule', ['Checkpoints with Commission staff from the plan date, and the goal date.'],
                         [Table(['#', 'Date', 'What'], [[c['n'], c['date'], c['what']] for c in pk['checkpoints']])]))
     n += 1

{gea_program-0.9.0 → gea_program-0.10.0}/gea/help/seismic.md

@@ -2,7 +2,7 @@
 
 > Raw seismic records in (miniSEED, SAC, or fetched from an FDSN archive), spectra and persistent lines out, one measured number before anything else is promised - the distance at which a known rig shows in this station's record - and, with an array, the direction it came from.
 
-**The command**: `gea seismic --action info --file day.mseed` reads a file (the format is decided by its content); `--action spectrum` and `--action lines --win 600` give the Welch PSD and the lines that persist above the local floor in the band (`--band 1 50` by default, where pumps, rotary and engines sit); `--action fetch --base texnet --network TX --station XXXX --channel HHZ --start ... --end ... --out tx.mseed` downloads from TexNet or EarthScope (`--base iris`); `--action detect --file tx.mseed --station-lat LAT --station-lon LON --sources rigs.csv` is the detectability test, with the rigs' positions and working windows in the CSV (`source_id, lat, lon, start_utc, end_utc[, kind, note]`). `--action selftest` runs the test on a synthetic scene and labels it `SIMULATION_SELF_TEST`. The station's response: `--action response --stationxml station.xml` lists what the file holds; `--action remove-response --file tx.mseed --stationxml station.xml --output VEL --pre-filt 0.5 1 40 45 --out tx_vel.mseed` turns counts into m/s (or `DISP` m, `ACC` m/s^2); `spectrum`, `lines` and `detect` take `--stationxml` and do it first; `fetch --with-response` fetches the StationXML beside the record. The array: `--action beam --files s1.mseed s2.mseed ... --sensors sensors.csv --band 1 20 --start ... --end ...` gives the back-azimuth and slowness the band's energy crossed the array with (`sensor_id, lat, lon` in the CSV, one record per sensor, three or more); `--action array-detect --files ... --sensors sensors.csv --sources rigs.csv` is the array's detectability test - did the array point at each listed rig in the windows it worked alone; `--action locate --bearings bearings.csv` crosses the bearings of two or more arrays (`lat, lon, back_azimuth_deg, sigma_deg`); `--action array-selftest` runs all of it on a labelled synthetic scene. The time dimension: `--action bearings --files ... --sensors sensors.csv --win 600 --name A1 --out a1.json` is the beam on every window of an array's record - a bearing with the array's tolerance where the beam was coherent, a gap where it was not, and the change points; `--action track --histories a1.json a2.json [--truth lateral.csv] --out track.json` crosses two or more arrays' histories window by window into positions with their ellipses, fits the longest continuous segment into a heading and a length, and judges it against the ground truth (`point_id, lat, lon, utc` - the lateral's surveyed points, or a permit's surface hole with its date); `--action track-selftest` runs the tracker on a labelled scene of a bit advancing along a lateral past two arrays. Several rigs at once: `--action signatures --file rec.mseed --sources rigs.csv --out sigs.json` learns each rig's own lines from the windows it worked alone; `--action multi-beam --files ... --sensors sensors.csv --signatures sigs.json` gives a bearing per rig in one window, each from that rig's own bins; `--action multi-bearings ... --out a1.json` does it window by window, and `--action multi-track --histories a1.json a2.json [--truth truth.csv]` crosses two or more arrays into a track per rig. `--action signature-selftest` and `--action field-selftest` run both on labelled scenes. Ground truth from a permit export: `gea permits --file export.csv --out rigs.csv [--within LAT LON KM] [--mapping map.json]` finds the columns by name and writes the rigs CSV with an import note beside it; `--action sar-film --hours 8 --step 600 --out film.json` writes the SAR panel's film - the same scene played forward in time, one frame per window, every frame stamped `SIMULATION_SELF_TEST`. On a site: `gea workspace --path C:\site --action add-seismic --name "Pad 3 node" --files tx.mseed --lat LAT --lon LON --sources rigs.csv [--stationxml station.xml] [--sensors sensors.csv --files s1.mseed s2.mseed ...]` registers a station or an array (the Seismic page does the same by upload; `--permits export.csv` in place of `--sources` converts a permit export on the way in), and `--action refresh-seismic` runs the whole leg on it; `--action add-track --name "Pad 7 lateral" --stations <array-1> <array-2> [--truth lateral.csv]` makes a track over two or more array stations and `--action refresh-track` runs the tracker on it - the Tracks card on the Seismic page is the same by upload, and the track view shows the map with every position's ellipse, a slider through time, and the bearings over time - the Seismic page's Refresh button is that command as a job. The page's SAR panel is the control panel and the screen: `--action sar-film` as a job makes the film, and the screen plays it - the trace, the spectrogram column arriving, the beam power map swinging onto the working rig, the bearing against the rig's true bearing with the array's tolerance wedge beside it, the tally per rig, and at the end the array detectability test's verdict on the whole scene, the same function a real record goes through.
+**The command**: `gea seismic --action info --file day.mseed` reads a file (the format is decided by its content); `--action spectrum` and `--action lines --win 600` give the Welch PSD and the lines that persist above the local floor in the band (`--band 1 50` by default, where pumps, rotary and engines sit); `--action fetch --base texnet --network TX --station XXXX --channel HHZ --start ... --end ... --out tx.mseed` downloads from TexNet or EarthScope (`--base iris`); `--action detect --file tx.mseed --station-lat LAT --station-lon LON --sources rigs.csv` is the detectability test, with the rigs' positions and working windows in the CSV (`source_id, lat, lon, start_utc, end_utc[, kind, note]`). `--action selftest` runs the test on a synthetic scene and labels it `SIMULATION_SELF_TEST`. The station's response: `--action response --stationxml station.xml` lists what the file holds; `--action remove-response --file tx.mseed --stationxml station.xml --output VEL --pre-filt 0.5 1 40 45 --out tx_vel.mseed` turns counts into m/s (or `DISP` m, `ACC` m/s^2); `spectrum`, `lines` and `detect` take `--stationxml` and do it first; `fetch --with-response` fetches the StationXML beside the record. The array: `--action beam --files s1.mseed s2.mseed ... --sensors sensors.csv --band 1 20 --start ... --end ...` gives the back-azimuth and slowness the band's energy crossed the array with (`sensor_id, lat, lon` in the CSV, one record per sensor, three or more); `--action array-detect --files ... --sensors sensors.csv --sources rigs.csv` is the array's detectability test - did the array point at each listed rig in the windows it worked alone; `--action locate --bearings bearings.csv` crosses the bearings of two or more arrays (`lat, lon, back_azimuth_deg, sigma_deg`); `--action array-selftest` runs all of it on a labelled synthetic scene. The time dimension: `--action bearings --files ... --sensors sensors.csv --win 600 --name A1 --out a1.json` is the beam on every window of an array's record - a bearing with the array's tolerance where the beam was coherent, a gap where it was not, and the change points; `--action track --histories a1.json a2.json [--truth lateral.csv] --out track.json` crosses two or more arrays' histories window by window into positions with their ellipses, fits the longest continuous segment into a heading and a length, and judges it against the ground truth (`point_id, lat, lon, utc` - the lateral's surveyed points, or a permit's surface hole with its date); `--action track-selftest` runs the tracker on a labelled scene of a bit advancing along a lateral past two arrays. Several rigs at once: `--action signatures --file rec.mseed --sources rigs.csv --out sigs.json` learns each rig's own lines from the windows it worked alone; `--action multi-beam --files ... --sensors sensors.csv --signatures sigs.json` gives a bearing per rig in one window, each from that rig's own bins; `--action multi-bearings ... --out a1.json` does it window by window, and `--action multi-track --histories a1.json a2.json [--truth truth.csv]` crosses two or more arrays into a track per rig. `--action signature-selftest` and `--action field-selftest` run both on labelled scenes. Ground truth from a permit export: `gea permits --file export.csv --out rigs.csv [--within LAT LON KM] [--mapping map.json]` finds the columns by name and writes the rigs CSV with an import note beside it; `--action sar-film --hours 8 --step 600 --out film.json` writes the SAR panel's film - the same scene played forward in time, one frame per window, every frame stamped `SIMULATION_SELF_TEST`. On a site: `gea workspace --path C:\site --action add-seismic --name "Pad 3 node" --files tx.mseed --lat LAT --lon LON --sources rigs.csv [--stationxml station.xml] [--sensors sensors.csv --files s1.mseed s2.mseed ...]` registers a station or an array (the Seismic page does the same by upload; `--permits export.csv` in place of `--sources` converts a permit export on the way in), and `--action refresh-seismic` runs the whole leg on it; `--action add-track --name "Pad 7 lateral" --stations <array-1> <array-2> [--truth lateral.csv]` makes a track over two or more array stations and `--action refresh-track` runs the tracker on it - the Tracks card on the Seismic page is the same by upload, and the track view shows the map with every position's ellipse, a slider through time, and the bearings over time - the Seismic page's Refresh button is that command as a job. Association: `gea workspace --path C:\site --action associate --site <id> [--vp 5.8 --depth-km 6 --catalog texnet.csv]` picks the onsets on every station of a site, associates them into events under a declared straight-ray model (three or more stations within the RMS tolerance, the worst pick dropped while more than three remain), locates each with its misfit region, and sets them against a catalogue export - AGREES, DIFFERS with both positions printed, or NOT ASSOCIATED BY THE STATIONS; `gea seismic --action assoc-selftest` runs it on a labelled scene. A depth is declared, not located; no magnitude is estimated. The page's SAR panel is the control panel and the screen: `--action sar-film` as a job makes the film, and the screen plays it - the trace, the spectrogram column arriving, the beam power map swinging onto the working rig, the bearing against the rig's true bearing with the array's tolerance wedge beside it, the tally per rig, and at the end the array detectability test's verdict on the whole scene, the same function a real record goes through.
 
 **What it writes**: `signatures --out` a JSON of every source's lines with the windows they were learned from and the reason any source has none; `multi-beam --out` a bearing per source with the bins it used, the lines another source also claims, and the whole-band bearing beside them; `multi-track --out` a position history and a track per source. `info` prints each trace with its start, end, rate, sample count, encoding and gaps - in counts, with the instrument response left as recorded; `spectrum --out` a CSV of frequency, PSD and dB; `lines --out` a JSON of the persistent lines (frequency, excess over the floor, the fraction of windows present); `fetch` the miniSEED plus a `.request.json` beside it with the URL and time (and `.stationxml` with `--with-response`); `remove-response` a FLOAT64 miniSEED in the chosen unit with a `.units.json` sidecar carrying the water level, the pre-filter and the check of the stages against the declared sensitivity; `beam --out` a JSON with the back-azimuth, the slowness and apparent velocity, the best-bin coherence and the coherent frequencies, the array response function's half-width, whether the geometry has aliasing lobes at this band, the other peaks, and the plane-wave limit; `array-detect` a verdict per rig (`POINTED`, `NOT_POINTED`, `INCOHERENT`, `AMBIGUOUS`, `INSUFFICIENT_WINDOWS`) with the beam's bearing against the true one and the tolerance it was judged by; `locate` the crossing point with its 1-sigma ellipse, the crossing angle, the residual of each bearing and whether the point is in front of every array; on a site, `refresh-seismic` writes the Seismic Station Report (html, md, json) and the spectrum, lines, detect, beam and array JSONs under `reports/seismic/<station>/`, which the Seismic page shows; `sar-film` writes `reports/seismic/SIMULATION/sar_film.json` (the frames) and its summary, never under a real station's folder; `refresh-track` writes the Seismic Track Report (html, md, json), every array's bearing history, `positions.json` and `verdict.json` under `reports/seismic/tracks/<track>/`; `permits` writes the rigs CSV and `<out>.import.json` - the columns used, the rows dropped and why, the end dates assumed; `detect --out` a JSON with a verdict per source (`DETECTED`, `NOT_DETECTED`, `AMBIGUOUS` when the rig never worked alone, `INSUFFICIENT_WINDOWS`), the quiet baseline, the lines that belong to each detected source and not to the quiet hours, and the radius bracketed between the farthest rig heard and the nearest not heard.
 

{gea_program-0.9.0 → gea_program-0.10.0}/gea/help/sra.md

@@ -4,7 +4,7 @@
 
 **The command**: declare each disposal well once - `gea workspace --path C:\site --action set-well --well <id> --lat LAT --lon LON --datum NAD27 --api 42-329-12345 --uic 123456 --depth-tier deep --formation "completed below the base of the Wolfcamp" --channel-pressure P_surf_psi --channel-rate Q_bpm --rate-unit bbl/min --bhp-method probe --channel-bhp P_bh_psi`; define the area on the site once - `--action sra-define --site <id> --name "Gardendale SRA" --lat 31.95 --lon -102.25 --datum WGS84 --radius-km 9.08 --plan-date 2022-12-16 --triggering-event texnet2022yxab`; then every month - `--action sra-report --site <id> --catalog texnet_export.csv [--aftershocks id1 id2] [--start 2026-03-01 --end 2026-03-31]`. `gea sra` runs the self-test on a labelled scene.
 
-**What it writes**: `reports/sites/<site>/sra_packet.html` (and `.md`, `.json`) - the area and the plan as declared, what is inside it with each well's depth tier, the daily record per well rolled up by month, the seismicity against the plan, the checkpoint schedule, and every gap by name; and `sra_daily_export.csv` - one line per well per day under the Notice's own parameter names (maximum surface injection pressure, average surface injection pressure, injection volume, maximum injection rate), the bottomhole pressure and its method, and the well's API and UIC numbers. Every declaration and every packet is in `records/audit.jsonl`.
+**What it writes**: `reports/sites/<site>/sra_packet.html` (and `.md`, `.json`) - the area and the plan as declared, what is inside it with each well's depth tier, the daily record per well rolled up by month, the seismicity against the plan, the events the site's own stations located (when `--action associate` has been run on the site: each inside or outside the area, against the catalogue, no magnitude), the checkpoint schedule, and every gap by name; and `sra_daily_export.csv` - one line per well per day under the Notice's own parameter names (maximum surface injection pressure, average surface injection pressure, injection volume, maximum injection rate), the bottomhole pressure and its method, and the well's API and UIC numbers. Every declaration and every packet is in `records/audit.jsonl`.
 
 **The number to check**: `Response:` in section "Seismicity against the plan" - TRIGGERED names the event, its magnitude and the deadline for the response group's meeting; NOT TRIGGERED names why. `Goal:` gives the days without a threshold event and the date the plan's goal falls on. The packet's front says COMPLETE or INCOMPLETE with the count of gaps.