> ## Documentation Index
> Fetch the complete documentation index at: https://spec2vec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Seismic Event Clustering with Spec2Vec: ESEC Catalog

> Reproduce the ESEC catalog analysis: download seismic waveforms, compute Spec2Vec features, and cluster exotic vs. tectonic earthquake signatures.

The ESEC application demonstrates how Spec2Vec can distinguish exotic seismic events — landslides, debris flows, and other non-tectonic surface events — from standard tectonic earthquakes purely from their spectral fingerprints. Rather than relying on hand-crafted phase picks or analyst labels, Spec2Vec computes a rich set of information-theoretic and statistical metrics from each event's spectrogram and lets those feature vectors drive clustering, producing separation between event classes that reflects genuine physical differences in source mechanism and wave propagation.

> [!WARNING]
>
> Before running any scripts in this workflow, open each Python file and update the global path variables at the top to match your local directory structure. All scripts read input data and write output files using these variables, and they will fail silently or with misleading errors if the paths are incorrect.

## Datasets

Two catalogs drive this analysis:

* **ESEC (Exotic Seismic Event Catalog):** A curated database of non-tectonic events — including landslides, glacial calving events, and debris flows — sourced from [IRIS SPUD](https://ds.iris.edu/spud/). The master reference catalog is `Master_ESEC_Catalog_vel_all.csv`, included in the `esec_catalog_clustering/` directory.
* **Tectonic EQ Catalog:** A manually curated set of conventional tectonic earthquakes downloaded via [IRIS Wilber 3](https://ds.iris.edu/wilber3/find_event). The master reference catalog is `Master_tectonic_eq_catalog.csv`, also included in the directory.

## Directory Structure

The `esec_catalog_clustering/` directory is organized as follows:

| Folder / File | Contents |
| - | - |
| `esec_raw_data/` | Raw downloaded ESEC waveforms |
| `esec_processed_vel/` | Processed ESEC velocity traces |
| `eq_raw_data/` | Raw tectonic earthquake downloads |
| `eq_processed_vel/` | Processed tectonic EQ velocity traces |
| `computed_dataset_files/` | Pre-computed Spec2Vec feature CSVs |
| `spec2vec_analysis_notebooks/` | Analysis and figure-generation notebooks |

## Step-by-Step Workflow

#### (To process from scratch)

**1. Download and process ESEC data**

Run `step1_esec_catalog_dataprepandprocess.py`. This script reads `Master_ESEC_Catalog_vel_all.csv`, queries the IRIS web services, and downloads raw waveforms for each catalogued event. Remember to update the global path variables at the top of the file first.

**Output:** Raw ESEC waveform files saved into `esec_raw_data/`.

**2. Process tectonic EQ data**

Run `step2_tectonic_eq_dataprepandprocess.py`. Because the tectonic earthquake data is manually downloaded via IRIS Wilber 3, this script focuses on applying standard signal processing routines — detrending, filtering, and instrument response removal — to the existing waveform files.

**Output:** Processed velocity traces saved into `eq_processed_vel/`.

**3. Compute Spec2Vec features**

Run `step3_spec2vec_metrics_prep.py`. This script reads all processed waveforms from both catalogs, converts each trace to a spectrogram, and feeds the spectrograms through the `GISQAPipeline` to extract the full Spec2Vec feature suite.

**Output:** Feature CSV files written to `computed_dataset_files/`, one per event class or combined, ready for analysis.

**4. Analyze and reproduce paper results**

Open `spec2vec_analysis_notebooks/spec2vec_analysis_main.ipynb` in Jupyter and run it from top to bottom. The notebook loads the feature CSVs from `computed_dataset_files/`, performs dimensionality reduction, clustering, and statistical comparisons, and regenerates the figures presented in the Spec2Vec publication.

> [!TIP]
>
> **Skip to results immediately:** Pre-computed feature files are already available in [computed\_dataset\_files](https://github.com/URseismology/SPEC2VEC/tree/main/esec_catalog_clustering/computed_dataset_files). If you just want to reproduce the paper figures without downloading or processing any raw data, open `spec2vec_analysis_notebooks/spec2vec_analysis_main.ipynb` directly and run it — Steps 1–3 are entirely optional.

## Optional Visualizations

After completing the core workflow, three additional scripts let you generate deeper visual analyses:

* **Reference input figures** — Run `optional_input_figures_ref_prep.py` to generate reference plots of the raw input signals for both the ESEC and tectonic EQ catalogs. Outputs are saved to `esec_spec2vec_ip_figures/` and `eq_spec2vec_ip_figures/` (pre-generated figures are already included in those folders for immediate inspection).
* **Comprehensive metric plots** — Run `optional_comprehensive_metrics_plots.py` to produce detailed visualizations of every computed Spec2Vec feature, useful for exploratory analysis and feature selection. Outputs are saved to `comprehensive_metrics_plots/`.
* **Rolling analysis** — Run `optional_esec_spec2vec_rolling_metrics_prep.py` to apply Spec2Vec on a rolling basis over N-second chunks of each time series rather than the full waveform. This sliding-window approach lets you track how spectral fingerprints evolve through an event and is particularly useful for long-duration exotic events such as sustained debris flows.

> [!TIP]
>
> **Skip to results immediately:** The github contains the figures from the processed results in the "[eq\_spec2vec\_ip\_figures](https://github.com/URseismology/SPEC2VEC/tree/main/esec_catalog_clustering/eq_spec2vec_ip_figures)", "[esec\_spec2vec\_ip\_figures](https://github.com/URseismology/SPEC2VEC/tree/main/esec_catalog_clustering/esec_spec2vec_ip_figures)" and "[comprehensive\_metrics\_plots](https://github.com/URseismology/SPEC2VEC/tree/main/esec_catalog_clustering/comprehensive_metrics_plots)" folders for your reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.