Reproducibility package — PR spectral dimension (bearing paper)

---
AIGC:
    Label: "1"
    ContentProducer: 001191110102MACQD9K64018705
    ProduceID: 2763500446026412_0-drive/227015509299921221/gear_synergy/reproducibility_README.md
    ReservedCode1: ""
    ContentPropagator: 001191110102MACQD9K64028705
    PropagateID: 2763500446026412#1792377655682
    ReservedCode2: ""
---
# Reproducibility package — PR spectral dimension (bearing paper)

**Paper:** *The participation ratio counts co-variation channels, not failed components: boundary laws for effective-rank-based health indicators in bearing life*
**Target journal:** Measurement Science and Technology (pre-submission draft)
**Authors:** Guiru Zhao
**Zenodo DOI:** 10.5281/zenodo.23462689

This package contains every script and every numeric/figure artefact used to
produce the results reported in the paper. It does **not** contain the raw
bearing vibration waveforms, which are public but governed by their original
licences; data-source URLs and the expected local directory layout are given
below.

---

## 1. Data (not included)

Four public run-to-failure / run-to-censorship bearing datasets are used
(44 bearings total: 25 ran to failure, 19 right-censored).

| Group | Source | Bearings | Notes |
|---|---|---|---|
| XJTU-SY | Lei Yaguo et al. (2019), https://github.com/catnowbest/BearingDataset | 15 | all RTF |
| NASA IMS (1st campaign) | NIMS, https://www.nasa.gov/intelligent-systems-division/discovery-and-systems-health/ | 4 | all RTF |
| NASA IMS (2nd + 3rd campaigns) | ibid. | 8 | all right-censored |
| FEMTO/PRONOSTIA (IEEE PHM 2012 challenge) | https://www.femto-st.fr/en/research-departments/as2m/demos/PRONOSTIA | 17 | 6 RTF + 11 right-censored |

