seismoai-io-usama 0.1.0

Module 1 library for loading and preparing seismic SGY files.

seismoai_io

seismoai_io is Module 1 of the SeismoAI activity. It loads seismic SGY gathers from disk, loads folders of SGY files, and normalizes trace amplitudes so the later visualization, QC, and modeling modules can reuse a consistent data format.

Features

• load_sgy(path): load one SGY/SEGY file into traces and headers
• load_sgy_folder(folder_path): load every SGY/SEGY file in a folder
• normalize_traces(traces, method="zscore"): normalize each trace independently

Installation

pip install seismoai-io-usama

For local development:

pip install -r requirements.txt
pip install .

Usage

from seismoai_io import load_sgy, load_sgy_folder, normalize_traces

gather = load_sgy("path/to/file.sgy")
traces = gather["traces"]
headers = gather["headers"]

normalized = normalize_traces(traces)
folder_data = load_sgy_folder("path/to/sgy_folder")

Returned Data Format

load_sgy() returns a dictionary with:

• path: absolute file path as a string
• traces: numpy.ndarray with shape (n_traces, n_samples)
• headers: pandas.DataFrame with one row per trace header

load_sgy_folder() returns a dictionary keyed by filename, where each value uses the same structure as load_sgy().

Testing

The tests use the provided real SGY dataset archive:

• C:\Users\hp\Downloads\Correlated_Shot_Gathers-20260417T172906Z-3-001.zip

Run the tests with:

pytest

Reflection

This module builds the input layer for the SeismoAI workflow. I learned how SGY gathers can be loaded into NumPy arrays with segyio, how to preserve trace headers for downstream analysis, and how important consistent normalization is before visualization or QC. The work also showed why packaging and tests matter early when other modules depend on one shared interface.