Metadata-Version: 2.4
Name: seismoai-io-zain
Version: 0.1.0
Summary: Module 1 utilities for loading and preparing SGY seismic files.
Author: Zain
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: segyio
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# seismoai-io-zain

`seismoai-io-zain` is Module 1 of the SeismoAI activity and provides the input layer for the larger seismic analysis pipeline. The package focuses on loading real SGY shot gathers from disk, loading a full folder of SGY files, and normalizing traces for downstream modules.

## Features

- `load_sgy_file(path)` loads one SGY gather into NumPy traces and pandas headers.
- `load_sgy_folder(folder)` loads every `.sgy` file in a folder with a consistent return contract.
- `normalize_traces(traces)` scales each trace by its own maximum absolute amplitude.
- The loader retries with little-endian byte order so it works with the provided correlated shot gathers.

## Installation

Install from the project folder:

```bash
pip install .
```

Install from PyPI after publishing:

```bash
pip install seismoai-io-zain
```

## Usage

```python
from seismoai_io import load_sgy_file, load_sgy_folder, normalize_traces

gather = load_sgy_file("path/to/file.sgy")
print(gather["traces"].shape)
print(gather["headers"].head())

folder_data = load_sgy_folder("path/to/Correlated_Shot_Gathers")
print(len(folder_data))

normalized = normalize_traces(gather["traces"])
print(normalized.shape)
```

## Real Dataset

The activity uses real correlated shot gathers from the provided Forge 2D Survey archive. Keep the dataset outside the package source tree if it is large, and point the loader functions at the extracted folder on your local machine.

## Testing

Run the tests from the project root:

```bash
pytest
```

## Reflection

We built the `seismoai_io` module to provide a clean starting point for the rest of the SeismoAI pipeline. I learned how to turn SGY seismic gathers into structured NumPy arrays and pandas DataFrames that other modules can reuse. I also learned that packaging matters because a working library needs tests, documentation, and installation metadata in addition to the functions themselves. Working against real seismic data made it clear that return formats and normalization rules need to stay simple and predictable. This module helped me see how a small, well-defined package can support a larger collaborative AI workflow.
