EIDA Consistency Checker

A tool to evaluate the consistency between EIDA nodes' availability and dataselect web services.
Designed for use in quality control and monitoring tasks across the European Integrated Data Archive (EIDA).

📖 Full documentation: https://EIDA.github.io/eida-consistency/

🚀 Installation & Quick Start

You can use eida-consistency in two ways:

Option 1: Using uvx

uvx eida-consistency <command> [options]

Option 2: Global install

uv tool install eida-consistency

Now it’s available globally:

eida-consistency <command> [options]

Update it with:

uv tool upgrade eida-consistency

🔍 CLI Commands

Run Consistency Check

Check if availability spans align with dataselect results:

uvx eida-consistency consistency --node RESIF --epochs 10 --duration 600
# OR check 5% of available stations:
uvx eida-consistency consistency --node RESIF --epochs "5%"

Options:

• --node: Node code (e.g. RESIF, NOA, ETH)
• --epochs: Number of random test epochs (default: 10) OR percentage (e.g., "5%", 0.05)
• --duration: Epoch length in seconds (≥600)
• --psd / --no-psd: Also check PSD (eidaws/psd) coverage vs dataselect (default: on)
• --delete-old: Keep only the most recent report
• --stdout: Print JSON report to stdout
• --report-dir: Save reports to a custom folder (default: reports/); works before or after the subcommand
• --log-level: Control verbosity (DEBUG, INFO, WARNING, ERROR)

Compare Reports

Compare two report files (e.g. a before/after pair for the same node):

uvx eida-consistency compare reports/resif_run1.json reports/resif_run2.json

Explore Inconsistencies

Re-check only the inconsistencies of a report, drilling down day-by-day to find their exact boundaries. With no report argument it uses the newest report; --index (repeatable) targets specific findings.

uvx eida-consistency explore                 # newest report, all inconsistencies
uvx eida-consistency explore reports/noa_20260621_140111_113496.json --index 7

See Re-run & Re-verify for when to use this vs check vs a fresh run.

Manage Node List

Reload routing cache:

uvx eida-consistency reload-nodes

List currently cached nodes:

uvx eida-consistency list-nodes

📂 Reports

Reports are stored in ./reports/ by default, or in a custom folder using --report-dir.

• JSON reports: reports/<node>_<YYYYMMDD>_<HHMMSS>_<microseconds>.json
• Markdown reports: reports/<node>_<YYYYMMDD>_<HHMMSS>_<microseconds>.md
• Global summary: summary.md

📚 Library Usage

You can also use eida-consistency as a Python library to run checks programmatically or build custom tools.

Check a Single Candidate

from eida_consistency.core.checker import check_candidate

# Define a candidate (network, station, channel, starttime)
candidate = {
    "network": "GR",
    "station": "ATH",
    "channel": "BHZ",
    "starttime": "2023-01-01T00:00:00",
}

# Run the check
results, stats = check_candidate(
    base_url="http://node.eida.eu/fdsnws",
    candidate=candidate,
    epochs=5,
    duration=600
)

for res in results:
    url, available, start, end, loc, span = res
    print(f"Time: {start} -> Available: {available}")

Run a Full Consistency Check

from eida_consistency.runner import run_consistency_check

# Run check for a specific node and get the report path
report_path = run_consistency_check(
    node="NOA",
    epochs=10,
    duration=600
)
print(f"Report generated at: {report_path}")

For full API documentation, please visit our Documentation Site or run:

uv run mkdocs serve

🔁 Re-run & Re-verify

There are three distinct ways to "run it again", depending on what you want:

1. Re-verify the findings of an existing report — re-check only the inconsistencies that a report recorded, replaying each one's exact window. This is the right way to confirm a node-side fix:

   uvx eida-consistency explore reports/noa_20260621_140111_113496.json
   

   Add --index N (repeatable) to re-check specific inconsistencies only.

2. Re-check a single stream/window — for a one-off, targeted check:

   uvx eida-consistency check --node NOA --net HP --sta SERG --loc "" --cha HHZ \
       --start 2016-09-20 --end 2016-10-19
   

3. Run a fresh sampled check — draw a new random set of streams for a node:

   uvx eida-consistency consistency --node NOA --epochs 20 --duration 600
   

   ⚠️ Passing the same --seed does not reproduce an older run once the node's live inventory changes. To reproduce a specific finding, use option 1 or 2 above, which replay the exact window rather than re-sampling.

   ℹ️ A fresh run cannot be limited to only inconsistent streams — a stream isn't known to be inconsistent until it's tested. Instead, the report already lists them on their own under the "Detected Inconsistencies" table, and option 1 (explore) re-checks only those inconsistent streams.

🧪 Example Workflow

# 1. Run a check (reports land in reports/test_noa/)
uvx eida-consistency consistency --node NOA --epochs 20 --report-dir reports/test_noa

# 2. Re-check the inconsistencies it found (day-by-day boundaries)
uvx eida-consistency explore --report-dir reports/test_noa

# 3. Fix them at node level, then re-verify by replaying the exact windows
#    (verdict per row: PERSISTS / RESOLVED / SKIPPED; add --all for CONSISTENT/REGRESSED)
uvx eida-consistency rerun reports/test_noa/<report>.json

# 4. Compare before/after
uvx eida-consistency compare reports/test_noa/old.json reports/test_noa/new.json

📊 Global Consistency Summary

📖 Full details: summary.md