Expected local layout (matching the scripts' relative paths):

```
chilun/
├── bearing_paired_stats.py
├── bearing_censored_controls.py
├── ...
├── XJTU_SY/            # 15 bearing subfolders (bearing1 … bearing15)
├── USA_1st/            # 1st_test_B1 … B4
├── USA_2nd_3rd/        # 2nd_test_B1 … B4, 3th_test_B1 … B4
└── FEMTO/              # Bearing1_1 … Bearing3_3
```

## 2. Python environment

- Python ≥ 3.10 (tested on 3.12)
- Packages: `numpy`, `scipy`, `pandas`, `matplotlib`. Warnings about
  `numexpr` / `bottleneck` version mismatches in some pandas installs are
  harmless and do not affect any numerical result.
- `torch` is **not** required.
- All scripts use `SEED = 20261018` for bootstrap reproducibility.

## 3. Script map (script → paper section → primary output)

| Script | Paper section(s) | Primary output directory |
|---|---|---|
| `kappa_predictive_all_groups.py` | §2.1, §3.1 (loader + 5-d feature extractor; dynamically loaded by other scripts) | — |
| `bearing_paired_stats.py` (module) | §2.4, §4.2 (equal-*n* paired PR estimator, bootstrap CI, sign test) | `bearing_paired_stats_out/` |
| `bearing_censored_controls.py` | §4.2.1, §6.1 (right-censoring negative control) | `censored_control_out/` |
| `bearing_coord_sensitivity.py` | §4.2, Appendix 6.2 (LODO + ALT5 sensitivity) | `coord_sensitivity_out/` |
| `bearing_femto_window_sensitivity.py` | §6.1 (FEMTO short-window sensitivity) | `femto_window_sensitivity_out/` |
| `bearing_real_bandpass_v2.py` | §5.3 (physically separated envelope fault bands) | `bearing_real_bandpass_v2_out/` |
| `bearing_real_spectrum.py` | §5.3 (Hilbert envelope spectra) | `bearing_real_spectrum_out/` |
| `bearing_crossdomain.py` | §5 (cross-domain companion) | — |
| `fig_pr_life_panels.py` | §4 (Fig. 4) | `pr_life_figure_out/` |
| `gear_planetary_l3b.py` | §2.1, §5.5 (L3 planetary falsification) | — |
| `gear_nsga2.py` | §5.5 (L4 dimension uniqueness + three-level scalarizer attribution; produces 0.44 / 7.00 / 10.32 kg picks) | — |
| `gear_dim_scaling.py` | §5.5 (four boundary tests of the scaling law) | — |

Note: `bearing_real_bandpass.py` (v1) is kept in the archive only for
historical traceability; the paper's §5.3 band-activation numbers are produced
by `bearing_real_bandpass_v2.py` (files `band_activation_v2.csv`,
`fig_band_envelope_spectra.png`, `cage_FTF_diagnostic.png`).

## 4. Running order

Scripts are independent in the sense that each can be re-run on its own;
they all share the same loader and identical definitions of ideal vector,
$\gamma$, PR and equal-*n* window via `bearing_paired_stats.py` and
`kappa_predictive_all_groups.py`. Suggested order:

```bash
# 1. Primary paired PR + 4-group descriptive summary
python3 bearing_paired_stats.py
#   -> bearing_paired_stats_out/paired_group_summary.csv
#   -> bearing_paired_stats_out/paired_per_bearing.csv

# 2. Right-censoring negative control (post hoc, rule fixed before stratified run)
python3 bearing_censored_controls.py
#   -> censored_control_out/censored_stratum_summary.csv
#   -> censored_control_out/censored_per_bearing.csv
#   -> censored_control_out/censored_vs_rtf_delta.png

# 3. Coordinate-choice sensitivity (LODO + ALT5)
python3 bearing_coord_sensitivity.py
#   -> coord_sensitivity_out/coord_config_pooled_summary.csv
#   -> coord_sensitivity_out/coord_config_group_summary.csv
#   -> coord_sensitivity_out/coord_per_bearing.csv

# 4. FEMTO short-window sensitivity
python3 bearing_femto_window_sensitivity.py
#   -> femto_window_sensitivity_out/window_sensitivity.csv
#   -> femto_window_sensitivity_out/femto_per_bearing.csv
#   -> femto_window_sensitivity_out/healthy_null_noise.csv
#   -> femto_window_sensitivity_out/length_diagnostics.csv
#   -> femto_window_sensitivity_out/femto_delta_vs_window.png

# 5. Physical envelope-band replication (§5.3)
python3 bearing_real_bandpass_v2.py
#   -> bearing_real_bandpass_v2_out/band_activation_v2.csv
#   -> bearing_real_bandpass_v2_out/fig_band_envelope_spectra.png
#   -> bearing_real_bandpass_v2_out/cage_FTF_diagnostic.png

python3 bearing_real_spectrum.py
#   -> bearing_real_spectrum_out/real_section_PR.csv
#   -> bearing_real_spectrum_out/real_kappa_int.csv

# 6. Figure 4 (PR vs life-fraction panels)
python3 fig_pr_life_panels.py
#   -> pr_life_figure_out/fig_pr_life_fraction.png
#   -> pr_life_figure_out/fig_pr_life_points.csv
```

## 5. What each output file maps to in the paper

- `paired_group_summary.csv`, `paired_per_bearing.csv` → §4.2 per-group and
  per-bearing healthy/end PR and paired $\Delta$PR values.
- `censored_stratum_summary.csv`, `censored_per_bearing.csv`,
  `censored_vs_rtf_delta.png` → §4.2.1 pooled RTF vs censored difference,
  bootstrap CI, and the separation-failure verdict.
- `coord_config_pooled_summary.csv`, `coord_config_group_summary.csv`,
  `coord_per_bearing.csv` → Appendix 6.2 seven-row coordinate-sensitivity
  table (full + 5 LODO + ALT5) and the 7/7 negative-result robustness
  statement.
- `window_sensitivity.csv`, `healthy_null_noise.csv`, `length_diagnostics.csv`,
  `femto_per_bearing.csv`, `femto_delta_vs_window.png` → §6.1 FEMTO
  short-window sensitivity table and healthy-null calibration.
- `band_activation_v2.csv`, `fig_band_envelope_spectra.png`,
  `cage_FTF_diagnostic.png` → §5.3 BPFO / BPFI / FTF envelope band analysis
  and the dual-defect (bearing 1_5) diagnostic.
- `real_section_PR.csv`, `real_kappa_int.csv` → §5.3 background-normalised
  band-prominence correlation.
- `fig_pr_life_fraction.png`, `fig_pr_life_points.csv` → §4 main
  PR-vs-life-fraction panels.

## 6. Figure file locations

The figures referenced directly by the manuscript live at the following
paths inside the package (matching the `\includegraphics` paths in the tex):

- `pr_life_figure_out/fig_pr_life_fraction.png` — §4, Figure 4 (PR vs life fraction panels)
- `bearing_real_bandpass_v2_out/fig_band_envelope_spectra.png` — §5.3 envelope band spectra
- `gear_planetary_scaling.png` — §5.5 (L3 planetary scaling)
- `gear_nsga2_comparison.png` — §5.5 (L4 scalarizer attribution, 0.44 / 7.00 / 10.32 kg picks)

## 7. Archive subdirectory (development history)

The `archive/` subdirectory contains development-history snapshots. **Numbers
reported in the manuscript are produced by the top-level scripts above; the
scripts in `archive/` are provided only for traceability and must not be
cited as the source of paper figures.** Contents:

| File | Role in development history |
|---|---|
| `gear_kappa_strict.py` + `gear_strict_curve.csv` + `gear_strict_curve.png` | earliest strict version (source of the 38-bearing subset retained for reference) |
| `gear_planetary_l3.py` | original L3 falsification script (the "beat 1" narrative in §5.5) |
| `gear_ensemble.py` + `gear_ensemble.csv` + `gear_ensemble_summary.json` | early ensemble analysis |
| `gear_nsga2_v1.py` | predecessor of `gear_nsga2.py`; superseded after a `Sp = S[pf]` indexing fix that changes the mass picks from 1.84 kg to 0.44 / 7.00 / 10.32 kg |
| `gear_nsga2old.py` | earlier NSGA-II variant |

## 8. A note on claims and registration

The analysis plan was fixed incrementally on the authors' local machines.
As documented in §2.6 of the paper, we did **not** deposit the plan at OSF,
AsPredicted or a journal registered-report track before analysis, and we make
no claim of such independent a priori attestation. The `censored_control`
and `coord_sensitivity` analyses are explicitly marked in the paper as
**post hoc robustness diagnostics**, with their decision rules fixed before
the stratified runs whose results are reported. Local file timestamps are
mutable and are not equivalent to a third-party registration. This archive
is provided as a documentation deposit; it does not retroactively establish
priority.

## 9. Licence

Code in this package is released under the **Creative Commons Attribution 4.0
International (CC BY 4.0)** licence. Raw datasets remain under their original
licences (XJTU-SY, NASA IMS, FEMTO/PRONOSTIA) and are not redistributed here.

## 10. Citing

```bibtex
@software{pr_bearing_package,
  author       = {Zhao, Guiru},
  title        = {Reproducibility package for ``The participation ratio counts
                  co-variation channels, not failed components''},
  month        = {October},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.23462689},
  url          = {https://doi.org/10.5281/zenodo.23462689}
}
```

---