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.
Files changed (84) hide show
  1. sth_analysis_tools-0.2.0/LICENSE +21 -0
  2. sth_analysis_tools-0.2.0/MANIFEST.in +19 -0
  3. sth_analysis_tools-0.2.0/PKG-INFO +559 -0
  4. sth_analysis_tools-0.2.0/README.md +519 -0
  5. sth_analysis_tools-0.2.0/analyser_config.yaml +185 -0
  6. sth_analysis_tools-0.2.0/dev_requirements.txt +5 -0
  7. sth_analysis_tools-0.2.0/pyproject.toml +113 -0
  8. sth_analysis_tools-0.2.0/requirements.txt +10 -0
  9. sth_analysis_tools-0.2.0/setup.cfg +4 -0
  10. sth_analysis_tools-0.2.0/src/sth_analysis_tools/__init__.py +176 -0
  11. sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/__init__.py +53 -0
  12. sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/aas_mapping.yaml +192 -0
  13. sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/adapter.py +175 -0
  14. sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/mapping_engine.py +168 -0
  15. sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/model.py +192 -0
  16. sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/registry.py +85 -0
  17. sth_analysis_tools-0.2.0/src/sth_analysis_tools/aas/serializer.py +87 -0
  18. sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/__init__.py +0 -0
  19. sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/analyzer.py +1114 -0
  20. sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/baseline_tracker.py +245 -0
  21. sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/dataset_group.py +337 -0
  22. sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/features.py +902 -0
  23. sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/normalizer.py +326 -0
  24. sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/pass_numbering.py +120 -0
  25. sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/peak_solver.py +286 -0
  26. sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/query_engine.py +245 -0
  27. sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/rolling_evaluator.py +487 -0
  28. sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/segmenter.py +604 -0
  29. sth_analysis_tools-0.2.0/src/sth_analysis_tools/analytics/tool_life.py +123 -0
  30. sth_analysis_tools-0.2.0/src/sth_analysis_tools/cli.py +1084 -0
  31. sth_analysis_tools-0.2.0/src/sth_analysis_tools/configs/cirp_paper_v9.yaml +101 -0
  32. sth_analysis_tools-0.2.0/src/sth_analysis_tools/core/__init__.py +33 -0
  33. sth_analysis_tools-0.2.0/src/sth_analysis_tools/core/config.py +823 -0
  34. sth_analysis_tools-0.2.0/src/sth_analysis_tools/core/exceptions.py +21 -0
  35. sth_analysis_tools-0.2.0/src/sth_analysis_tools/core/metadata_profile.py +233 -0
  36. sth_analysis_tools-0.2.0/src/sth_analysis_tools/core/metadata_schema.py +108 -0
  37. sth_analysis_tools-0.2.0/src/sth_analysis_tools/core/utils.py +115 -0
  38. sth_analysis_tools-0.2.0/src/sth_analysis_tools/dashboard/__init__.py +10 -0
  39. sth_analysis_tools-0.2.0/src/sth_analysis_tools/dashboard/app.py +1328 -0
  40. sth_analysis_tools-0.2.0/src/sth_analysis_tools/dashboard/components.py +1397 -0
  41. sth_analysis_tools-0.2.0/src/sth_analysis_tools/dashboard/data_service.py +644 -0
  42. sth_analysis_tools-0.2.0/src/sth_analysis_tools/io/__init__.py +0 -0
  43. sth_analysis_tools-0.2.0/src/sth_analysis_tools/io/dataset_handle.py +1063 -0
  44. sth_analysis_tools-0.2.0/src/sth_analysis_tools/io/loader.py +371 -0
  45. sth_analysis_tools-0.2.0/src/sth_analysis_tools/jupyter.py +80 -0
  46. sth_analysis_tools-0.2.0/src/sth_analysis_tools/visualization/__init__.py +49 -0
  47. sth_analysis_tools-0.2.0/src/sth_analysis_tools/visualization/interactive.py +641 -0
  48. sth_analysis_tools-0.2.0/src/sth_analysis_tools/visualization/reporter.py +568 -0
  49. sth_analysis_tools-0.2.0/src/sth_analysis_tools/visualization/visualizer.py +3326 -0
  50. sth_analysis_tools-0.2.0/src/sth_analysis_tools.egg-info/PKG-INFO +559 -0
  51. sth_analysis_tools-0.2.0/src/sth_analysis_tools.egg-info/SOURCES.txt +82 -0
  52. sth_analysis_tools-0.2.0/src/sth_analysis_tools.egg-info/dependency_links.txt +1 -0
  53. sth_analysis_tools-0.2.0/src/sth_analysis_tools.egg-info/entry_points.txt +3 -0
  54. sth_analysis_tools-0.2.0/src/sth_analysis_tools.egg-info/requires.txt +26 -0
  55. sth_analysis_tools-0.2.0/src/sth_analysis_tools.egg-info/top_level.txt +1 -0
  56. sth_analysis_tools-0.2.0/tests/__init__.py +1 -0
  57. sth_analysis_tools-0.2.0/tests/test_aas.py +383 -0
  58. sth_analysis_tools-0.2.0/tests/test_attachments_audit.py +67 -0
  59. sth_analysis_tools-0.2.0/tests/test_cli.py +82 -0
  60. sth_analysis_tools-0.2.0/tests/test_config_yaml_and_exclusions.py +196 -0
  61. sth_analysis_tools-0.2.0/tests/test_dashboard.py +207 -0
  62. sth_analysis_tools-0.2.0/tests/test_dashboard_usability.py +319 -0
  63. sth_analysis_tools-0.2.0/tests/test_dataset_group.py +81 -0
  64. sth_analysis_tools-0.2.0/tests/test_dependency_enforcement.py +76 -0
  65. sth_analysis_tools-0.2.0/tests/test_e2e_real_datasets.py +221 -0
  66. sth_analysis_tools-0.2.0/tests/test_features.py +149 -0
  67. sth_analysis_tools-0.2.0/tests/test_harmonics_visualizer.py +117 -0
  68. sth_analysis_tools-0.2.0/tests/test_interactive.py +112 -0
  69. sth_analysis_tools-0.2.0/tests/test_loader.py +64 -0
  70. sth_analysis_tools-0.2.0/tests/test_metadata_query.py +154 -0
  71. sth_analysis_tools-0.2.0/tests/test_normalizer.py +54 -0
  72. sth_analysis_tools-0.2.0/tests/test_numeric_accuracy_snapshots.py +113 -0
  73. sth_analysis_tools-0.2.0/tests/test_oo_library.py +96 -0
  74. sth_analysis_tools-0.2.0/tests/test_packet_and_trim.py +48 -0
  75. sth_analysis_tools-0.2.0/tests/test_pass_numbering.py +69 -0
  76. sth_analysis_tools-0.2.0/tests/test_query_engine.py +168 -0
  77. sth_analysis_tools-0.2.0/tests/test_rolling_evaluator.py +102 -0
  78. sth_analysis_tools-0.2.0/tests/test_segmentation_diagnostic.py +76 -0
  79. sth_analysis_tools-0.2.0/tests/test_segmentation_switches.py +153 -0
  80. sth_analysis_tools-0.2.0/tests/test_segmenter.py +45 -0
  81. sth_analysis_tools-0.2.0/tests/test_time_base_and_stage2.py +89 -0
  82. sth_analysis_tools-0.2.0/tests/test_tool_life.py +79 -0
  83. sth_analysis_tools-0.2.0/tests/test_wear_kpis_and_reporting.py +87 -0
  84. 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
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
44
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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.