Metadata-Version: 2.4
Name: scig-fault-dataset
Version: 0.1.0
Summary: Loader and feature extraction for the SCIG inter-turn short-circuit fault dataset (3 modalities, 7 classes, 5 kHz).
Project-URL: Homepage, https://github.com/navarmn/scig-fault-dataset
Project-URL: Source code, https://github.com/navarmn/scig-fault-dataset
Project-URL: Dataset, https://doi.org/10.5281/zenodo.20965466
Project-URL: Prior work, https://github.com/navarmn/Wind_turbine_failure_prediction
Author-email: Navar Medeiros M Nascimento <navarmedeiros@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Navar Medeiros M Nascimento
        
        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.
License-File: LICENSE
License-File: NOTICE
Keywords: dataset,fault-detection,induction-generator,scig,signal-processing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=2.0
Requires-Dist: pooch>=1.8
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.11
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: torch>=2.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == 'torch'
Description-Content-Type: text/markdown

# scig-fault-dataset

A Python loader and signal feature extraction library for the SCIG Inter-turn
Short-Circuit Fault Dataset (Squirrel-Cage Induction Generator, 3 sensor
modalities, 7 fault classes, 5 kHz acquisition). Raw signals are hosted
externally and are not stored in this repository.

## Install

```bash
pip install scig-fault-dataset
```

Dependencies pulled in automatically: numpy, pandas, scipy, scikit-learn,
pooch.

For the optional PyTorch Dataset wrapper:

```bash
pip install "scig-fault-dataset[torch]"
```

## Getting the data

Three modes are supported.

### 1. Local path

Pass the dataset root directly to `load()`:

```python
import scig_fault_dataset as scig

for signal, label, meta in scig.load(
    modality="current",
    split="random",
    subset="train",
    root="path/to/SCIG_fault_dataset_v1.0",
):
    ...
```

Or export the environment variable so you can omit `root=` everywhere:

```bash
export SCIG_DATASET_DIR=/path/to/SCIG_fault_dataset_v1.0
```

### 2. Download on demand

`scig_fault_dataset.download()` fetches the archive, checksum-validates it,
and unzips it into a local cache. The cache location is returned by
`default_data_home()` and defaults to the OS user-cache directory; override it
with `SCIG_DATASET_HOME`:

```python
import scig_fault_dataset as scig

root = scig.download()          # fetches, validates, unzips; returns Path
for signal, label, meta in scig.load(modality="current", split="random", subset="train"):
    ...                         # load() finds the cached data automatically
```

