# pySEAFOM
A Python library for performance analysis and testing of Distributed Acoustic Sensing (DAS) interrogators, developed by SEAFOM's Measuring Sensor Performance group. This package provides standardized tools for testing, benchmarking, and performance evaluation of DAS systems following SEAFOM recommended procedures.
## ๐ Purpose
To promote transparency, consistency, and collaboration in the evaluation of DAS interrogator performance by providing open-source tools and standardized workflows.
## โก Quick Start
### Installation
```bash
pip install pySEAFOM
```
### Basic Usage
**Option 1: Import specific functions directly**
```python
from pySEAFOM import calculate_self_noise, plot_combined_self_noise_db
import numpy as np
```
**Option 2: Import modules (recommended when using multiple engines)**
```python
import pySEAFOM
import numpy as np
# Load your DAS data (channels ร time samples)
data = np.load('your_das_data.npy') # Shape: (n_channels, n_samples)
# Define test sections (channel ranges to analyze)
sections = [data[0:50, :], data[100:150, :]] # Two cable sections
section_names = ['Section A', 'Section B']
# Calculate self-noise for each section (using direct import)
results = calculate_self_noise(
sections,
interrogation_rate=10000, # Hz
gauge_length=10.0, # meters
window_function='blackman-harris',
data_type='pฮต' # picostrain
)
# OR using module import:
# results = pySEAFOM.self_noise.calculate_self_noise(
sections,
interrogation_rate=10000, # Hz
gauge_length=10.0, # meters
window_function='blackman-harris',
data_type='pฮต' # picostrain
)
# Visualize results
plot_combined_self_noise_db(
results=results,
test_sections=section_names,
gauge_length=10.0,
org_data_unit='pฮต',
title='DAS Self-Noise Test Results'
)
```
## ๐ Features & Modules
### Current Modules
#### `pySEAFOM.self_noise`
Self-noise analysis
### Future Modules (Planned)
- **Linearity Analysis**: Dynamic range and linearity testing
- **Frequency Response**: Frequency-dependent sensitivity
- **Spatial Resolution**: Gauge length verification
- **Noise Floor**: System noise characterization
## ๐ Documentation
### Main Functions
#### `calculate_self_noise()`
Computes RMS amplitude spectral density across channels.
**Parameters:**
- `sections` (list): List of 2D arrays (channels ร samples) for each test section
- `interrogation_rate` (float): Sampling frequency in Hz
- `gauge_length` (float): Gauge length in meters
- `window_function` (str): FFT window type ('blackman-harris', 'hann', 'none', etc.)
- `data_type` (str): Data unit ('pฮต', 'nฮต', 'rad', or custom)
**Returns:**
- List of tuples: `[(frequencies, asd), ...]` for each section
#### `plot_combined_self_noise_db()`
Creates publication-quality self-noise plots.
**Parameters:**
- `results`: Output from `calculate_self_noise()`
- `test_sections` (list): Section names
- `gauge_length` (float): Gauge length in meters
- `org_data_unit` (str): Display unit
- `title` (str): Plot title
- `sampling_freq` (float): Sampling rate (for metadata box)
- `n_channels` (int): Total channels (for metadata box)
- `duration` (float): Recording duration (for metadata box)
#### `report_self_noise()`
Prints formatted text report.
**Parameters:**
- `results`: Output from `calculate_self_noise()`
- `gauge_length` (float): Gauge length in meters
- `test_sections` (list): Section names
- `band_frequencies` (list): Frequency bands for averaging, e.g., `[(1, 100), (100, 1000)]`
- `report_in_db` (bool): Use dB scale or linear units
- `org_data_unit` (str): Display unit
## ๐งช Example Notebook
See `self_noise_test.ipynb` for a complete example using synthetic data:
- Generates known ASD synthetic signals
- Validates calculation accuracy
- Demonstrates all visualization options
## ๐ Typical Workflow
1. **Prepare Data**: Load DAS measurements (channels ร samples)
2. **Define Sections**: Select channel ranges for analysis
3. **Calculate Self-Noise**: Use `calculate_self_noise()` with appropriate parameters
4. **Visualize**: Create plots with `plot_combined_self_noise_db()`
5. **Report**: Generate text summaries with `report_self_noise()`
## ๐ง Development Setup
```bash
# Clone the repository
git clone https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM.git
cd pySEAFOM
# Install in development mode
pip install -e .
# Install development dependencies
pip install -e ".[dev]"
# Run tests (if available)
pytest tests/
```
## ๐ฆ Package Structure
```
pySEAFOM/
โโโ self_noise - Self-noise analysis module
โ โโโ calculate_self_noise()
โ โโโ plot_combined_self_noise_db()
โ โโโ report_self_noise()
โโโ (future modules) - Additional analysis engines
โโโ examples/ - Example notebooks
โโโ self_noise_test.ipynb
```
## ๐ Adding New Modules
To add a new analysis module:
1. Create `source/your_module.py` with your functions
2. Update `source/__init__.py`:
```python
from . import self_noise, your_module
```
3. Add documentation to README
4. Create example notebook in root directory
See the existing `self_noise.py` module as a template.
## ๐ค Contributing
We welcome contributions from researchers, engineers, and developers working in the fiber optic sensing space. Please see our [contribution guidelines](CONTRIBUTING.md) to get started.
## ๐ License
This project is licensed under the MIT License โ see the [LICENSE](LICENSE) file for details.
This repository follows the [SEAFOM Governance Policy](https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/governance/blob/main/GOVERNANCE.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM",
"name": "pySEAFOM",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "DAS, distributed acoustic sensing, self-noise, fiber optic, seismic",
"author": "SEAFOM Fiber Optic Monitoring Group",
"author_email": "SEAFOM Fiber Optic Monitoring Group <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/23/9a/9161e1767032962f1bdeb10380075cb03013085c744279f097f5e3c2b77e/pyseafom-0.1.3.tar.gz",
"platform": null,
"description": "\r\n\r\n# pySEAFOM\r\n\r\nA Python library for performance analysis and testing of Distributed Acoustic Sensing (DAS) interrogators, developed by SEAFOM's Measuring Sensor Performance group. This package provides standardized tools for testing, benchmarking, and performance evaluation of DAS systems following SEAFOM recommended procedures.\r\n\r\n## \ud83c\udf10 Purpose\r\n\r\nTo promote transparency, consistency, and collaboration in the evaluation of DAS interrogator performance by providing open-source tools and standardized workflows.\r\n\r\n## \u26a1 Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\npip install pySEAFOM\r\n```\r\n\r\n### Basic Usage\r\n\r\n**Option 1: Import specific functions directly**\r\n```python\r\nfrom pySEAFOM import calculate_self_noise, plot_combined_self_noise_db\r\nimport numpy as np\r\n```\r\n\r\n**Option 2: Import modules (recommended when using multiple engines)**\r\n```python\r\nimport pySEAFOM\r\nimport numpy as np\r\n\r\n# Load your DAS data (channels \u00d7 time samples)\r\ndata = np.load('your_das_data.npy') # Shape: (n_channels, n_samples)\r\n\r\n# Define test sections (channel ranges to analyze)\r\nsections = [data[0:50, :], data[100:150, :]] # Two cable sections\r\nsection_names = ['Section A', 'Section B']\r\n\r\n# Calculate self-noise for each section (using direct import)\r\nresults = calculate_self_noise(\r\n sections,\r\n interrogation_rate=10000, # Hz\r\n gauge_length=10.0, # meters\r\n window_function='blackman-harris',\r\n data_type='p\u03b5' # picostrain\r\n)\r\n\r\n# OR using module import:\r\n# results = pySEAFOM.self_noise.calculate_self_noise(\r\n sections,\r\n interrogation_rate=10000, # Hz\r\n gauge_length=10.0, # meters\r\n window_function='blackman-harris',\r\n data_type='p\u03b5' # picostrain\r\n)\r\n\r\n# Visualize results\r\nplot_combined_self_noise_db(\r\n results=results,\r\n test_sections=section_names,\r\n gauge_length=10.0,\r\n org_data_unit='p\u03b5',\r\n title='DAS Self-Noise Test Results'\r\n)\r\n```\r\n\r\n## \ud83d\udcc1 Features & Modules\r\n\r\n### Current Modules\r\n\r\n#### `pySEAFOM.self_noise`\r\nSelf-noise analysis\r\n\r\n### Future Modules (Planned)\r\n- **Linearity Analysis**: Dynamic range and linearity testing\r\n- **Frequency Response**: Frequency-dependent sensitivity\r\n- **Spatial Resolution**: Gauge length verification\r\n- **Noise Floor**: System noise characterization\r\n\r\n## \ud83d\udcda Documentation\r\n\r\n### Main Functions\r\n\r\n#### `calculate_self_noise()`\r\nComputes RMS amplitude spectral density across channels.\r\n\r\n**Parameters:**\r\n- `sections` (list): List of 2D arrays (channels \u00d7 samples) for each test section\r\n- `interrogation_rate` (float): Sampling frequency in Hz\r\n- `gauge_length` (float): Gauge length in meters\r\n- `window_function` (str): FFT window type ('blackman-harris', 'hann', 'none', etc.)\r\n- `data_type` (str): Data unit ('p\u03b5', 'n\u03b5', 'rad', or custom)\r\n\r\n**Returns:**\r\n- List of tuples: `[(frequencies, asd), ...]` for each section\r\n\r\n#### `plot_combined_self_noise_db()`\r\nCreates publication-quality self-noise plots.\r\n\r\n**Parameters:**\r\n- `results`: Output from `calculate_self_noise()`\r\n- `test_sections` (list): Section names\r\n- `gauge_length` (float): Gauge length in meters\r\n- `org_data_unit` (str): Display unit\r\n- `title` (str): Plot title\r\n- `sampling_freq` (float): Sampling rate (for metadata box)\r\n- `n_channels` (int): Total channels (for metadata box)\r\n- `duration` (float): Recording duration (for metadata box)\r\n\r\n#### `report_self_noise()`\r\nPrints formatted text report.\r\n\r\n**Parameters:**\r\n- `results`: Output from `calculate_self_noise()`\r\n- `gauge_length` (float): Gauge length in meters\r\n- `test_sections` (list): Section names\r\n- `band_frequencies` (list): Frequency bands for averaging, e.g., `[(1, 100), (100, 1000)]`\r\n- `report_in_db` (bool): Use dB scale or linear units\r\n- `org_data_unit` (str): Display unit\r\n\r\n## \ud83e\uddea Example Notebook\r\n\r\nSee `self_noise_test.ipynb` for a complete example using synthetic data:\r\n- Generates known ASD synthetic signals\r\n- Validates calculation accuracy\r\n- Demonstrates all visualization options\r\n\r\n## \ud83d\udcca Typical Workflow\r\n\r\n1. **Prepare Data**: Load DAS measurements (channels \u00d7 samples)\r\n2. **Define Sections**: Select channel ranges for analysis\r\n3. **Calculate Self-Noise**: Use `calculate_self_noise()` with appropriate parameters\r\n4. **Visualize**: Create plots with `plot_combined_self_noise_db()`\r\n5. **Report**: Generate text summaries with `report_self_noise()`\r\n\r\n## \ud83d\udd27 Development Setup\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM.git\r\ncd pySEAFOM\r\n\r\n# Install in development mode\r\npip install -e .\r\n\r\n# Install development dependencies\r\npip install -e \".[dev]\"\r\n\r\n# Run tests (if available)\r\npytest tests/\r\n```\r\n\r\n## \ud83d\udce6 Package Structure\r\n\r\n```\r\npySEAFOM/\r\n\u251c\u2500\u2500 self_noise - Self-noise analysis module\r\n\u2502 \u251c\u2500\u2500 calculate_self_noise()\r\n\u2502 \u251c\u2500\u2500 plot_combined_self_noise_db()\r\n\u2502 \u2514\u2500\u2500 report_self_noise()\r\n\u251c\u2500\u2500 (future modules) - Additional analysis engines\r\n\u2514\u2500\u2500 examples/ - Example notebooks\r\n \u2514\u2500\u2500 self_noise_test.ipynb\r\n```\r\n\r\n## \ud83d\udd0c Adding New Modules\r\n\r\nTo add a new analysis module:\r\n\r\n1. Create `source/your_module.py` with your functions\r\n2. Update `source/__init__.py`:\r\n ```python\r\n from . import self_noise, your_module\r\n ```\r\n3. Add documentation to README\r\n4. Create example notebook in root directory\r\n\r\nSee the existing `self_noise.py` module as a template.\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions from researchers, engineers, and developers working in the fiber optic sensing space. Please see our [contribution guidelines](CONTRIBUTING.md) to get started.\r\n\r\n## \ud83d\udcdc License\r\n\r\nThis project is licensed under the MIT License \u2014 see the [LICENSE](LICENSE) file for details.\r\n\r\nThis repository follows the [SEAFOM Governance Policy](https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/governance/blob/main/GOVERNANCE.md).\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Performance analysis and testing tools for Distributed Acoustic Sensing (DAS) systems",
"version": "0.1.3",
"project_urls": {
"Documentation": "https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM",
"Homepage": "https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM",
"Issues": "https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM/issues",
"Repository": "https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM"
},
"split_keywords": [
"das",
" distributed acoustic sensing",
" self-noise",
" fiber optic",
" seismic"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c68ec3ec8f6130569d80bc1b04298b2a89829238a339af86dfd6c4c46e12b65d",
"md5": "72cae31480948ba93079c41080054a1b",
"sha256": "df0bb8d43cc67139e1466188faaf22fe48e9e3ad19fc55d2625dda4dd64bd3e3"
},
"downloads": -1,
"filename": "pyseafom-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "72cae31480948ba93079c41080054a1b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9984,
"upload_time": "2025-11-06T20:25:25",
"upload_time_iso_8601": "2025-11-06T20:25:25.068950Z",
"url": "https://files.pythonhosted.org/packages/c6/8e/c3ec8f6130569d80bc1b04298b2a89829238a339af86dfd6c4c46e12b65d/pyseafom-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "239a9161e1767032962f1bdeb10380075cb03013085c744279f097f5e3c2b77e",
"md5": "0037a4d1e4db17ad9266f3fc20036e59",
"sha256": "860dd3376fe47b803eef0ccba037de7204ee2395478225ac531d02168d2cc817"
},
"downloads": -1,
"filename": "pyseafom-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "0037a4d1e4db17ad9266f3fc20036e59",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 160361,
"upload_time": "2025-11-06T20:25:27",
"upload_time_iso_8601": "2025-11-06T20:25:27.612420Z",
"url": "https://files.pythonhosted.org/packages/23/9a/9161e1767032962f1bdeb10380075cb03013085c744279f097f5e3c2b77e/pyseafom-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-06 20:25:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SEAFOM-Fiber-Optic-Monitoring-Group",
"github_project": "pySEAFOM",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyseafom"
}
JSON
