UNNS SAC → ΔA LADDER PIPELINE

======================================

PURPOSE
-------
Convert SAC seismic waveforms into ΔA structural ladders suitable for:

- STRUC_PERC analysis
- admissibility trajectory analysis
- explosion vs earthquake comparison
- UNNS structural regime extraction

------------------------------------------------------------
STEP 1 — ORGANIZE FILES
------------------------------------------------------------

Create working structure:

nk_explosion_project/
│
├── sac_raw/
│   ├── IC.BJT.00.BHZ.M.2013...
│   ├── IC.MDJ.00.BHZ.M.2013...
│   ├── IU.MAJO.00.BHZ.M.2013...
│   └── ...
│
├── csv_waveforms/
│
├── ladders/
│
└── results/

Copy ONLY .SAC files into:

sac_raw/

------------------------------------------------------------
STEP 2 — CONVERT SAC → CSV
------------------------------------------------------------

Run your SAC converter:

python sac_to_csv.py

OR

python sac_to_csv.py "sac_raw/IC.MDJ.00.BHZ.M.2013..."

Expected output:

csv_waveforms/
└── IC.MDJ.00.BHZ.M.2013.csv

CSV should contain:

time, amplitude

OR

index, amplitude

------------------------------------------------------------
STEP 3 — GENERATE ΔA LADDERS
------------------------------------------------------------

Run:

python delta_ladder.py

OR

python delta_ladder.py "csv_waveforms/IC.MDJ.00.BHZ.M.2013.csv"

Expected output:

ladders/
└── IC.MDJ.00.BHZ.M.2013_ladder.csv

------------------------------------------------------------
WHAT delta_ladder.py DOES
------------------------------------------------------------

Transforms waveform amplitudes:

A₁, A₂, A₃, ...

into first-order structural differences:

ΔA₁ = A₂ − A₁
ΔA₂ = A₃ − A₂
ΔA₃ = A₄ − A₃
...

This converts raw seismic motion into:

STRUCTURAL TRANSITION SPACE

instead of raw amplitude space.

------------------------------------------------------------
WHY ΔA IS IMPORTANT
------------------------------------------------------------

Raw waveforms:
- contain instrument scaling
- contain baseline offsets
- contain propagation amplitude effects

ΔA ladders reveal:
- transition structure
- oscillatory admissibility
- fragmentation behavior
- resonance persistence
- margin instability

This is the correct UNNS representation layer.

------------------------------------------------------------
STEP 4 — RUN STRUC_PERC
------------------------------------------------------------

Input generated ladders into:

STRUC_PERC_I
or
STRUC_PERC_I_v2_4_0

Recommended first comparison groups:

GROUP A — Nuclear explosions
--------------------------------
2006
2009
2013

GROUP B — Natural earthquakes
--------------------------------
Nevada earthquake
California earthquakes
regional tectonic events

------------------------------------------------------------
EXPECTED OBSERVATIONS
------------------------------------------------------------

Explosion ladders are expected to show:

- higher trajectory coherence
- lower fragmentation entropy
- stronger oscillatory persistence
- narrower admissibility families
- more repeatable structural tails

Earthquakes are expected to show:

- broader fragmentation
- rupture asymmetry
- stronger admissibility divergence
- more chaotic transition structure

------------------------------------------------------------
BEST FIRST STATIONS
------------------------------------------------------------

Recommended first stations:

IC.MDJ
IC.BJT
IU.MAJO
IU.YSS
IC.HIA

These already show strong waveform coherence.

------------------------------------------------------------
IMPORTANT
------------------------------------------------------------

DO NOT:
- normalize aggressively
- smooth heavily
- resample unnecessarily

Preserve original structural transitions.

------------------------------------------------------------
TARGET OUTPUT
------------------------------------------------------------

Final desired chain:

SAC
→ CSV waveform
→ ΔA ladder
→ STRUC_PERC
→ admissibility trajectory
→ regime comparison
→ explosion vs earthquake structural classification


BATCH:

USAGE
CURRENT DIRECTORY MODE

If CSV files are beside the script:

python delta_ladder.py .
FOLDER MODE
python delta_ladder.py csv_waveforms
SINGLE FILE MODE
python delta_ladder.py waveform.csv
OUTPUT

For every CSV:

IC.MDJ.00.BHZ...csv
↓
IC.MDJ.00.BHZ..._delta.txt

This gives you a fully automated:

SAC
→ CSV
→ ΔA ladder
→ STRUC_PERC
→ admissibility analysis

pipeline for the nuclear-test waveform corpus.

============================================================
END
============================================================