pcrsaits 1.0.0__tar.gz

pcrsaits-1.0.0/LICENSE

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

pcrsaits-1.0.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: pcrsaits
+Version: 1.0.0
+Summary: PCR-SAITS lightweight residual correction for SAITS and BRITS imputation
+Author: Sawet Somnugpong
+License-Expression: MIT
+Project-URL: Repository, https://github.com/qoozbass/PCR-SAITS
+Project-URL: Paper, https://doi.org/10.1016/j.eswa.2026.134510
+Project-URL: Archive, https://doi.org/10.5281/zenodo.22973879
+Keywords: time-series,imputation,SAITS,BRITS,missing-data
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: torch
+Requires-Dist: pypots
+Dynamic: license-file
+
+# PCR-SAITS
+
+PCR-SAITS is a lightweight residual-correction layer for multivariate
+time-series imputation. The public package exposes the same audited PCR core
+with SAITS and BRITS backbones through a small user-facing API.
+
+Paper:
+
+**PCR-SAITS: A Lightweight Disagreement-Based Residual Corrector for
+SAITS-Based Multivariate Time Series Imputation**  
+Sawet Somnugpong, *Expert Systems with Applications* (2026)  
+DOI: https://doi.org/10.1016/j.eswa.2026.134510
+
+## Install
+
+From this source tree:
+
+```bash
+python -m pip install .
+```
+
+Core dependencies are `numpy`, `torch`, and `pypots`.
+
+## Public API
+
+```python
+from pcrsaits import PCRSAITS, PCRBRITS
+```
+
+Both are thin wrappers around the legacy-equivalence-tested `PCRCorrector`.
+A trained SAITS/BRITS backbone is supplied to the PCR wrapper; the PCR layer
+does not retrain or own the backbone checkpoint.
+
+For a new dataset, explicit feature metadata is the default:
+
+```python
+model = PCRSAITS(
+    backbone=trained_saits,
+    feature_names=["PM2.5", "TEMP", "WSPM"],
+    feature_groups=["pollutant", "meteorological", "meteorological"],
+)
+model.fit(train_values, val_values, seed=7)
+imputed = model.impute(masked_values)
+```
+
+Allowed public feature groups are:
+
+- `pollutant`
+- `sensor`
+- `meteorological`
+
+To reproduce legacy paper-suite name inference, use:
+
+```python
+model = PCRSAITS(
+    backbone=trained_saits,
+    feature_names=["CO(GT)", "PT08.S1(CO)", "T"],
+    metadata_mode="paper_legacy_inference",
+)
+```
+
+## Important inference behavior
+
+PCR correction is applied to every cell that is missing in the supplied input.
+Originally observed cells are restored exactly.
+
+## Save / load
+
+Backbone and PCR checkpoints are intentionally separate:
+
+```python
+trained_saits.save("saits_backbone.pypots")
+model.save("pcrsaits.pt")
+```
+
+After restoring the backbone:
+
+```python
+model = PCRSAITS.load("pcrsaits.pt", backbone=restored_saits)
+```
+
+## Examples
+
+- `examples/quickstart_pcrsaits.py`
+- `examples/quickstart_pcrbrits.py`
+
+## Paper reproduction
+
+Historical experiment programs supplied by the author are preserved under
+`paper_reproduction/legacy_scripts/` with a SHA256 manifest.
+
+```bash
+python paper_reproduction/verify_sources.py
+```
+
+Final reviewer-specific Table 17 and patient-aware PhysioNet source identities
+are recorded separately so that older protocols are not silently presented as
+the final paper protocol.
+
+See:
+
+- `REPRODUCIBILITY.md`
+- `paper_reproduction/README.md`
+- `paper_reproduction/PHYSIONET_PROTOCOL.md`
+
+## Citation
+
+See `CITATION.cff`.
+
+Software archive DOI: https://doi.org/10.5281/zenodo.22973879
+
+## Release status
+
+This tree is the `v1.0.0` release payload prepared for final pre-tag audit.
+The Git tag and archival deposit should be created only after the clean ZIP,
+wheel, and sdist hashes are independently verified.
+
+
+## License
+
+MIT License. See `LICENSE`.

pcrsaits-1.0.0/README.md