By default `download()` fetches the published archive from Zenodo
([DOI 10.5281/zenodo.20965466](https://doi.org/10.5281/zenodo.20965466)) and
verifies it against a baked-in SHA256, so it works out of the box. Set
`SCIG_DATASET_BASE_URL` to point at a mirror or a local `file://` base if you
prefer.

### 3. Validate an existing copy

```python
missing = scig.validate(root="path/to/SCIG_fault_dataset_v1.0")
# Returns [] if the top-level layout looks correct; otherwise lists problems.
```

## Quickstart

```python
import numpy as np
import scig_fault_dataset as scig

signals, labels = [], []

for signal, label, meta in scig.load(
    modality="current",     # "current", "vibration", or "axial_flux"
    split="fr_holdout",     # "random", "fr_holdout", or "if_holdout"
    subset="train",         # "train", "val", or "test"
    root="path/to/SCIG_fault_dataset_v1.0",
):
    signals.append(signal)
    labels.append(label)
    # meta keys include: cls, FR, FG, IF, relative_path, ...

X = np.stack(signals)       # shape (n_samples, n_timepoints, n_channels)
print(X.shape, set(labels))
```

Each iteration yields a tuple `(signal, label, meta)`:

- `signal` - `np.ndarray` of shape `(n_timepoints, n_channels)`.
- `label` - class string such as `"NORMAL"` or `"FAULT_1"`.
- `meta` - dict with operating-point metadata (rotation frequency `FR`,
  grid frequency `FG`, fault intensity `IF`, relative file path, etc.).

Use `scig.list_classes()` and `scig.list_splits()` to query available labels
and splits for a given root.

## Feature extraction

`scig_fault_dataset.features` provides three sklearn-compatible transformers
that operate on `(n_samples, n_timepoints)` arrays (one channel at a time).

```python
import numpy as np
from scig_fault_dataset.features import FourierFeatures, HOSFeatures, SCMFeatures

# X: (n_samples, n_timepoints) - single channel
X = np.random.randn(100, 50000)

feats = FourierFeatures().fit_transform(X)  # Fourier amplitude spectrum features
```

All three transformers follow the sklearn `fit` / `transform` / `fit_transform`
interface and can be dropped into `sklearn.pipeline.Pipeline`.

Bare functional equivalents are also available for one-off use:

```python
from scig_fault_dataset.features import fourier, hos, scm

f_feats = fourier(X)
h_feats = hos(X)
s_feats = scm(X)
```

- `FourierFeatures` / `fourier` - amplitude spectrum features.
- `HOSFeatures` / `hos` - higher-order statistics (skewness, kurtosis, etc.).
- `SCMFeatures` / `scm` - spectral centroid moments, re-implemented from
  Xu et al. 2021 (ASOC 101, 107053, Section 2.2).

## Examples

The `examples/` directory contains two self-contained studies. They are not
installed with the package; run them directly from the cloned repository.

### `examples/replication_paper1/`

Reproduces the paper-1 classification results (Xu et al. 2021). Install its
own dependencies first:

```bash
pip install -r examples/replication_paper1/requirements.txt
```

Entry point: `examples/replication_paper1/paper02_replication.ipynb`.

### `examples/analysis/`

Technical-validation analysis scripts (spectral characterisation, cross-sensor
consistency, asymmetry checks, etc.). Install its own dependencies first:

```bash
pip install -r examples/analysis/requirements.txt
```

Scripts live under `examples/analysis/scig_analysis/`. Note that
`examples/analysis/scig_analysis/confusion.py` requires the project baselines
feature matrix, which is not bundled in this repository.

## Releasing

To cut a release, push a version tag:

```bash
git tag vX.Y.Z
git push origin vX.Y.Z
```

The `release` workflow triggers automatically. It builds the wheel and sdist,
runs `twine check`, then:

- A final tag (matching `vX.Y.Z` exactly, e.g. `v1.0.0`) publishes to **PyPI**.
- A pre-release tag (e.g. `v1.0.0rc1`, `v1.0.0a1`, `v1.0.0b2`, `v1.0.0.dev1`)
  publishes to **TestPyPI**.

After a successful publish the workflow creates a GitHub Release with
auto-generated notes and attaches the wheel and sdist.

The package version comes from the tag via hatch-vcs. Do not edit a version
field by hand.

**Prerequisites (one-time, maintainer):**

1. Configure Trusted Publishers on PyPI and TestPyPI for this repository:
   publisher = GitHub Actions, workflow file = `release.yml`, environment name =
   `pypi` (for PyPI) and `testpypi` (for TestPyPI).
2. Create the `pypi` and `testpypi` GitHub Environments in the repository
   Settings page.

Both Trusted Publishers and both GitHub Environments are configured, and the
pipeline has published `0.1.0rc1` to TestPyPI end-to-end.

## Dataset and citation

The dataset itself is archived on Zenodo under CC BY 4.0:

**SCIG Inter-turn Short-Circuit Fault Dataset**, v1.0.0.
DOI: [10.5281/zenodo.20965466](https://doi.org/10.5281/zenodo.20965466)

If you use the data, please cite it by title, version, and that DOI; a
ready-to-use citation record (`CITATION.cff`) ships inside the archive.

## License

Code: MIT. See `LICENSE` for the full text and `NOTICE` for vendored-code
attribution and re-license terms.

Dataset: CC BY 4.0, hosted on Zenodo at
[10.5281/zenodo.20965466](https://doi.org/10.5281/zenodo.20965466); the
archive also bundles the dataset's own `LICENSE`.
