Metadata-Version: 2.4
Name: seismoai-io-usama
Version: 0.1.0
Summary: Module 1 library for loading and preparing seismic SGY files.
Home-page: https://github.com/usama-sherazi/seismoai_io
Author: Usama Sherazi
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: segyio
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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

```bash
pip install seismoai-io-usama
```

For local development:

```bash
pip install -r requirements.txt
pip install .
```

## Usage

```python
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:

```bash
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.