@@ -0,0 +1,121 @@
+# PCR-SAITS
+
+PCR-SAITS is a lightweight residual-correction layer for multivariate
+time-series imputation. The public package exposes the same audited PCR core
+with SAITS and BRITS backbones through a small user-facing API.
+
+Paper:
+
+**PCR-SAITS: A Lightweight Disagreement-Based Residual Corrector for
+SAITS-Based Multivariate Time Series Imputation**  
+Sawet Somnugpong, *Expert Systems with Applications* (2026)  
+DOI: https://doi.org/10.1016/j.eswa.2026.134510
+
+## Install
+
+From this source tree:
+
+```bash
+python -m pip install .
+```
+
+Core dependencies are `numpy`, `torch`, and `pypots`.
+
+## Public API
+
+```python
+from pcrsaits import PCRSAITS, PCRBRITS
+```
+
+Both are thin wrappers around the legacy-equivalence-tested `PCRCorrector`.
+A trained SAITS/BRITS backbone is supplied to the PCR wrapper; the PCR layer
+does not retrain or own the backbone checkpoint.
+
+For a new dataset, explicit feature metadata is the default:
+
+```python
+model = PCRSAITS(
+    backbone=trained_saits,
+    feature_names=["PM2.5", "TEMP", "WSPM"],
+    feature_groups=["pollutant", "meteorological", "meteorological"],
+)
+model.fit(train_values, val_values, seed=7)
+imputed = model.impute(masked_values)
+```
+
+Allowed public feature groups are:
+
+- `pollutant`
+- `sensor`
+- `meteorological`
+
+To reproduce legacy paper-suite name inference, use:
+
+```python
+model = PCRSAITS(
+    backbone=trained_saits,
+    feature_names=["CO(GT)", "PT08.S1(CO)", "T"],
+    metadata_mode="paper_legacy_inference",
+)
+```
+
+## Important inference behavior
+
+PCR correction is applied to every cell that is missing in the supplied input.
+Originally observed cells are restored exactly.
+
+## Save / load
+
+Backbone and PCR checkpoints are intentionally separate:
+
+```python
+trained_saits.save("saits_backbone.pypots")
+model.save("pcrsaits.pt")
+```
+
+After restoring the backbone:
+
+```python
+model = PCRSAITS.load("pcrsaits.pt", backbone=restored_saits)
+```
+
+## Examples
+
+- `examples/quickstart_pcrsaits.py`
+- `examples/quickstart_pcrbrits.py`
+
+## Paper reproduction
+
+Historical experiment programs supplied by the author are preserved under
+`paper_reproduction/legacy_scripts/` with a SHA256 manifest.
+
+```bash
+python paper_reproduction/verify_sources.py
+```
+
+Final reviewer-specific Table 17 and patient-aware PhysioNet source identities
+are recorded separately so that older protocols are not silently presented as
+the final paper protocol.
+
+See:
+
+- `REPRODUCIBILITY.md`
+- `paper_reproduction/README.md`
+- `paper_reproduction/PHYSIONET_PROTOCOL.md`
+
+## Citation
+
+See `CITATION.cff`.
+
+Software archive DOI: https://doi.org/10.5281/zenodo.22973879
+
+## Release status
+
+This tree is the `v1.0.0` release payload prepared for final pre-tag audit.
+The Git tag and archival deposit should be created only after the clean ZIP,
+wheel, and sdist hashes are independently verified.
+
+
+## License
+
+MIT License. See `LICENSE`.

pcrsaits-1.0.0/pcrsaits/__init__.py

@@ -0,0 +1,33 @@
+from .backbones import BackboneAdapter, SAITSBackbone, BRITSBackbone
+from .corrector import PCRCorrector
+from .masks import (
+    apply_mask,
+    build_correction_scope,
+    make_holdout_train_mask,
+)
+from .metadata import (
+    VALID_FEATURE_GROUPS,
+    VALID_METADATA_MODES,
+    resolve_core_feature_names,
+)
+from .model import PCRResidualNet
+from .public import PCRSAITS, PCRBRITS
+from .windows import build_windows, reconstruct_from_windows
+
+__all__ = [
+    "BackboneAdapter",
+    "SAITSBackbone",
+    "BRITSBackbone",
+    "PCRCorrector",
+    "PCRSAITS",
+    "PCRBRITS",
+    "PCRResidualNet",
+    "VALID_FEATURE_GROUPS",
+    "VALID_METADATA_MODES",
+    "resolve_core_feature_names",
+    "apply_mask",
+    "build_correction_scope",
+    "make_holdout_train_mask",
+    "build_windows",
+    "reconstruct_from_windows",
+]

pcrsaits-1.0.0/pcrsaits/backbones/__init__.py

@@ -0,0 +1,4 @@
+from .base import BackboneAdapter
+from .saits import SAITSBackbone
+from .brits import BRITSBackbone
+__all__ = ["BackboneAdapter", "SAITSBackbone", "BRITSBackbone"]

pcrsaits-1.0.0/pcrsaits/backbones/_device.py

@@ -0,0 +1,3 @@
+import torch
+def choose_device() -> str:
+    return "cuda" if torch.cuda.is_available() else "cpu"

pcrsaits-1.0.0/pcrsaits/backbones/base.py

