sth-analysis-tools 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sth_analysis_tools-0.2.0/LICENSE +21 -0
- sth_analysis_tools-0.2.0/MANIFEST.in +19 -0
- sth_analysis_tools-0.2.0/PKG-INFO +559 -0
- sth_analysis_tools-0.2.0/README.md +519 -0
- sth_analysis_tools-0.2.0/analyser_config.yaml +185 -0
- sth_analysis_tools-0.2.0/dev_requirements.txt +5 -0
- sth_analysis_tools-0.2.0/pyproject.toml +113 -0
- sth_analysis_tools-0.2.0/requirements.txt +10 -0
- sth_analysis_tools-0.2.0/setup.cfg +4 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/__init__.py +176 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/__init__.py +53 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/aas_mapping.yaml +192 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/adapter.py +175 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/mapping_engine.py +168 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/model.py +192 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/registry.py +85 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/serializer.py +87 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/__init__.py +0 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/analyzer.py +1114 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/baseline_tracker.py +245 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/dataset_group.py +337 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/features.py +902 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/normalizer.py +326 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/pass_numbering.py +120 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/peak_solver.py +286 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/query_engine.py +245 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/rolling_evaluator.py +487 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/segmenter.py +604 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/tool_life.py +123 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/cli.py +1084 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/configs/cirp_paper_v9.yaml +101 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/core/__init__.py +33 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/core/config.py +823 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/core/exceptions.py +21 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/core/metadata_profile.py +233 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/core/metadata_schema.py +108 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/core/utils.py +115 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/dashboard/__init__.py +10 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/dashboard/app.py +1328 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/dashboard/components.py +1397 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/dashboard/data_service.py +644 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/io/__init__.py +0 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/io/dataset_handle.py +1063 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/io/loader.py +371 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/jupyter.py +80 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/visualization/__init__.py +49 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/visualization/interactive.py +641 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/visualization/reporter.py +568 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools/visualization/visualizer.py +3326 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools.egg-info/PKG-INFO +559 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools.egg-info/SOURCES.txt +82 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools.egg-info/dependency_links.txt +1 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools.egg-info/entry_points.txt +3 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools.egg-info/requires.txt +26 -0
- sth_analysis_tools-0.2.0/src/sth_analysis_tools.egg-info/top_level.txt +1 -0
- sth_analysis_tools-0.2.0/tests/__init__.py +1 -0
- sth_analysis_tools-0.2.0/tests/test_aas.py +383 -0
- sth_analysis_tools-0.2.0/tests/test_attachments_audit.py +67 -0
- sth_analysis_tools-0.2.0/tests/test_cli.py +82 -0
- sth_analysis_tools-0.2.0/tests/test_config_yaml_and_exclusions.py +196 -0
- sth_analysis_tools-0.2.0/tests/test_dashboard.py +207 -0
- sth_analysis_tools-0.2.0/tests/test_dashboard_usability.py +319 -0
- sth_analysis_tools-0.2.0/tests/test_dataset_group.py +81 -0
- sth_analysis_tools-0.2.0/tests/test_dependency_enforcement.py +76 -0
- sth_analysis_tools-0.2.0/tests/test_e2e_real_datasets.py +221 -0
- sth_analysis_tools-0.2.0/tests/test_features.py +149 -0
- sth_analysis_tools-0.2.0/tests/test_harmonics_visualizer.py +117 -0
- sth_analysis_tools-0.2.0/tests/test_interactive.py +112 -0
- sth_analysis_tools-0.2.0/tests/test_loader.py +64 -0
- sth_analysis_tools-0.2.0/tests/test_metadata_query.py +154 -0
- sth_analysis_tools-0.2.0/tests/test_normalizer.py +54 -0
- sth_analysis_tools-0.2.0/tests/test_numeric_accuracy_snapshots.py +113 -0
- sth_analysis_tools-0.2.0/tests/test_oo_library.py +96 -0
- sth_analysis_tools-0.2.0/tests/test_packet_and_trim.py +48 -0
- sth_analysis_tools-0.2.0/tests/test_pass_numbering.py +69 -0
- sth_analysis_tools-0.2.0/tests/test_query_engine.py +168 -0
- sth_analysis_tools-0.2.0/tests/test_rolling_evaluator.py +102 -0
- sth_analysis_tools-0.2.0/tests/test_segmentation_diagnostic.py +76 -0
- sth_analysis_tools-0.2.0/tests/test_segmentation_switches.py +153 -0
- sth_analysis_tools-0.2.0/tests/test_segmenter.py +45 -0
- sth_analysis_tools-0.2.0/tests/test_time_base_and_stage2.py +89 -0
- sth_analysis_tools-0.2.0/tests/test_tool_life.py +79 -0
- sth_analysis_tools-0.2.0/tests/test_wear_kpis_and_reporting.py +87 -0
- sth_analysis_tools-0.2.0/tests/test_working_directory_and_timing.py +74 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Institute of Production Engineering and Photonic Technologies (IFT), TU Wien
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
include LICENSE
|
|
2
|
+
include README.md
|
|
3
|
+
include pyproject.toml
|
|
4
|
+
include analyser_config.yaml
|
|
5
|
+
include requirements.txt
|
|
6
|
+
include dev_requirements.txt
|
|
7
|
+
|
|
8
|
+
recursive-include src/sth_analysis_tools *
|
|
9
|
+
recursive-include tests *.py
|
|
10
|
+
|
|
11
|
+
recursive-exclude report *
|
|
12
|
+
recursive-exclude clean_data *
|
|
13
|
+
recursive-exclude output *
|
|
14
|
+
recursive-exclude docs *
|
|
15
|
+
recursive-exclude scripts *
|
|
16
|
+
recursive-exclude examples *
|
|
17
|
+
recursive-exclude .pytest_cache *
|
|
18
|
+
|
|
19
|
+
global-exclude *.py[cod] __pycache__ *.so *.dylib *.swp *.DS_Store
|
|
@@ -0,0 +1,559 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sth-analysis-tools
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: CIRP Sensory Toolholder (STH) Normalization & Analysis Tools
|
|
5
|
+
Author-email: IFT - TU Wien <trautner@ift.at>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Classifier: Programming Language :: Python :: 3
|
|
8
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
9
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
11
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
12
|
+
Classifier: Topic :: Scientific/Engineering :: Information Analysis
|
|
13
|
+
Requires-Python: >=3.10
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Requires-Dist: h5py>=3.8.0
|
|
17
|
+
Requires-Dist: numpy>=1.23.0
|
|
18
|
+
Requires-Dist: scipy>=1.10.0
|
|
19
|
+
Requires-Dist: pandas>=1.5.0
|
|
20
|
+
Requires-Dist: matplotlib>=3.6.0
|
|
21
|
+
Requires-Dist: markdown>=3.4.0
|
|
22
|
+
Requires-Dist: xhtml2pdf>=0.2.11
|
|
23
|
+
Requires-Dist: typer>=0.9.0
|
|
24
|
+
Requires-Dist: rich>=12.0.0
|
|
25
|
+
Requires-Dist: pyyaml>=6.0
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
28
|
+
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
|
|
29
|
+
Requires-Dist: ruff==0.17.1; extra == "dev"
|
|
30
|
+
Requires-Dist: vulture==2.16; extra == "dev"
|
|
31
|
+
Requires-Dist: build>=1.0; extra == "dev"
|
|
32
|
+
Requires-Dist: twine>=5.0; extra == "dev"
|
|
33
|
+
Provides-Extra: dashboard
|
|
34
|
+
Requires-Dist: dash>=2.14.0; extra == "dashboard"
|
|
35
|
+
Requires-Dist: dash-bootstrap-components>=1.5.0; extra == "dashboard"
|
|
36
|
+
Requires-Dist: plotly>=5.18.0; extra == "dashboard"
|
|
37
|
+
Provides-Extra: all
|
|
38
|
+
Requires-Dist: sth-analysis-tools[dashboard,dev]; extra == "all"
|
|
39
|
+
Dynamic: license-file
|
|
40
|
+
|
|
41
|
+
# STH Analysis Tools (`sth-analysis-tools`)
|
|
42
|
+
|
|
43
|
+
[](https://www.python.org/downloads/)
|
|
44
|
+
[](LICENSE)
|
|
45
|
+
|
|
46
|
+
A Python package and CLI developed by the **Institute of Production Engineering and Photonic Technologies (IFT), TU Wien** for the **CIRP Sensory Toolholder Milling Initiative**.
|
|
47
|
+
|
|
48
|
+
`sth-analysis-tools` provides signal processing and wear proxy extraction for single-axis sensory toolholders equipped with high-frequency accelerometers (ADXL1001, about 9.47 kHz, BLE packets of three samples). It eliminates sensor DC offsets and thermal baseline drift, extracts spindle rotational modulation, automates cutting pass segmentation, and tracks 31 physical wear proxy KPIs across tool lifecycles.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## The Physical Signal Model
|
|
53
|
+
|
|
54
|
+
The raw acceleration signal $a_{\mathrm{raw}}(t)$ recorded by the toolholder sensor is modeled as:
|
|
55
|
+
|
|
56
|
+
$$a_{\mathrm{raw}}(t) = a_{\mathrm{dyn}}(t) + a_{\mathrm{rot}}(t) + b_0 + \Delta\mu_{\mathrm{thermal}}(t)$$
|
|
57
|
+
|
|
58
|
+
- $a_{\mathrm{dyn}}(t)$: Dynamic cutting vibration from tooth engagement, chip shearing, and chatter.
|
|
59
|
+
- $a_{\mathrm{rot}}(t)$: Spindle rotation-synchronous sine wave modulation (tool runout / unbalance).
|
|
60
|
+
- $b_0$: Static sensor zero-g manufacturing offset.
|
|
61
|
+
- $\Delta\mu_{\mathrm{thermal}}(t)$: Low-frequency baseline drift caused by frictional bearing heating and thermal expansion.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Key Features
|
|
66
|
+
|
|
67
|
+
- **PCHIP Baseline Detrending**: Reconstructs continuous baseline drift from free-air dwell intervals without phase distortion or attenuation of dynamic cutting frequencies.
|
|
68
|
+
- **Rotational Modulation Compensation**: Extracts the 1x component with a zero-phase Butterworth band-pass (0.7–1.3 f_rot) inside every stretch without lost packets.
|
|
69
|
+
- **Counter-based time base**: Places every sample by the BLE packet counter (lost packets stay gaps); the sampling rate comes from `sensor.fs_hz` in the configuration (required).
|
|
70
|
+
- **Universal 1.5s Cut Edge Trimming**: Enforces a default 1.5s boundary trim on cutting intervals to eliminate entry/exit shock transients.
|
|
71
|
+
- **31 Tool Wear Proxies**: Computes statistical (RMS, Peak-to-Peak, Crest Factor, Skewness, Kurtosis), spectral (TPF harmonics 1..8, centroid, flatness), and energy indicators.
|
|
72
|
+
- **High-Speed Streaming & Parallel CLI**: Multi-core CPU processing directly from standard HDF5 containers without modifying raw source files.
|
|
73
|
+
- **Interactive Cut Explorer Dashboard**: High-resolution pass-level metric overviews with synchronized time-domain and log PSD harmonic jump-in inspection.
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Installation
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
pip install sth-analysis-tools # library and the sth-tool CLI
|
|
81
|
+
pip install "sth-analysis-tools[dashboard]" # + the Dash web explorer
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Python 3.10 or newer. For development:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
git clone https://git.ift.tuwien.ac.at/pub/pypi/sth-analysis.git
|
|
88
|
+
cd sth-analysis
|
|
89
|
+
pip install -e ".[dev]"
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## Quickstart (Python API)
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
import sth_analysis_tools as sth
|
|
98
|
+
|
|
99
|
+
# Initialize analyzer on dataset directory with working copy isolation
|
|
100
|
+
analyzer = sth.ToolAnalyzer("clean_data/", working_directory="output/working_directory")
|
|
101
|
+
|
|
102
|
+
# Query datasets using pure JSONPath expressions
|
|
103
|
+
ctu_tools = analyzer.find(jsonpath="$.pre.parameters.tool_id == '0005-A'")
|
|
104
|
+
|
|
105
|
+
# Or query using custom lambda predicate functions
|
|
106
|
+
# ctu_tools = analyzer.find(query=lambda meta: meta.get("pre", {}).get("parameters", {}).get("tool_id") == "0005-A")
|
|
107
|
+
|
|
108
|
+
# Execute end-to-end processing pipeline on a dataset (default 1.5s edge trimming)
|
|
109
|
+
ds = ctu_tools[0]
|
|
110
|
+
cut_metrics = ds.process_pipeline(trim_edge_s=1.5)
|
|
111
|
+
|
|
112
|
+
# Inspect computed wear proxies (including clean and per-revolution median metrics)
|
|
113
|
+
print(cut_metrics[["cut_index", "rms_g", "rms_clean_g", "rms_median_g", "harmonic_power_ratio"]])
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Command-Line Interface (`sth-tool`)
|
|
119
|
+
|
|
120
|
+
The package provides a CLI (`sth-tool`) for batch processing, metadata searching, diagnostic inspection, image extraction, and publication figure generation.
|
|
121
|
+
|
|
122
|
+
### 1. `sth-tool process` — Batch Normalization & Feature Extraction
|
|
123
|
+
Executes the dataset-first single-pass processing pipeline: dwell segmentation, PCHIP baseline detrending, spindle rotational sine modulation fitting, edge trimming, and extraction of all 31 cut features.
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
# Process all datasets in parallel using all CPU cores with default 1.5s edge trimming
|
|
127
|
+
sth-tool process --data-dir clean_data/ --work-dir output/working_directory/
|
|
128
|
+
|
|
129
|
+
# Force recalculation and overwrite existing HDF5 files in the workspace
|
|
130
|
+
sth-tool process --data-dir clean_data/ --work-dir output/working_directory/ --force
|
|
131
|
+
|
|
132
|
+
# Custom parallel workers and edge trimming
|
|
133
|
+
sth-tool process --data-dir clean_data/ --work-dir output/working_directory/ --jobs 8 --trim-edge-s 2.0
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
| Option | Flag | Default | Description |
|
|
137
|
+
| :--- | :--- | :--- | :--- |
|
|
138
|
+
| `--config` | `-c` | `analyser_config.yaml` | Path to YAML configuration file. |
|
|
139
|
+
| `--data-dir` | `-d` | `paths.data_dir` | Input dataset directory containing raw HDF5 files (default: `clean_data/`). |
|
|
140
|
+
| `--work-dir` | `-w` | `paths.work_dir` | Working directory for enriched/processed HDF5 files (default: `output/working_directory/`). |
|
|
141
|
+
| `--output-dir` | `-o` | `paths.output_dir` | Base output directory (default: `output/`). |
|
|
142
|
+
| `--force` | `-f` | `False` | Force complete recalculation and overwrite cached files. |
|
|
143
|
+
| `--jobs` | `-j` | `execution.jobs` | Number of parallel worker CPU processes (0 = Auto/all cores). |
|
|
144
|
+
| `--trim-edge-s` | | `execution.trim_edge_s` | Cut interval edge trimming in seconds (default: 1.5s). |
|
|
145
|
+
| `--trim-edge-pct`| | `execution.trim_edge_pct`| Cut interval proportional edge trimming fraction (default: 0.0). |
|
|
146
|
+
| `--recursive` | | `True` | Recursively search subdirectories for HDF5 files. |
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
### 2. `sth-tool plot` — Publication Figure Generation
|
|
152
|
+
Renders campaign-wide multi-tool wear progression curves, 3-stage kinematic tooth harmonics combs, or single-dataset diagnostic grids.
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
# 1. Render all campaign wear proxy progression figures across all 29 physical features
|
|
156
|
+
sth-tool plot --type campaign --all
|
|
157
|
+
|
|
158
|
+
# 2. Render specific wear proxies (e.g. clean RMS and per-revolution median PTP)
|
|
159
|
+
sth-tool plot --type campaign -m rms_clean_g -m rms_median_g -m peak_to_peak_median_g
|
|
160
|
+
|
|
161
|
+
# 3. Focus campaign evaluation on the final N cutting passes per tool (EOL focus)
|
|
162
|
+
sth-tool plot --type campaign --all --last-n-cuts 5
|
|
163
|
+
|
|
164
|
+
# 4. Render 3-stage kinematic tooth harmonics combs for all tools (uncompensated)
|
|
165
|
+
sth-tool plot --type harmonics
|
|
166
|
+
|
|
167
|
+
# 5. Render tooth harmonics with sine-modulation compensation, fixed y-limits, and peak markers
|
|
168
|
+
sth-tool plot --type harmonics --compensated --ylim "-6,6" --fft-ylim "-50,10"
|
|
169
|
+
|
|
170
|
+
# 6. Render tooth harmonics without peak markers for a specific tool
|
|
171
|
+
sth-tool plot --type harmonics --query "tool_id=0006D" --compensated --no-peaks
|
|
172
|
+
|
|
173
|
+
# 7. Render single-dataset 2x2 diagnostic inspection grids
|
|
174
|
+
sth-tool plot --type dataset
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
| Option | Flag | Default | Description |
|
|
178
|
+
| :--- | :--- | :--- | :--- |
|
|
179
|
+
| `--type` | `-t` | `campaign` | Plot mode: `campaign` (lifecycle curves), `harmonics` (tooth combs), `dataset` (2x2 grid). |
|
|
180
|
+
| `--all` | `-a` | `False` | Render all available wear proxy figures. |
|
|
181
|
+
| `--metric` / `--proxies` | `-m` / `-p` | `None` | Specific metric key(s) to plot (can be repeated). |
|
|
182
|
+
| `--query` | `-q` | `None` | Metadata query filter (e.g. `twm1`, `twm2`, `tool_id=0005-A`). |
|
|
183
|
+
| `--group-by` | `-g` | `tool_id` | Metadata attribute to group progression curves by. |
|
|
184
|
+
| `--last-n-cuts` | `-n` | `None` | Restrict evaluation sequence to the final N cuts per tool. |
|
|
185
|
+
| `--compensated` | `-C` | `False` | Render harmonics plot with sine-modulation-compensated acceleration as primary line. |
|
|
186
|
+
| `--show-peaks / --no-peaks` | | `True` | Toggle kinematic tooth impact peak markers (Tooth 1 / Tooth 2) in harmonics plots. |
|
|
187
|
+
| `--ylim` | `-y` | `None` | Fixed y-axis acceleration range (e.g. `"-6,6"` or `"6"`). |
|
|
188
|
+
| `--fft-ylim` | `-fy` | `None` | Fixed FFT PSD limits in dB (e.g. `"-50,10"`). |
|
|
189
|
+
| `--fft-xlim` | `-fx` | `None` | Fixed FFT frequency range in Hz (e.g. `"0,900"`). |
|
|
190
|
+
| `--force-raw` | | `False` | Recompute directly from raw HDF5 rather than cached enriched data. |
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
### 3. `sth-tool search` — Dataset Querying & Metadata Inspection
|
|
195
|
+
Fast metadata filtering and summary table display across datasets using JSONPath or key-value queries.
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
# Query by tool identifier
|
|
199
|
+
sth-tool search -q "tool_id=0005-A"
|
|
200
|
+
|
|
201
|
+
# Query by organization using JSONPath
|
|
202
|
+
sth-tool search --jsonpath "$.pre.parameters.organization ~ 'Dortmund'"
|
|
203
|
+
|
|
204
|
+
# Search by filename pattern
|
|
205
|
+
sth-tool search --pattern ".*twm_1.*"
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
### 4. `sth-tool export-images` — Optical Microscope Wear Photograph Extraction
|
|
211
|
+
Extracts and categorizes embedded high-resolution tool photographs (pre/post setup, peripheral wear, end face wear, chip morphology, broken tool inspection) from HDF5 metadata containers.
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
# Export all embedded photos across datasets
|
|
215
|
+
sth-tool export-images --data-dir clean_data/ --output-dir output/extracted_images/
|
|
216
|
+
|
|
217
|
+
# Export only tool wear and broken tool images for a specific tool
|
|
218
|
+
sth-tool export-images --data-dir clean_data/ -c peripheral -c end -c broken -q "tool_id=0005-A"
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
### 5. `sth-tool inspect` — Intra-Cut Rolling Anomaly & Chatter Audit
|
|
224
|
+
Performs cycle-by-cycle rolling window evaluation within cutting passes to detect chatter onset, micro-chipping, or pre-breakage trends before final tool failure.
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
# Audit broken tool passes with rolling window evaluation
|
|
228
|
+
sth-tool inspect --data-dir clean_data/ -q "tool_breakage=true"
|
|
229
|
+
|
|
230
|
+
# Generate multi-panel rolling feature progression plots
|
|
231
|
+
sth-tool inspect --data-dir clean_data/ -q "tool_id=0005-C" --plot --window-revs 3.0 --step-revs 0.5
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
### 6. `sth-tool dashboard` — Interactive Web Explorer (Dash & Plotly)
|
|
237
|
+
Launches the browser-based interactive STH Milling Explorer dashboard featuring dynamic metadata querying, single-pass min-max envelope overview, strictly clamped un-decimated 1.0s oscilloscope with Welch log PSD & kinematic harmonic markers ($f_{\mathrm{rot}}, f_{\mathrm{TPF}}$), rolling intra-cut dynamics & 2D STFT spectrogram waterfall heatmaps, and multi-tool wear progression with cut exclusion handling.
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
# Launch dashboard on default localhost (http://127.0.0.1:8050)
|
|
241
|
+
sth-tool dashboard
|
|
242
|
+
|
|
243
|
+
# Bind to custom interface and port with hot-reload debug mode
|
|
244
|
+
sth-tool dashboard --host 0.0.0.0 --port 8080 --debug
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
| Option | Flag | Default | Description |
|
|
248
|
+
| :--- | :--- | :--- | :--- |
|
|
249
|
+
| `--host` | `-H` | `127.0.0.1` | Host interface to bind the Dash web server to. |
|
|
250
|
+
| `--port` | `-p` | `8050` | Port number for the Dash web server. |
|
|
251
|
+
| `--debug` | `-d` | `False` | Enable Dash hot-reloading and debug mode. |
|
|
252
|
+
| `--data-dir` | | `paths.data_dir` | Custom path to clean HDF5 data directory. |
|
|
253
|
+
| `--config` | `-c` | `analyser_config.yaml` | Path to custom YAML configuration file. |
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
### 7. `sth-tool aas` — Industry 4.0 Asset Administration Shell (IEC 63278-1)
|
|
258
|
+
Generates, inspects, and exports standardized AAS Digital Twins adhering to IEC 63278-1 and IDTA Specifications with ECLASS IRDI semantic identifiers:
|
|
259
|
+
- **IDTA-02006 Digital Nameplate** (`0173-1#01-AHF578#003`): Manufacturer, product designation, serial number, year of construction.
|
|
260
|
+
- **IDTA-02003 Technical Data** (`0173-1#01-AHF579#003`): Tool dimensions ($d_1, l_1, z$), tool material, workpiece material.
|
|
261
|
+
- **Machining Process Data** (`0173-1#01-ADN781#005`): Operational kinematics ($v_c, f_z, a_p, a_e$, milling mode, cooling/lubricant).
|
|
262
|
+
- **IDTA-02004 Time Series Data** (`https://admin-shell.io/idta/TimeSeriesData/1/0`): High-rate dynamic telemetry with direct URI fragment pointer to internal HDF5 dataset (`file://<filename>#/acceleration`).
|
|
263
|
+
- **Tool Wear Monitoring** (`urn:cirp:submodel:wear_monitoring:1.0`): Steady-state RMS proxy, median peak-to-peak impact, flute asymmetry index, chatter indicator ratio, and operational state.
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
# Inspect AAS Digital Twin and Submodel hierarchy for a specific tool in Rich formatted tree
|
|
267
|
+
sth-tool aas info 0006A
|
|
268
|
+
|
|
269
|
+
# Export compliant AAS JSON digital twin envelopes for filtered datasets
|
|
270
|
+
sth-tool aas export 0006A --output-dir output/reports/aas/
|
|
271
|
+
|
|
272
|
+
# Embed the generated AAS Digital Twin JSON directly into the HDF5 container (/embedded_files/aas_digital_twin.json)
|
|
273
|
+
sth-tool aas embed clean_data/isf/ISF_0006A_01.h5
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
**Python AAS API:**
|
|
277
|
+
```python
|
|
278
|
+
handle = sth.ToolAnalyzer("clean_data/").find(tool_id="0006A")[0]
|
|
279
|
+
|
|
280
|
+
# 1. Generate in-memory IEC 63278-1 compliant dictionary
|
|
281
|
+
aas_dict = handle.to_aas()
|
|
282
|
+
|
|
283
|
+
# 2. Export to validated AAS JSON file
|
|
284
|
+
json_path = handle.export_aas("output/reports/aas/tool_0006A_aas.json")
|
|
285
|
+
|
|
286
|
+
# 3. Embed directly into HDF5 container for offline carrier distribution
|
|
287
|
+
handle.embed_aas_twin()
|
|
288
|
+
|
|
289
|
+
# 4. Access embedded or dynamically generated digital twin
|
|
290
|
+
twin = handle.aas_digital_twin
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
---
|
|
294
|
+
|
|
295
|
+
## Configuration & Dynamic Exclusions (`analyser_config.yaml`)
|
|
296
|
+
|
|
297
|
+
Both the CLI and Python library (`ToolAnalyzer`, `STHConfig`) are configured via `analyser_config.yaml`. This file defines default filesystem paths, publication plot destinations, execution defaults, and generic metadata-driven exclusion rules.
|
|
298
|
+
|
|
299
|
+
```yaml
|
|
300
|
+
sensor:
|
|
301
|
+
fs_hz: 9466.5 # sampling rate of the sensor [Hz], required (measured from the tooth-passing line)
|
|
302
|
+
|
|
303
|
+
paths:
|
|
304
|
+
data_dir: "clean_data"
|
|
305
|
+
work_dir: "output/working_directory"
|
|
306
|
+
output_dir: "output"
|
|
307
|
+
|
|
308
|
+
plots:
|
|
309
|
+
wear_proxies: "plots/wear_proxies"
|
|
310
|
+
harmonics: "plots/harmonics"
|
|
311
|
+
dataset_grid: "plots/dataset_grid"
|
|
312
|
+
rolling: "plots/rolling"
|
|
313
|
+
|
|
314
|
+
exports:
|
|
315
|
+
reports: "reports"
|
|
316
|
+
images: "extracted_images"
|
|
317
|
+
metadata: "metadata"
|
|
318
|
+
|
|
319
|
+
execution:
|
|
320
|
+
jobs: 0
|
|
321
|
+
trim_edge_s: 1.5
|
|
322
|
+
trim_edge_pct: 0.0
|
|
323
|
+
|
|
324
|
+
segmentation: # pass/dwell segmentation (defaults shown)
|
|
325
|
+
window_s: 0.5 # window and step of the short-time feature [s]
|
|
326
|
+
step_s: 0.1
|
|
327
|
+
feature: "sigma" # "sigma" (std of the raw signal) or "band_rms" (RMS of the signal band-passed
|
|
328
|
+
band: {low_frot: 1.5, high_hz: 1000.0, order: 2} # low_frot * f_rot .. high_hz, zero-phase Butterworth)
|
|
329
|
+
hysteresis_low: null # a cut ends only below tau_off (null: one threshold)
|
|
330
|
+
hysteresis_reference: "tau" # tau_off = hysteresis_low * tau* ("tau") or a + hysteresis_low * (tau* - a) with the
|
|
331
|
+
# air level a = 5th percentile of the feature ("air")
|
|
332
|
+
gap_bridge_s: 3.5 # active runs closer than this are joined [s]
|
|
333
|
+
min_dwell_s: 0.0 # shorter dwells are joined to the passes [s]
|
|
334
|
+
min_cut_duration_s: 3.0 # shorter segments are dropped [s]
|
|
335
|
+
count_weight: 100.0 # cost per missing or surplus pass in the threshold cost
|
|
336
|
+
target_count: "file" # target of the threshold cost: "file" (n_cuts_in_file) or "executed"
|
|
337
|
+
# (n_cuts_in_file minus post.passes_not_recorded, also for broken runs)
|
|
338
|
+
breakage_target: "metadata" # broken runs with target_count "file": "metadata" or "protocol" (8 / 6 passes)
|
|
339
|
+
pass_numbering: "sequential" # "sequential" or "metadata" (from n_cuts_total)
|
|
340
|
+
|
|
341
|
+
baseline:
|
|
342
|
+
anchor_guard: null # discard an anchor window whose 1x band (0.7-1.3 f_rot) p-p per revolution exceeds
|
|
343
|
+
# anchor_guard x the recording's air level (P5 over all dwell revolutions)
|
|
344
|
+
|
|
345
|
+
exclusions:
|
|
346
|
+
min_file_size_mb: 0.0 # off (default); compressed files make the size no measure of the content
|
|
347
|
+
file_patterns:
|
|
348
|
+
- "*2026-06-18_15-18-09*"
|
|
349
|
+
- "*2026-06-18_15-28-59*"
|
|
350
|
+
rules:
|
|
351
|
+
tools:
|
|
352
|
+
type: "list"
|
|
353
|
+
keys:
|
|
354
|
+
- "$.pre.parameters.tool_id"
|
|
355
|
+
- "$.pre.parameters.tool.id"
|
|
356
|
+
values:
|
|
357
|
+
- "IFT-001"
|
|
358
|
+
- "PTW-001"
|
|
359
|
+
- "PTW-002"
|
|
360
|
+
- "0005-C"
|
|
361
|
+
short_runs:
|
|
362
|
+
type: "jsonpath"
|
|
363
|
+
expression: "$.file_size_mb < 2.0"
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
### Packaged configurations
|
|
367
|
+
|
|
368
|
+
Configurations shipped with the package are loaded by name instead of a path:
|
|
369
|
+
|
|
370
|
+
```python
|
|
371
|
+
from sth_analysis_tools.core.config import get_config, packaged_config_names
|
|
372
|
+
|
|
373
|
+
packaged_config_names() # ['cirp_paper_v9']
|
|
374
|
+
cfg = get_config("cirp_paper_v9") # settings of the HSM compensation paper
|
|
375
|
+
cfg = get_config("default") # built-in defaults, no file
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
`cirp_paper_v9` holds the sampling rate, the segmentation (band-RMS feature, hysteresis 0.7 to the air level, dwells
|
|
379
|
+
of at least 1 s), metadata pass numbering, and the file and cut exclusions of the paper. Its file and cut rules match
|
|
380
|
+
the original file names of the CIRP STH dataset. `STH_CONFIG_FILE` may also name a packaged configuration's file.
|
|
381
|
+
|
|
382
|
+
### Regular passes of a tool life
|
|
383
|
+
|
|
384
|
+
`analytics.tool_life` joins the pass tables of all recordings of one tool (in time order) and numbers the passes in
|
|
385
|
+
the tool life from the metadata counters (`n_cuts_total`, `n_cuts_in_file`, `passes_not_recorded`):
|
|
386
|
+
|
|
387
|
+
```python
|
|
388
|
+
from sth_analysis_tools.analytics.tool_life import ToolFile, file_rows, regular_passes
|
|
389
|
+
|
|
390
|
+
rows = []
|
|
391
|
+
for name, metadata, metrics in recordings_of_one_tool: # metrics = process_pipeline(...) of each file
|
|
392
|
+
rows += file_rows(ToolFile(name, metadata, metrics))
|
|
393
|
+
rows = regular_passes(rows, tool_id="0001C", config=cfg) # adds pass_number, is_regular_pass, exclusion_reason, ...
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
A pass is regular when it has a pass number, is not excluded by an `exclusions.cuts` rule, lasts at least half the
|
|
397
|
+
tool's median pass duration and is not the pass in which the tool broke. The result depends on the other files of
|
|
398
|
+
the tool, so all of them must be given.
|
|
399
|
+
|
|
400
|
+
### Generic Dynamic Exclusions in Python
|
|
401
|
+
|
|
402
|
+
Exclusion rules are completely schema-agnostic and evaluated before loading full acceleration arrays:
|
|
403
|
+
|
|
404
|
+
```python
|
|
405
|
+
import sth_analysis_tools as sth
|
|
406
|
+
|
|
407
|
+
# 1. Automatic exclusion using analyser_config.yaml defaults:
|
|
408
|
+
analyzer = sth.ToolAnalyzer()
|
|
409
|
+
|
|
410
|
+
# 2. Dynamic programmatic exclusion using a lambda predicate:
|
|
411
|
+
analyzer = sth.ToolAnalyzer(
|
|
412
|
+
exclude=lambda meta, path: meta.get("pre", {}).get("parameters", {}).get("tool_id") == "0005-C"
|
|
413
|
+
)
|
|
414
|
+
|
|
415
|
+
# 3. Dynamic exclusion using pure JSONPath expressions:
|
|
416
|
+
analyzer = sth.ToolAnalyzer(
|
|
417
|
+
exclude="$.pre.parameters.tool_id in ['IFT-001', 'PTW-001', 'PTW-002', '0005-C']"
|
|
418
|
+
)
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
### Cut-Level Exclusions (Aborted Passes & Outliers)
|
|
422
|
+
In addition to file-level exclusions, individual cutting passes (such as aborted entry touches or premature feed holds) can be excluded directly in `analyser_config.yaml` without deleting data:
|
|
423
|
+
|
|
424
|
+
```yaml
|
|
425
|
+
exclusions:
|
|
426
|
+
cuts:
|
|
427
|
+
- tool_id: "0001C"
|
|
428
|
+
cut_index: 65 # Global sequential cut index across tool lifecycle
|
|
429
|
+
reason: "Aborted entry pass (duration 6.1s vs 48.0s nominal)"
|
|
430
|
+
display: "greyed_out" # Options: "greyed_out" (default), "drop" or "not_cutting"
|
|
431
|
+
- file_pattern: "*2026-07-15_09-10-56*"
|
|
432
|
+
time_from_s: 2.0 # a detected segment whose midpoint lies in this window is not a cutting pass
|
|
433
|
+
time_to_s: 49.5
|
|
434
|
+
reason: "Spindle running without cutting (confirmed by the partner)"
|
|
435
|
+
display: "not_cutting"
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
- **`greyed_out`**: The active progression curve bridges across the valid cuts (e.g. Cut 64 to 66). Cut 65 is rendered with a distinct faded gray hollow marker ($\alpha=0.35$), annotated with an exclusion callout, and omitted from statistical tables.
|
|
439
|
+
- **`drop`**: The outlier cut is filtered out completely from visualization.
|
|
440
|
+
- **`not_cutting`**: The segmentation removes the detected segment of the matching file whose midpoint lies in
|
|
441
|
+
`[time_from_s, time_to_s]` before the dwells, anchors and pass numbers are formed: the time counts as a dwell.
|
|
442
|
+
|
|
443
|
+
---
|
|
444
|
+
|
|
445
|
+
## HDF5 Container Architecture & Memory Efficiency
|
|
446
|
+
|
|
447
|
+
`sth-analysis-tools` relies natively on the **Hierarchical Data Format version 5 (HDF5)** as a high-throughput, self-contained scientific container for machining telemetry.
|
|
448
|
+
|
|
449
|
+
### Internal Tree Hierarchy
|
|
450
|
+
|
|
451
|
+
```text
|
|
452
|
+
/ (Root Group)
|
|
453
|
+
├── acceleration # Raw sensor table (counter, timestamp, x) as recorded
|
|
454
|
+
├── acceleration_dynamic # a_proc: raw signal minus the PCHIP baseline (written by `process`)
|
|
455
|
+
├── baseline_trend # the PCHIP baseline B(t)
|
|
456
|
+
├── acceleration_sine_modulation # 1x component (NaN outside the valid parts of loss-free blocks)
|
|
457
|
+
├── acceleration_clean # a_proc minus the 1x component (NaN where it is undefined)
|
|
458
|
+
├── regime_mask # 0 other, 1 dwell, 2 pass (attrs: end_dwell_status, segmentation_fallback)
|
|
459
|
+
├── sensors/ # Synchronized auxiliary sensor channels
|
|
460
|
+
├── embedded_files/ # Binary/text payloads (NC code, tool calibration curves)
|
|
461
|
+
│ ├── nc_program.mpf
|
|
462
|
+
│ └── calibration_report.pdf
|
|
463
|
+
├── pre__flank_face # Pre-cut optical wear micrograph [RGB array]
|
|
464
|
+
└── post__rake_face # Post-cut optical wear micrograph [RGB array]
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
### JSON Attribute Serialization
|
|
468
|
+
Rather than enforcing rigid HDF5 compound datatypes, dataset-level metadata and post-normalization cut summaries are serialized as standard JSON strings directly in HDF5 group attributes:
|
|
469
|
+
- `attrs["metadata_json"]`: Tool geometry, machine kinematic parameters, workpiece material, and experimental context.
|
|
470
|
+
- `attrs["cut_metrics_table_json"]`: Pre-computed wear proxy summary table across all segmented passes.
|
|
471
|
+
|
|
472
|
+
This enables **instantaneous sub-millisecond querying**: `ToolAnalyzer` scans dozens of gigabytes of HDF5 files in fractions of a second by reading header attributes without mounting or decompressing heavy time-series arrays.
|
|
473
|
+
|
|
474
|
+
### Zero-Copy Partial Slicing
|
|
475
|
+
Because vibration channels are chunked along the time axis, arbitrary intervals can be lazily indexed:
|
|
476
|
+
```python
|
|
477
|
+
# Lazily inspect 2.0 seconds of cutting without loading the entire 500 MB file into RAM
|
|
478
|
+
with h5py.File("cirp_twm_1_TUWien.hdf5", "r") as f:
|
|
479
|
+
sample_slice = f["acceleration"][100000:120000] # Sub-millisecond zero-copy hyperslab read
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
---
|
|
483
|
+
|
|
484
|
+
## Compute-to-data algorithm (`algorithm/`)
|
|
485
|
+
|
|
486
|
+
`algorithm/` is the compute-to-data algorithm `sth_features` for Ocean / Pontus-X, built with
|
|
487
|
+
[pelago](https://pypi.org/project/pelago/). It runs this library on the recordings of a job (at most 10 per job on
|
|
488
|
+
the node) and returns, per file, an HDF5 with the derived signals, the regime mask, the pass metrics, the CIRP
|
|
489
|
+
metadata and `time_s`, plus `features.csv` (one row per pass, with the pass number in the tool life and
|
|
490
|
+
`is_regular_pass` when all files of a tool are in the job), `summary.json` and `report.pdf`. The library comes from
|
|
491
|
+
the image `ttrau/datascience-base`; the bundle holds only `main.py`, `export.py` and pelago.
|
|
492
|
+
|
|
493
|
+
| Parameter | Default | |
|
|
494
|
+
| --- | --- | --- |
|
|
495
|
+
| `config` | `cirp_paper_v9` | packaged settings, or `default` |
|
|
496
|
+
| `include_raw` | `false` | return the whole enriched file, raw signal and tool pictures included |
|
|
497
|
+
| `signals` | `all` | `all`, `none` or a comma list of `acceleration_dynamic`, `acceleration_clean`, `acceleration_sine_modulation`, `acceleration_dimensionless`, `baseline_trend` |
|
|
498
|
+
| `pdf` | `true` | write `report.pdf` |
|
|
499
|
+
|
|
500
|
+
`acceleration_dynamic + baseline_trend` gives back the raw signal. With `signals=none` only the regime mask, the
|
|
501
|
+
metrics and the metadata leave the node (about 80 kB per file instead of about 90 MB for a 640 s recording).
|
|
502
|
+
|
|
503
|
+
On the node the inputs are named after their URL: the CIRP file name is taken from the input name when it holds one
|
|
504
|
+
(Trident's named links) and rebuilt from the metadata otherwise (profile, institution, start time; a file named in a
|
|
505
|
+
configuration rule is recognised within 6 s). `summary.json` says which (`name_from`).
|
|
506
|
+
|
|
507
|
+
```bash
|
|
508
|
+
DATA=<folder with .hdf5 recordings> algorithm/build.sh # bundle, app definition, local run, container run
|
|
509
|
+
```
|
|
510
|
+
|
|
511
|
+
`build.sh` writes `algorithm/dist/sth_features.py` and `sth_features.dsapp.json` (upload both; Trident fills the
|
|
512
|
+
algorithm service from the definition). The algorithm version is set in `algorithm/pelago.toml`; the image there
|
|
513
|
+
must contain the library version the algorithm needs.
|
|
514
|
+
|
|
515
|
+
---
|
|
516
|
+
|
|
517
|
+
## Testing & Quality Assurance
|
|
518
|
+
|
|
519
|
+
Run the automated test suite with pytest:
|
|
520
|
+
|
|
521
|
+
```bash
|
|
522
|
+
# Run all unit and regression tests
|
|
523
|
+
pytest tests/ -v
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
Tests that need recordings of the dataset (in `clean_data/`, not in the repository) are skipped without them.
|
|
527
|
+
|
|
528
|
+
Code checks (`make check` runs all of them and the tests; tools pinned in the `dev` extras):
|
|
529
|
+
|
|
530
|
+
| Command | Tool | Checks |
|
|
531
|
+
| --- | --- | --- |
|
|
532
|
+
| `make lint` | Ruff | errors, import order, modern syntax, complexity (max 15; existing large functions carry `# noqa: C901`) |
|
|
533
|
+
| `make format` | Ruff | formats `src/ tests/ algorithm/ main.py` (`ruff format --check` in `make check`) |
|
|
534
|
+
| `make deadcode` | vulture | unused functions, classes, variables and imports (≥ 60 % confidence; false positives go into `vulture_whitelist.py`, findings of 2026-10-31 are in `vulture_baseline.py` to be worked down) |
|
|
535
|
+
| `make dupes` | jscpd (via `npx`, needs Node) | copy-paste; fails when duplication rises above the `threshold` in `.jscpd.json` |
|
|
536
|
+
|
|
537
|
+
Rules: `[tool.ruff]` and `[tool.vulture]` in `pyproject.toml`, `.jscpd.json`. The commit that only reformatted the
|
|
538
|
+
code is listed in `.git-blame-ignore-revs` (`git config blame.ignoreRevsFile .git-blame-ignore-revs`).
|
|
539
|
+
|
|
540
|
+
---
|
|
541
|
+
|
|
542
|
+
## Release
|
|
543
|
+
|
|
544
|
+
The version is set in one place: `__version__` in `src/sth_analysis_tools/__init__.py`.
|
|
545
|
+
|
|
546
|
+
1. Set `__version__`, add the entry to `CHANGELOG.md`, commit and push.
|
|
547
|
+
2. `make release`: stops if the version is already on PyPI, if there are uncommitted changes or a check fails;
|
|
548
|
+
otherwise builds and pushes the tag `v<version>`. The tag pipeline checks that the tag equals `__version__` and
|
|
549
|
+
uploads to PyPI with Trusted Publishing (no stored token; publisher configured on pypi.org for this GitLab
|
|
550
|
+
project, environment `pypi`).
|
|
551
|
+
3. Raise `sth-analysis-tools>=<version>` in `datascience-base-docker` and build a new image tag.
|
|
552
|
+
|
|
553
|
+
`make version` prints the current version.
|
|
554
|
+
|
|
555
|
+
---
|
|
556
|
+
|
|
557
|
+
## License
|
|
558
|
+
|
|
559
|
+
This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
|