tsgap 0.3.0__tar.gz

tsgap-0.3.0/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+## Version 0.1.1 - Critical Fixes
+
+### Critical Bug Fixes
+
+#### 1. Calibration Bracketing Logic (Fixed) ⚠️
+- **Before**: Bound expansion logic was reversed, causing calibration to fail for extreme rates
+- **After**: Correct bracketing - expands bounds in proper direction
+- **Impact**: Now handles extreme missing rates (1%, 90%) correctly
+
+#### 2. MAR Normalization for 3D Data (Improved)
+- **Before**: Global normalization across all participants
+- **After**: Per-participant normalization for 3D data
+- **Impact**: More consistent MAR behavior across subjects with different scales
+
+#### 3. Base Rate Handling (Fixed)
+- **Before**: `base_rate` could conflict with low `missing_rate`
+- **After**: Automatically capped at `missing_rate * 0.5`
+- **Impact**: Prevents calibration issues with very low missing rates
+
+#### 4. Probability Zeroing (Improved)
+- **Before**: Non-eligible positions handled after sampling
+- **After**: Probabilities zeroed before sampling for cleaner semantics
+- **Impact**: Slightly faster and more explicit logic
+
+### Testing
+
+Added extreme rate testing:
+- Low rates: 1%, 2%, 5% - all within 0.4% of target
+- High rates: 50%, 70%, 90% - all within 1.3% of target
+- MCAR remains exact at all rates
+
+---
+
+## Version 0.1.0 - Initial Release
+
+### Key Improvements
+
+#### 1. Reproducibility (Fixed)
+- **Before**: Used global `np.random.seed()` and direct calls to `np.random.choice()`, `np.random.rand()`
+- **After**: Uses `np.random.Generator` with seed passed through all functions
+- **Impact**: Fully reproducible results with same seed across all mechanisms
+
+#### 2. Consistent Mask Semantics (Fixed)
+- **Before**: MCAR didn't mark existing NaNs as False in returned mask
+- **After**: All mechanisms consistently set `mask[existing_nans] = False`
+- **Impact**: Uniform mask interpretation across all mechanisms
+
+#### 3. Target Dimension Support (Added)
+- **Before**: Only MCAR supported `target` parameter
+- **After**: MAR and MNAR now support `target` parameter
+- **Impact**: Can selectively mask specific dimensions while others drive missingness
+
+#### 4. Improved Calibration (Enhanced)
+- **Before**: Fixed bounds [-10, 10] for binary search
+- **After**: Automatic bound expansion with bracketing
+- **Impact**: Handles extreme missing rates (e.g., 0.01, 0.99) correctly
+
+#### 5. Eligible Position Handling (Fixed)
+- **Before**: MAR/MNAR calibrated over all positions including existing NaNs
+- **After**: Calibration only considers eligible (non-NaN) positions
+- **Impact**: More accurate missing rate achievement on real datasets with existing NaNs
+
+#### 6. Performance Optimization (Improved)
+- **Before**: Nested loops for MNAR normalization (slow on large datasets)
+- **After**: Vectorized normalization using numpy broadcasting
+- **Impact**: ~10-100x faster on large 3D arrays
+
+#### 7. Code Organization (Refactored)
+- Added helper functions:
+  - `_get_eligible_mask()`: Unified eligible position logic
+  - `_calibrate_offset()`: Reusable calibration with auto-bracketing
+- **Impact**: Cleaner code, easier to maintain and extend
+
+### API Changes
+
+All changes are backward compatible. New optional parameters:
+- `rng`: `np.random.Generator` for explicit RNG control
+- `target`: Now supported in MAR and MNAR (was MCAR-only)
+
+### Testing
+
+All 17 unit tests pass:
+- MCAR exact rate control
+- MAR/MNAR approximate rate control
+- Reproducibility with seeds
+- Edge cases (constant signals, existing NaNs)
+- Block missingness patterns
+
+### Documentation
+
+- Updated docstrings with clearer parameter descriptions
+- Added notes about missing rate being applied to eligible entries
+- Clarified mask semantics (True=observed, False=missing)
+- Added mathematical formulations for each mechanism in README

tsgap-0.3.0/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Oripov"
+    given-names: "Feruz"
+    orcid: "https://orcid.org/0009-0001-4303-0512"
+title: "TSGap: Composable Time-Series Missingness Simulation"
+version: 0.3.0
+date-released: 2026-03-16
+url: "https://github.com/feruzoripov/tsgap"
+license: MIT
+repository-code: "https://github.com/feruzoripov/tsgap"
+keywords:
+  - time series
+  - missing data
+  - imputation
+  - benchmarking
+  - simulation
+  - MCAR
+  - MAR
+  - MNAR

tsgap-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to TSGap
+
+Thank you for your interest in contributing to TSGap.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/tsgap.git`
+3. Create a virtual environment: `python -m venv .env && source .env/bin/activate`
+4. Install in development mode: `pip install -e ".[dev]"`
+
+## Running Tests
+
+```bash
+pytest tsgap/tests/ -v
+```
+
+All tests must pass before submitting a pull request.
+
+## Adding a New Pattern
+
+1. Implement your pattern function in `tsgap/patterns.py` following the existing signature:
+   ```python
+   def apply_my_pattern(mask, shape, rng=None, **kwargs):
+       ...
+       return modified_mask
+   ```
+2. Register it in the `PATTERNS` dictionary at the bottom of the file.
+3. Add tests in `tsgap/tests/test_missingness.py`.
+4. Update the docstring in `tsgap/core.py` and `README.md`.
+
+## Adding a New Mechanism
+
+1. Implement in `tsgap/mechanisms.py` following the existing signature.
+2. Register it in the `MECHANISMS` dictionary.
+3. Add tests and update documentation.
+
+## Code Style
+
+- Use type hints (`from __future__ import annotations`)
+- Include docstrings with Parameters/Returns sections (NumPy style)
+- Keep functions focused and composable
+
+## Reporting Issues
+
+Open an issue on GitHub with:
+- A minimal reproducible example
+- Expected vs. actual behavior
+- Python and NumPy versions
+
+## Pull Requests
+
+- One feature per PR
+- Include tests for new functionality
+- Update documentation as needed
+- Ensure all existing tests still pass

tsgap-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Feruz Oripov
+
+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.

tsgap-0.3.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include CONTRIBUTING.md
+recursive-include tsgap *.py