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:

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

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

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.

Software Requirements Specification (SRS)¶

1. Introduction¶

1.1 Purpose¶

1.2 Intended Audience¶

1.3 Scope¶

2. Overall Description¶

2.1 Product Perspective¶

2.2 Software Constraints¶

2.3 User Classes and Characteristics¶

3. Functional Requirements¶

3.1 Extract Body from API Response¶

3.2 Wrap Data for Input to Associator or PickFilter¶

Required Parameters:¶

Optional Parameters (for pickfilter):¶

Input Format (list of pick dicts):¶

Output Format:¶

3.3 Convert Input Files to API Response Format¶

Supported Input Types:¶

Common Parameters:¶

Output Format:¶

3.4 Format Conversion Utilities (NEW)¶

4. Non-Functional Requirements¶

4.1 Performance¶

4.2 Reliability¶

4.3 Usability¶

4.4 Portability¶

5. Installation¶

5.1 From PyPI:¶

5.2 Upgrade:¶

6. Example Usage¶

Example 1: Extract Body from JSON Response¶

Example 2: Create Associator Input Request¶

Example 3: Convert GaMMa CSV to Response JSON¶

Example 4: Convert Formats¶

7. Future Enhancements (Planned)¶

8. Appendices¶

postprocessing_seismo_lib

Navigation

Related Topics