@@ -0,0 +1,26 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional
+import numpy as np
+
+class BackboneAdapter(ABC):
+    checkpoint_ext = ".pypots"
+
+    @abstractmethod
+    def fit(self, train_windows: np.ndarray,
+            val_windows: Optional[np.ndarray] = None,
+            val_windows_ori: Optional[np.ndarray] = None) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def impute(self, windows: np.ndarray) -> np.ndarray:
+        raise NotImplementedError
+
+    @abstractmethod
+    def save(self, path: Path) -> None:
+        raise NotImplementedError
+
+    @classmethod
+    @abstractmethod
+    def load_from_checkpoint(cls, path: Path, **kwargs):
+        raise NotImplementedError

pcrsaits-1.0.0/pcrsaits/backbones/brits.py

@@ -0,0 +1,61 @@
+from pathlib import Path
+import numpy as np
+from .base import BackboneAdapter
+from ._device import choose_device
+
+try:
+    from pypots.imputation import BRITS
+except Exception:
+    BRITS = None
+
+class BRITSBackbone(BackboneAdapter):
+    checkpoint_ext = ".pypots"
+
+    def __init__(self, n_steps, n_features, epochs, batch_size, patience,
+                 rnn_hidden_size, verbose=True):
+        if BRITS is None:
+            raise RuntimeError("PyPOTS BRITS is not installed. Please install pypots.")
+        self.model = BRITS(
+            n_steps=n_steps,
+            n_features=n_features,
+            rnn_hidden_size=rnn_hidden_size,
+            batch_size=batch_size,
+            epochs=epochs,
+            patience=patience,
+            num_workers=0,
+            device=choose_device(),
+            verbose=verbose,
+            saving_path=None,
+        )
+        self.verbose = verbose
+
+    def fit(self, train_windows, val_windows=None, val_windows_ori=None):
+        train_set = {"X": train_windows.astype(np.float32)}
+        if val_windows is not None and val_windows_ori is not None:
+            val_set = {
+                "X": val_windows.astype(np.float32),
+                "X_ori": val_windows_ori.astype(np.float32),
+            }
+            try:
+                self.model.fit(train_set, val_set)
+                return
+            except Exception as exc:
+                print(
+                    f"[WARN] BRITS fit with val_set failed: {exc}. "
+                    "Falling back to train only.",
+                    flush=True,
+                )
+        self.model.fit(train_set)
+
+    def impute(self, windows):
+        out = self.model.impute({"X": windows.astype(np.float32)})
+        return np.asarray(out, dtype=float)
+
+    def save(self, path: Path):
+        self.model.save(str(path))
+
+    @classmethod
+    def load_from_checkpoint(cls, path: Path, **kwargs):
+        obj = cls(**kwargs)
+        obj.model.load(str(path))
+        return obj

pcrsaits-1.0.0/pcrsaits/backbones/saits.py

@@ -0,0 +1,57 @@
+from pathlib import Path
+import numpy as np
+from .base import BackboneAdapter
+from ._device import choose_device
+
+try:
+    from pypots.imputation import SAITS
+except Exception:
+    SAITS = None
+
+class SAITSBackbone(BackboneAdapter):
+    checkpoint_ext = ".pypots"
+
+    def __init__(self, n_steps, n_features, epochs, batch_size, patience,
+                 d_model, d_ffn, n_heads, n_layers, dropout, verbose=True):
+        if SAITS is None:
+            raise RuntimeError("PyPOTS is not installed. Please install pypots.")
+        self.model = SAITS(
+            n_steps=n_steps,
+            n_features=n_features,
+            n_layers=n_layers,
+            d_model=d_model,
+            d_ffn=d_ffn,
+            n_heads=n_heads,
+            d_k=d_model // max(1, n_heads),
+            d_v=d_model // max(1, n_heads),
+            dropout=dropout,
+            batch_size=batch_size,
+            epochs=epochs,
+            patience=patience,
+            num_workers=0,
+            device=choose_device(),
+        )
+        self.verbose = verbose
+
+    def fit(self, train_windows, val_windows, val_windows_ori=None):
+        train_set = {"X": train_windows.astype(np.float32)}
+        if val_windows_ori is None:
+            val_windows_ori = val_windows
+        val_set = {
+            "X": val_windows.astype(np.float32),
+            "X_ori": val_windows_ori.astype(np.float32),
+        }
+        self.model.fit(train_set, val_set)
+
+    def impute(self, windows):
+        out = self.model.impute({"X": windows.astype(np.float32)})
+        return np.asarray(out, dtype=float)
+
+    def save(self, path: Path):
+        self.model.save(str(path))
+
+    @classmethod
+    def load_from_checkpoint(cls, path: Path, **kwargs):
+        obj = cls(**kwargs)
+        obj.model.load(str(path))
+        return obj