scig-fault-dataset 0.1.0

Loader and feature extraction for the SCIG inter-turn short-circuit fault dataset (3 modalities, 7 classes, 5 kHz).

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

pip install scig-fault-dataset

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

For the optional PyTorch Dataset wrapper:

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

Getting the data

Three modes are supported.

1. Local path

Pass the dataset root directly to load():

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:

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:

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) 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

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

Quickstart

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).

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:

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:

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:

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:

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

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; the archive also bundles the dataset's own LICENSE.