# Software Requirements Specification (SRS)

**Project Name:** postprocessing_seismo_lib  
**Version:** 1.1  
**Python Version Compatibility:** Python 3.10.5 only  
**Last Updated:** April 9, 2026  

---

## 1. Introduction

### 1.1 Purpose

`postprocessing_seismo_lib` is a lightweight Python library designed to parse, validate, and build structured API messages for seismic event-based systems. It supports nested JSON formats and provides utilities for converting between multiple seismic pick data formats.

---

### 1.2 Intended Audience

- Developers integrating seismic pipelines  
- Researchers working with seismic data formats (GaMMa, QuakeML, ArcOut, ANSS, SOA, PhaseNet)  

---

### 1.3 Scope

The library provides utilities to:

- Extract body data from API-style JSON responses  
- Wrap pick data into structured API request formats  
- Convert CSV, QuakeML XML, and ArcOut into API response JSON  
- Convert between seismic pick formats (SOA, ANSS, PhaseNet)  

---

## 2. Overall Description

### 2.1 Product Perspective

This is a standalone utility library, intended to be imported and used as part of a broader earthquake data processing pipeline.

### 2.2 Software Constraints

- ❌ Not compatible with Python versions earlier than 3.10 (specifically fails on Python 3.6.5 and 3.8.10).  
- ✅ Tested and vetted on Python 3.10.5.

### 2.3 User Classes and Characteristics

| User Class          | Description                                                    |
|---------------------|----------------------------------------------------------------|
| Individual Users    | Analysts or researchers using the library for one-off analysis tasks |
| Pipeline Developers | Engineers automating seismic data processing pipelines using API input/output |


---

## 3. Functional Requirements

## 3.1 Extract Body from API Response

**Function:** `extract_body_from_file(file_path: str) -> dict`

**Description:**  
Extracts the body portion of a structured JSON response.

**Input Format:**

```json
{
  "status": 200,
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "id": "event_id",
    "format": "format_type",
    "data": []
  }
}
```

**Output:** Only the body dictionary.

---

## 3.2 Wrap Data for Input to Associator or PickFilter

**Function:** `wrap_data(...) -> None`

**Description:**  
Wraps input pick data (JSON) into a structured `RetrieveParameters` request format for the associator or pickfilter modules. Also validates both input and output.

### Required Parameters:

- `input_file_path`: Path to input JSON file  
- `output_file_path`: Path to output JSON file  
- `evid`: Event ID string  
- `module`: Either `'associator'` or `'pickfilter'`

### Optional Parameters (for pickfilter):

- `mode`: Default `'hypoPN'`, other allowed: `'st-proc'`  
- `testType`: Default `'local'`  
- `logging`: Default `False`

### Input Format (list of pick dicts):

```json
[
  {
    "Amplitude": {"Amplitude": 123.4, "SNR": 5.2},
    "Phase": "P",
    ...
  }
]
```

### Output Format:

```json
{
  "RetrieveParameters": {
    "pickFile": "filename.json",
    "pickDataStr": [ ... ]  // validated picks
  }
}
```

---

## 3.3 Convert Input Files to API Response Format

**Function:** `convert_file_to_json(...) -> None`

**Description:**  
Converts various file formats to structured API-style response JSON.

### Supported Input Types:

- **CSV:** Provide `event_file` and `pick_file`  
- **QuakeML XML:** Provide `input_file` path  
- **ArcOut:** Provide `input_file` path

### Common Parameters:

- `output_file`: JSON output file  
- `id`: Custom ID string  
- `error_log_file`: File to log validation or format errors

### Output Format:

```json
{
  "status": 200,
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "id": "event_id",
    "format": "format_type",
    "data": [ ... ]
  }
}
```

---

### 3.4 Format Conversion Utilities (NEW)

The library now supports conversion between seismic formats:

- SOA → SOA (ANSS-informed)
- SOA → ANSS
- ANSS → SOA
- PhaseNet CSV → SOA

Functions:

- `soa_to_soa_pick_format_using_anss_libraries`
- `soa_to_anss_pick_format`
- `anss_to_soa_pick_format`
- `phasenet_csv_to_soa_pick_format`

All return:
```
{ "picks": [...] }
```

---

## 4. Non-Functional Requirements

### 4.1 Performance

All parsing and wrapping functions must complete execution within **2 seconds** for files < 1MB.

### 4.2 Reliability

- Output must be schema-validated.  
- Errors are written to explicitly named `.log` files.

### 4.3 Usability

- Functions must be easily callable in scripts and pipelines.  
- Inputs/outputs should follow clearly documented format rules.

### 4.4 Portability

- ❌ Not portable to Python versions earlier than 3.10  
- ✅ Compatible with Python 3.10.5

---

## 5. Installation

### 5.1 From PyPI:

```bash
pip install postprocessing-seismo-lib
```

### 5.2 Upgrade:

```bash
pip install --upgrade postprocessing-seismo-lib
```
---

## 6. Example Usage

### Example 1: Extract Body from JSON Response

```python
from postprocessing_seismo_lib import extract_body_from_file

body = extract_body_from_file("response.json")
```

### Example 2: Create Associator Input Request

```python
from postprocessing_seismo_lib import wrap_data

wrap_data(
    input_file_path="filtered_picks.json",
    output_file_path="output_associator.json",
    evid="my_event_id",
    module="associator"
)
```

### Example 3: Convert GaMMa CSV to Response JSON

```python
from postprocessing_seismo_lib import convert_file_to_json

convert_file_to_json(
    input_file="",
    output_file="response.json",
    id="event_id",
    event_file="events.csv",
    pick_file="picks.csv",
    error_log_file="errors.txt"
)
```

### Example 4: Convert Formats

```python
from postprocessing_seismo_lib import (
    anss_to_soa_pick_format,
    soa_to_anss_pick_format,
    phasenet_csv_to_soa_pick_format,
    soa_to_soa_pick_format_using_anss_libraries
)

soa_picks_informed_by_anss = soa_to_soa_pick_format_using_anss_libraries("file path to SOA picks.json")

formatted_anss_picks = soa_to_anss_pick_format("file path to SOA picks.json", "file path to archived stations.csv")

pick_list = phasenet_csv_to_soa_pick_format("file path to picks.csv", "floating pt value for highpass filter")

soa_picks=anss_to_soa_pick_format("file path to ANSS picks.json")
```

---

## 7. Future Enhancements (Planned)

- Support for additional modules beyond associator and pickfilter.  
- Built-in CLI wrapper.  
- Expanded schema validation tools.  
- Performance profiling and async support.

---

## 8. Appendices

- Example data files are bundled within the `postprocessing_seismo_lib.example_data` package directory.  
- Schema validation logs are written to `wrap_data_errors.log`, `quakeml_error_log.txt`, etc.