Software Requirements Specification (SRS)

Project Name: postprocessing_seismo_lib
Version: 1.2
Python Version Compatibility: Python 3.10.5 only
Last Updated: July 19, 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:

{
  "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):

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

Output Format:

{
  "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:

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

---

3.4 Pick Format Conversion Utilities

The library supports conversion between seismic pick formats, targeting anss-formats==0.1.3 (see ANSS Pick format spec):

• 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(pick_file_path, station_csv_path=None)

• anss_to_soa_pick_format

• phasenet_csv_to_soa_pick_format

All return:

{ "success", "num_picks", "num_errors", "picks": [...], "errors" }

station_csv_path is optional on soa_to_anss_pick_format and the two functions below; when omitted, the archive_stations_loc_dates.csv bundled under postprocessing_seismo_lib/example_data/ is used.

---

3.5 SOA-Envelope → ANSS Pick / Detection Conversion Utilities (NEW, anss-formats==0.1.3)

Three additional entry points convert SOA-format JSON envelopes (as returned by the Phasenet lambda or pick-filter-spec’s PickProcess/v2 endpoint) directly into anss-formats==0.1.3 Pick/Detection objects:

• phasenet_soa_to_anss_pick_format(soa_source, station_csv_path=None) — Phasenet-lambda SOA picks → list of ANSS Pick dicts.

• pickfilter_soa_to_anss_pick_format(pickfilter_source, station_csv_path=None) — pick-filter SOA picks (carrying Onset and a multi-standard Quality list) → list of ANSS Pick dicts.

• pickfilter_soa_to_anss_detection_format(detection_source, station_csv_path=None) — pick-filter SOA detection → a single ANSS Detection dict.

All three accept either a file path to the response envelope ({"status", "headers", "body"}), a path to the bare body, or an already-loaded dict/list.

---

3.6 AQMS / pick-filter-spec Detection JSON Writer (NEW)

A separate module, postprocessing_seismo_lib.json_writers, builds an ANSS Detection JSON directly from AQMS database rows or from a pandas DataFrame of already-processed picks (the shape produced by pick-filter-spec’s pick_processing.py) — a different input contract from section 3.5’s SOA-JSON converters:

• dumps_detection_anss(*data, agencyID=None, author=None) -> dict

• dump_detection_anss(*data, fp, agencyID=None, author=None, **json_kwargs) -> dict

• map_arrival_quality_to_score(quality, channel) -> int — maps an ML confidence score to a 0-4 Hypoinverse pick-weight code.

The reverse direction, detection_anss_to_scsn(detection) -> dict (in postprocessing_seismo_lib.utils), converts an ANSS Detection dict back into the legacy SCSN detection JSON format.

---

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:

pip install postprocessing-seismo-lib

5.2 Upgrade:

pip install --upgrade postprocessing-seismo-lib

---

6. Example Usage

Example 1: Extract Body from JSON Response

from postprocessing_seismo_lib import extract_body_from_file

body = extract_body_from_file("response.json")

Example 2: Create Associator Input Request

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

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

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")

Example 5: SOA-Envelope → ANSS Pick / Detection (anss-formats==0.1.3)

from postprocessing_seismo_lib import (
    phasenet_soa_to_anss_pick_format,
    pickfilter_soa_to_anss_pick_format,
    pickfilter_soa_to_anss_detection_format,
)

phasenet_anss_picks = phasenet_soa_to_anss_pick_format("file path to Phasenet lambda SOA response.json")

pickfilter_anss_picks = pickfilter_soa_to_anss_pick_format("file path to pick-filter SOA picks response.json")

pickfilter_anss_detection = pickfilter_soa_to_anss_detection_format("file path to pick-filter SOA detection response.json")

Example 6: AQMS / pick-filter-spec Detection JSON Writer

from postprocessing_seismo_lib import dumps_detection_anss, detection_anss_to_scsn

anss_detection = dumps_detection_anss(picks_df, evt, agencyID="CI", author="hypoPN")

scsn_detection = detection_anss_to_scsn(anss_detection)

---

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.