pySEAFOM 0.1.0__tar.gz

pyseafom-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,6 @@
+# Global owners for all files
+* @SEAFOM-Fiber-Optic-Monitoring-Group/pyseafom-admins @SEAFOM-Fiber-Optic-Monitoring-Group/pyseafom-maintainers 
+
+
+# Maintainers own automation and templates
+.github/** @SEAFOM-Fiber-Optic-Monitoring-Group/pyseafom-maintainers

pyseafom-0.1.0/.github/workflows/pr-approvals-check.yml

@@ -0,0 +1,84 @@
+name: Require 1 Admin and 1 Maintainer Approval
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, review_requested]
+  pull_request_review:
+    types: [submitted, edited, dismissed]
+
+permissions:
+  pull-requests: read
+  contents: read
+
+jobs:
+  check-approvals:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const core = require('@actions/core');
+            const prNumber = context.payload.pull_request
+              ? context.payload.pull_request.number
+              : context.payload.review.pull_request_url.split('/').pop();
+
+            const { data: pr } = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: prNumber,
+            });
+
+            const { data: reviews } = await github.rest.pulls.listReviews({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: pr.number,
+              per_page: 100
+            });
+
+            // Keep only the latest review per user
+            const latestByUser = new Map();
+            for (const r of reviews) latestByUser.set(r.user.id, r);
+            const approvals = [...latestByUser.values()].filter(r => r.state === 'APPROVED');
+
+            if (approvals.length === 0) {
+              core.setFailed('No approvals yet.');
+              return;
+            }
+
+            const approverLogins = approvals.map(a => a.user.login.toLowerCase());
+            core.info(`Approvers: ${approverLogins.join(', ')}`);
+
+            async function teamHasUser(org, team_slug, username) {
+              try {
+                await github.rest.teams.getMembershipForUserInOrg({ org, team_slug, username });
+                return true;
+              } catch (e) {
+                return false;
+              }
+            }
+
+            const org = context.repo.owner;
+            const adminTeam = 'pyseafom-admins';
+            const maintainerTeam = 'pyseafom-maintainers';
+            const prAuthor = pr.user.login.toLowerCase();
+
+            let hasAdmin = false;
+            let hasMaintainer = false;
+
+            for (const login of approverLogins) {
+              if (await teamHasUser(org, adminTeam, login)) hasAdmin = true;
+              if (await teamHasUser(org, maintainerTeam, login)) hasMaintainer = true;
+            }
+
+            // Include PR author's approval if they're in either team
+            if (approverLogins.includes(prAuthor)) {
+              if (await teamHasUser(org, adminTeam, prAuthor)) hasAdmin = true;
+              if (await teamHasUser(org, maintainerTeam, prAuthor)) hasMaintainer = true;
+            }
+
+            if (!hasAdmin || !hasMaintainer) {
+              core.setFailed(`Approval missing: need at least 1 Admin (${hasAdmin}) and 1 Maintainer (${hasMaintainer}).`);
+            } else {
+              core.info('Approval policy satisfied: 1 Admin and 1 Maintainer.');
+            }

pyseafom-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SEAFOM Fiber Optic Monitoring Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyseafom-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+# Include documentation and metadata files
+include README.md
+include LICENSE
+include pyproject.toml
+
+# Include example notebooks
+include *.ipynb
+
+# Exclude build artifacts and cache
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .git*

pyseafom-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: pySEAFOM
+Version: 0.1.0
+Summary: Performance analysis and testing tools for Distributed Acoustic Sensing (DAS) systems
+Home-page: https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM
+Author: SEAFOM Fiber Optic Monitoring Group
+Author-email: SEAFOM Fiber Optic Monitoring Group <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM
+Project-URL: Documentation, https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM
+Project-URL: Repository, https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM
+Project-URL: Issues, https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM/issues
+Keywords: DAS,distributed acoustic sensing,self-noise,fiber optic,seismic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: matplotlib>=3.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: flake8>=4.0; extra == "dev"
+Requires-Dist: jupyter>=1.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+![SEAFOM Logo](https://seafom.otm-networks.com/wp-content/uploads/sites/20/2017-12-01_SEAFOM-Fiber-Optic-Monitoring-Group_450x124.png)
+
+# 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 tools for DAS interrogators:
+- **Self-Noise Calculation**: RMS amplitude spectral density across multiple channels
+- **Multi-Section Analysis**: Compare different cable sections or spatial locations
+- **Publication-Ready Plots**: dB-scale visualization with metadata and frequency bands
+- **Text Reports**: Generate formatted reports of key frequencies and band statistics
+- **Flexible Units**: Support for picostrain (pε), nanostrain (nε), radians, and arbitrary units
+- **Window Functions**: Multiple FFT window options (Blackman-Harris, Hann, Hamming, etc.)
+
+### 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
+- *(Add your modules here)*
+
+## 📚 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).

pyseafom-0.1.0/README.md

@@ -0,0 +1,195 @@
+![SEAFOM Logo](https://seafom.otm-networks.com/wp-content/uploads/sites/20/2017-12-01_SEAFOM-Fiber-Optic-Monitoring-Group_450x124.png)
+
+# 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 tools for DAS interrogators:
+- **Self-Noise Calculation**: RMS amplitude spectral density across multiple channels
+- **Multi-Section Analysis**: Compare different cable sections or spatial locations
+- **Publication-Ready Plots**: dB-scale visualization with metadata and frequency bands
+- **Text Reports**: Generate formatted reports of key frequencies and band statistics
+- **Flexible Units**: Support for picostrain (pε), nanostrain (nε), radians, and arbitrary units
+- **Window Functions**: Multiple FFT window options (Blackman-Harris, Hann, Hamming, etc.)
+
+### 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
+- *(Add your modules here)*
+
+## 📚 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).

pyseafom-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=45", "wheel", "setuptools_scm>=6.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pySEAFOM"
+version = "0.1.0"
+description = "Performance analysis and testing tools for Distributed Acoustic Sensing (DAS) systems"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}  # Update if different
+authors = [
+    {name = "SEAFOM Fiber Optic Monitoring Group", email = "your.email@example.com"}
+]
+keywords = ["DAS", "distributed acoustic sensing", "self-noise", "fiber optic", "seismic"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Physics",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "numpy>=1.20.0",
+    "scipy>=1.7.0",
+    "matplotlib>=3.3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=3.0",
+    "black>=22.0",
+    "flake8>=4.0",
+    "jupyter>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM"
+Documentation = "https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM"
+Repository = "https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM"
+Issues = "https://github.com/SEAFOM-Fiber-Optic-Monitoring-Group/pySEAFOM/issues"
+
+[tool.setuptools]
+package-dir = {"" = "source"}
+
+[tool.setuptools.packages.find]
+where = ["source"]