flamingo-thz 0.1.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.
- flamingo_thz-0.1.0/LICENSE +22 -0
- flamingo_thz-0.1.0/PKG-INFO +292 -0
- flamingo_thz-0.1.0/README.md +266 -0
- flamingo_thz-0.1.0/pyproject.toml +39 -0
- flamingo_thz-0.1.0/setup.cfg +4 -0
- flamingo_thz-0.1.0/src/__init__.py +7 -0
- flamingo_thz-0.1.0/src/flamingo/__init__.py +7 -0
- flamingo_thz-0.1.0/src/flamingo/algorithms/__init__.py +15 -0
- flamingo_thz-0.1.0/src/flamingo/algorithms/correction_methods.py +104 -0
- flamingo_thz-0.1.0/src/flamingo/algorithms/error_fit_functions.py +211 -0
- flamingo_thz-0.1.0/src/flamingo/cli.py +65 -0
- flamingo_thz-0.1.0/src/flamingo/core/__init__.py +4 -0
- flamingo_thz-0.1.0/src/flamingo/core/optimization_parameter.py +157 -0
- flamingo_thz-0.1.0/src/flamingo/core/processing_pipeline.py +426 -0
- flamingo_thz-0.1.0/src/flamingo/gui/__init__.py +1 -0
- flamingo_thz-0.1.0/src/flamingo/gui/components.py +634 -0
- flamingo_thz-0.1.0/src/flamingo/gui.py +365 -0
- flamingo_thz-0.1.0/src/flamingo/main.py +46 -0
- flamingo_thz-0.1.0/src/flamingo/utils/__init__.py +20 -0
- flamingo_thz-0.1.0/src/flamingo/utils/config.py +65 -0
- flamingo_thz-0.1.0/src/flamingo/utils/helper_functions.py +127 -0
- flamingo_thz-0.1.0/src/flamingo/utils/log_capture.py +136 -0
- flamingo_thz-0.1.0/src/flamingo/utils/progress.py +129 -0
- flamingo_thz-0.1.0/src/flamingo/visualization/__init__.py +7 -0
- flamingo_thz-0.1.0/src/flamingo/visualization/plot_data.py +281 -0
- flamingo_thz-0.1.0/src/flamingo_thz.egg-info/PKG-INFO +292 -0
- flamingo_thz-0.1.0/src/flamingo_thz.egg-info/SOURCES.txt +29 -0
- flamingo_thz-0.1.0/src/flamingo_thz.egg-info/dependency_links.txt +1 -0
- flamingo_thz-0.1.0/src/flamingo_thz.egg-info/entry_points.txt +3 -0
- flamingo_thz-0.1.0/src/flamingo_thz.egg-info/requires.txt +7 -0
- flamingo_thz-0.1.0/src/flamingo_thz.egg-info/top_level.txt +2 -0
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 PERETTI Romain
|
|
4
|
+
Copyright (c) 2025 Tim Vogel
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE.
|
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: flamingo-thz
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Data Correction Tool for THz Time Domain Spectroscopy
|
|
5
|
+
Author-email: Tim Vogel <32876663+TimVog@users.noreply.github.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/TimVog/flamingo
|
|
8
|
+
Project-URL: Repository, https://github.com/TimVog/flamingo
|
|
9
|
+
Classifier: Programming Language :: Python
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Requires-Python: >=3.9
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
License-File: LICENSE
|
|
18
|
+
Requires-Dist: numpy
|
|
19
|
+
Requires-Dist: scipy
|
|
20
|
+
Requires-Dist: matplotlib
|
|
21
|
+
Requires-Dist: h5py
|
|
22
|
+
Requires-Dist: tqdm
|
|
23
|
+
Requires-Dist: colorama
|
|
24
|
+
Requires-Dist: customtkinter>=5.1.2
|
|
25
|
+
Dynamic: license-file
|
|
26
|
+
|
|
27
|
+
# flamingo
|
|
28
|
+
|
|
29
|
+
**flamingo** stands for **F**lexible **L**ibrary for **A**mplitude and **M**otion **I**naccuracies **N**eatly **G**one **O**ut :flamingo:
|
|
30
|
+
|
|
31
|
+
and is a THz data analysis tool which corrects subtle time distortion errors in Terahertz time-domain spectroscopy (THz-TDS) measurements.
|
|
32
|
+
|
|
33
|
+
## Origin and Motivation
|
|
34
|
+
|
|
35
|
+
This project is a fork of [Correct-TDS](https://github.com/THzbiophotonics/Correct-TDS) from the group of [Romain Peretti](https://www.tuscany-erc.fr/). While the original implementation provided valuable algorithms, flamingo reimplements these with several key improvements:
|
|
36
|
+
|
|
37
|
+
1. **Lightweight design** - Built using minimal dependencies (numpy, scipy, matplotlib) for easier installation and maintenance
|
|
38
|
+
2. **Memory efficiency** - Processing one trace at a time, allowing even large datasets (10,000+ traces) to be analyzed on modest hardware
|
|
39
|
+
3. **Modern GUI** - Using CustomTkinter instead of PyQT for a lighter-weight graphical user interface
|
|
40
|
+
4. **Cross-platform compatibility** - Designed to work seamlessly across operating systems with minimal setup
|
|
41
|
+
|
|
42
|
+
The scientific foundation remains the excellent work described in:
|
|
43
|
+
|
|
44
|
+
> E. Denakpo, T. Hannotte, N. Osseiran, F. Orieux and R. Peretti,
|
|
45
|
+
>
|
|
46
|
+
> "Signal Estimation and Uncertainties Extraction in Terahertz Time-Domain Spectroscopy,"
|
|
47
|
+
>
|
|
48
|
+
> in *IEEE Transactions on Instrumentation and Measurement, vol. 74, pp. 1-13, 2025, Art no. 6005413,*
|
|
49
|
+
>
|
|
50
|
+
> doi: [10.1109/TIM.2025.3554287]()
|
|
51
|
+
|
|
52
|
+
## What does flamingo do?
|
|
53
|
+
|
|
54
|
+
flamingo analyzes THz-TDS data and corrects systematic errors that affect measurement precision. It specifically targets data from commercial THz-TDS systems like [Menlo](https://www.menlosystems.com/products/thz-time-domain-solutions/terak15-terahertz-spectrometer/) and [Toptica](https://www.toptica.com/products/terahertz-systems/time-domain), providing tools to reduce the standard deviation across multiple measurements.
|
|
55
|
+
|
|
56
|
+
The software features:
|
|
57
|
+
|
|
58
|
+
- **Small footprint** - Minimal dependencies and optimized code for simpler installation and deployment
|
|
59
|
+
- **Efficient processing** - Single-trace processing approach that preserves memory even with very large datasets
|
|
60
|
+
- **Multiple interfaces** - Python API, command-line tool, and graphical user interface to suit different workflows
|
|
61
|
+
- **Standalone executable** - Available as an .exe file for users without Python programming experience
|
|
62
|
+
|
|
63
|
+
## Overview
|
|
64
|
+
|
|
65
|
+
flamingo is a comprehensive toolset for analyzing and correcting THz time-domain spectroscopy (THz-TDS) data. It features:
|
|
66
|
+
|
|
67
|
+
- Efficient processing of raw THz data from HDF-5 (.h5) files
|
|
68
|
+
- Memory-optimized algorithms that read one trace at a time, enabling processing of large datasets even on low-spec hardware
|
|
69
|
+
- Flexible correction methods for systematic errors in THz-TDS measurements:
|
|
70
|
+
- Delay correction
|
|
71
|
+
- Dilatation correction
|
|
72
|
+
- Periodic error correction ("Ghost" spectrum suppression)
|
|
73
|
+
- Interactive visualization tools for both time-domain and frequency-domain data
|
|
74
|
+
- Multiple interfaces: Python API, command-line, and graphical user interface
|
|
75
|
+
|
|
76
|
+
## Installation
|
|
77
|
+
|
|
78
|
+
### Executable Version
|
|
79
|
+
|
|
80
|
+
For users without a Python background, a standalone executable version is available:
|
|
81
|
+
## Download
|
|
82
|
+
- [Latest Release](https://github.com/TimVog/flamingo/releases/latest) - View release notes and all available files
|
|
83
|
+
- [Windows Executable](https://github.com/TimVog/flamingo/releases/latest/download/flamingo-v0.1.0-win64.zip) - Direct download for Windows users
|
|
84
|
+
|
|
85
|
+
This allows you to run the application without installing Python or any dependencies.
|
|
86
|
+
|
|
87
|
+
1. Unpack the `.zip`-file
|
|
88
|
+
2. Double-click `flamingo.exe` to launch the application
|
|
89
|
+
3. Use the graphical interface to process your THz-TDS data
|
|
90
|
+
|
|
91
|
+
**Note:** Please scroll down to Usage/Example data to see how you can make your first steps with flamingo.
|
|
92
|
+
|
|
93
|
+

|
|
94
|
+
|
|
95
|
+
### Using pip
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
# Install from PyPI
|
|
99
|
+
pip install flamingo-thz
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### From source
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
# Clone the repository
|
|
106
|
+
git clone https://github.com/TimVog/flamingo.git
|
|
107
|
+
cd flamingo
|
|
108
|
+
|
|
109
|
+
# Install in development mode
|
|
110
|
+
pip install -e .
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
## Project Structure
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
flamingo/
|
|
118
|
+
├── README.md
|
|
119
|
+
├── flamingo.spec # PyInstaller specification for executable
|
|
120
|
+
├── pyproject.toml # Package configuration
|
|
121
|
+
└── src/ # Source code
|
|
122
|
+
└── flamingo/ # Main package
|
|
123
|
+
├── __init__.py
|
|
124
|
+
├── cli.py # Command-line interface
|
|
125
|
+
├── gui.py # Graphical user interface
|
|
126
|
+
├── main.py # Main API entry points
|
|
127
|
+
├── algorithms/ # Error correction algorithms
|
|
128
|
+
│ ├── __init__.py
|
|
129
|
+
│ ├── correction_methods.py
|
|
130
|
+
│ └── error_fit_functions.py
|
|
131
|
+
├── core/ # Core processing functionality
|
|
132
|
+
│ ├── __init__.py
|
|
133
|
+
│ ├── optimization_parameter.py
|
|
134
|
+
│ └── processing_pipeline.py
|
|
135
|
+
├── gui/ # GUI components
|
|
136
|
+
│ ├── __init__.py
|
|
137
|
+
│ └── components.py
|
|
138
|
+
├── utils/ # Utility functions
|
|
139
|
+
│ ├── __init__.py
|
|
140
|
+
│ ├── config.py
|
|
141
|
+
│ ├── helper_functions.py
|
|
142
|
+
│ ├── log_capture.py
|
|
143
|
+
│ └── progress.py
|
|
144
|
+
└── visualization/ # Plotting tools
|
|
145
|
+
├── __init__.py
|
|
146
|
+
└── plot_data.py
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## Usage
|
|
150
|
+
|
|
151
|
+
Flamingo provides three different interfaces for flexibility:
|
|
152
|
+
|
|
153
|
+
### Graphical User Interface
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
# Launch the GUI
|
|
157
|
+
flamingo-gui
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+

|
|
161
|
+
|
|
162
|
+

|
|
163
|
+
|
|
164
|
+
The GUI provides an intuitive interface with:
|
|
165
|
+
- File selection
|
|
166
|
+
- Processing parameter configuration
|
|
167
|
+
- Interactive visualizations
|
|
168
|
+
- Optimization parameter adjustment
|
|
169
|
+
- Export functionality for corrected data
|
|
170
|
+
|
|
171
|
+
### Python API
|
|
172
|
+
|
|
173
|
+
```python
|
|
174
|
+
from flamingo import process_data
|
|
175
|
+
|
|
176
|
+
# Process data with custom parameters
|
|
177
|
+
data, correction_params, trace_time, freq = process_data(
|
|
178
|
+
filepath='path/to/your/data.h5',
|
|
179
|
+
trace_start=0,
|
|
180
|
+
trace_end=1000,
|
|
181
|
+
lowcut=0.2e12, # Low cut frequency in Hz
|
|
182
|
+
config_options={
|
|
183
|
+
"enable_dilatation": True,
|
|
184
|
+
"enable_periodic": True
|
|
185
|
+
}
|
|
186
|
+
)
|
|
187
|
+
|
|
188
|
+
# For more advanced usage with full access to the processing pipeline:
|
|
189
|
+
from flamingo import ProcessingPipeline
|
|
190
|
+
from flamingo.core.optimization_parameter import CorrectionConfig
|
|
191
|
+
|
|
192
|
+
# Create configuration with custom settings
|
|
193
|
+
config = CorrectionConfig()
|
|
194
|
+
config.enabled_corrections["dilatation"] = True
|
|
195
|
+
config.enabled_corrections["periodic"] = True
|
|
196
|
+
|
|
197
|
+
# Create processing pipeline
|
|
198
|
+
pipeline = ProcessingPipeline(config)
|
|
199
|
+
|
|
200
|
+
# Process file
|
|
201
|
+
result = pipeline.process_file(
|
|
202
|
+
filepath='path/to/your/data.h5',
|
|
203
|
+
trace_start=0,
|
|
204
|
+
trace_end=1000,
|
|
205
|
+
lowcut=0.2e12
|
|
206
|
+
)
|
|
207
|
+
|
|
208
|
+
# Export corrected data to a new file
|
|
209
|
+
pipeline.export_corrected_data(
|
|
210
|
+
'path/to/your/data.h5',
|
|
211
|
+
'path/to/output/corrected_data.h5',
|
|
212
|
+
trace_start=0,
|
|
213
|
+
trace_end=1000
|
|
214
|
+
)
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Command-Line Interface
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
# Basic usage
|
|
221
|
+
flamingo --input data.h5 --output results/ --start 0 --end 1000 --lowcut 0.2e12
|
|
222
|
+
|
|
223
|
+
# Disable specific corrections
|
|
224
|
+
flamingo --input data.h5 --no-dilatation --no-periodic
|
|
225
|
+
|
|
226
|
+
# Export corrected data
|
|
227
|
+
flamingo --input data.h5 --export corrected_data.h5
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
|
|
231
|
+
## Data Format
|
|
232
|
+
|
|
233
|
+
Flamingo expects H5 files containing THz time-domain spectroscopy data with the following structure:
|
|
234
|
+
- Time trace axis stored as `timeaxis`
|
|
235
|
+
- Multiple amplitude time traces stored as numeric keys ("0", "1", "2", ...)
|
|
236
|
+
- All traces must have the same number of samples and be based on the same time axis
|
|
237
|
+
|
|
238
|
+
### Example Data
|
|
239
|
+
|
|
240
|
+
If you'd like to try flamingo but don't have suitable THz-TDS data available, you can download an example file:
|
|
241
|
+
|
|
242
|
+
1. Get the file `04-12-2023_0mb_50k_100ps.h5` from [this research data repository](https://entrepot.recherche.data.gouv.fr/dataset.xhtml?persistentId=doi:10.57745/Y35DYN)
|
|
243
|
+
2. This file is already in the correct format for flamingo
|
|
244
|
+
|
|
245
|
+
**Note**: This example file contains 50 000 traces, which is a large dataset. For an initial exploration of the software's capabilities, try setting the "End trace" parameter to 1 000 in the GUI or via the command line. This is typically sufficient to get a good feel for the software while keeping processing times reasonable.
|
|
246
|
+
|
|
247
|
+
## Correction Methods
|
|
248
|
+
|
|
249
|
+
Flamingo implements several correction methods to improve the quality of THz-TDS data:
|
|
250
|
+
|
|
251
|
+
1. **Delay Correction**: Compensates for time shifts between traces
|
|
252
|
+
2. **Dilatation Correction**: Corrects for stretching/compression effects in the time domain
|
|
253
|
+
3. **Residual Noise Correction**: Reduces amplitude variations
|
|
254
|
+
4. **Periodic Error Correction**: Suppresses "Ghost" spectra caused by periodic sampling errors
|
|
255
|
+
|
|
256
|
+
## Visualization
|
|
257
|
+
|
|
258
|
+
The package includes comprehensive visualization tools:
|
|
259
|
+
- Time-domain signal plots
|
|
260
|
+
- Frequency-domain spectrum plots
|
|
261
|
+
- Correction parameter visualization
|
|
262
|
+
- Before/after comparison plots
|
|
263
|
+
|
|
264
|
+
```python
|
|
265
|
+
from flamingo.visualization import plot_data
|
|
266
|
+
|
|
267
|
+
# Generate plots of processed data
|
|
268
|
+
plot_data.visualize_processing_steps(data, trace_time, freq)
|
|
269
|
+
plot_data.plot_comparison(data, trace_time, freq)
|
|
270
|
+
plot_data.plot_correction_parameter(correction_params)
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
## How does this software compare to the other THz-TDS packages like [parrot](https://github.com/puls-lab/parrot) and [phoeniks](https://github.com/puls-lab/phoeniks)?
|
|
274
|
+
|
|
275
|
+
- **parrot** :parrot: is a fully-fledged solution for continuously recorded THz data with two raw streams (position and THz signal). It takes care of cutting, correcting the phase shift between these two streams, interpolation and so on. The presented algorithms are also going into parrot to keep it as a complete package.
|
|
276
|
+
- **phoeniks** :bird: is at the end of the processing chain, if one is interested in the complex refractive index. It uses already averaged data as an input and needs a sample and reference trace.
|
|
277
|
+
- **flamingo** :flamingo: is more specialized, using already interpolated traces like they can be recorded with commercial THz-TDS. By correcting subtle errors, which can be detected having an ensemble of traces, the standard deviation of the dataset can be reduced, improving phase accuracy, which is a pre-requisite for accurate extraction of the complex refractive index.
|
|
278
|
+
|
|
279
|
+
## Contributing
|
|
280
|
+
|
|
281
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
282
|
+
|
|
283
|
+
## Credits
|
|
284
|
+
|
|
285
|
+
- Original [Correct-TDS](https://github.com/THzbiophotonics/Correct-TDS) implementation by [Romain Peretti's group](https://www.tuscany-erc.fr/)
|
|
286
|
+
- Algorithms based on the paper by E. Denakpo et al. (2025)
|
|
287
|
+
- Package development by Tim Vogel
|
|
288
|
+
- GUI development and object-oriented architecture support by Claude 3.7 Sonnet, which provided assistance in restructuring the codebase from linear scripts to a modular, object-oriented package with a modern graphical interface
|
|
289
|
+
|
|
290
|
+
## License
|
|
291
|
+
|
|
292
|
+
This project is licensed under the MIT License - see the LICENSE file for details.
|
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
# flamingo
|
|
2
|
+
|
|
3
|
+
**flamingo** stands for **F**lexible **L**ibrary for **A**mplitude and **M**otion **I**naccuracies **N**eatly **G**one **O**ut :flamingo:
|
|
4
|
+
|
|
5
|
+
and is a THz data analysis tool which corrects subtle time distortion errors in Terahertz time-domain spectroscopy (THz-TDS) measurements.
|
|
6
|
+
|
|
7
|
+
## Origin and Motivation
|
|
8
|
+
|
|
9
|
+
This project is a fork of [Correct-TDS](https://github.com/THzbiophotonics/Correct-TDS) from the group of [Romain Peretti](https://www.tuscany-erc.fr/). While the original implementation provided valuable algorithms, flamingo reimplements these with several key improvements:
|
|
10
|
+
|
|
11
|
+
1. **Lightweight design** - Built using minimal dependencies (numpy, scipy, matplotlib) for easier installation and maintenance
|
|
12
|
+
2. **Memory efficiency** - Processing one trace at a time, allowing even large datasets (10,000+ traces) to be analyzed on modest hardware
|
|
13
|
+
3. **Modern GUI** - Using CustomTkinter instead of PyQT for a lighter-weight graphical user interface
|
|
14
|
+
4. **Cross-platform compatibility** - Designed to work seamlessly across operating systems with minimal setup
|
|
15
|
+
|
|
16
|
+
The scientific foundation remains the excellent work described in:
|
|
17
|
+
|
|
18
|
+
> E. Denakpo, T. Hannotte, N. Osseiran, F. Orieux and R. Peretti,
|
|
19
|
+
>
|
|
20
|
+
> "Signal Estimation and Uncertainties Extraction in Terahertz Time-Domain Spectroscopy,"
|
|
21
|
+
>
|
|
22
|
+
> in *IEEE Transactions on Instrumentation and Measurement, vol. 74, pp. 1-13, 2025, Art no. 6005413,*
|
|
23
|
+
>
|
|
24
|
+
> doi: [10.1109/TIM.2025.3554287]()
|
|
25
|
+
|
|
26
|
+
## What does flamingo do?
|
|
27
|
+
|
|
28
|
+
flamingo analyzes THz-TDS data and corrects systematic errors that affect measurement precision. It specifically targets data from commercial THz-TDS systems like [Menlo](https://www.menlosystems.com/products/thz-time-domain-solutions/terak15-terahertz-spectrometer/) and [Toptica](https://www.toptica.com/products/terahertz-systems/time-domain), providing tools to reduce the standard deviation across multiple measurements.
|
|
29
|
+
|
|
30
|
+
The software features:
|
|
31
|
+
|
|
32
|
+
- **Small footprint** - Minimal dependencies and optimized code for simpler installation and deployment
|
|
33
|
+
- **Efficient processing** - Single-trace processing approach that preserves memory even with very large datasets
|
|
34
|
+
- **Multiple interfaces** - Python API, command-line tool, and graphical user interface to suit different workflows
|
|
35
|
+
- **Standalone executable** - Available as an .exe file for users without Python programming experience
|
|
36
|
+
|
|
37
|
+
## Overview
|
|
38
|
+
|
|
39
|
+
flamingo is a comprehensive toolset for analyzing and correcting THz time-domain spectroscopy (THz-TDS) data. It features:
|
|
40
|
+
|
|
41
|
+
- Efficient processing of raw THz data from HDF-5 (.h5) files
|
|
42
|
+
- Memory-optimized algorithms that read one trace at a time, enabling processing of large datasets even on low-spec hardware
|
|
43
|
+
- Flexible correction methods for systematic errors in THz-TDS measurements:
|
|
44
|
+
- Delay correction
|
|
45
|
+
- Dilatation correction
|
|
46
|
+
- Periodic error correction ("Ghost" spectrum suppression)
|
|
47
|
+
- Interactive visualization tools for both time-domain and frequency-domain data
|
|
48
|
+
- Multiple interfaces: Python API, command-line, and graphical user interface
|
|
49
|
+
|
|
50
|
+
## Installation
|
|
51
|
+
|
|
52
|
+
### Executable Version
|
|
53
|
+
|
|
54
|
+
For users without a Python background, a standalone executable version is available:
|
|
55
|
+
## Download
|
|
56
|
+
- [Latest Release](https://github.com/TimVog/flamingo/releases/latest) - View release notes and all available files
|
|
57
|
+
- [Windows Executable](https://github.com/TimVog/flamingo/releases/latest/download/flamingo-v0.1.0-win64.zip) - Direct download for Windows users
|
|
58
|
+
|
|
59
|
+
This allows you to run the application without installing Python or any dependencies.
|
|
60
|
+
|
|
61
|
+
1. Unpack the `.zip`-file
|
|
62
|
+
2. Double-click `flamingo.exe` to launch the application
|
|
63
|
+
3. Use the graphical interface to process your THz-TDS data
|
|
64
|
+
|
|
65
|
+
**Note:** Please scroll down to Usage/Example data to see how you can make your first steps with flamingo.
|
|
66
|
+
|
|
67
|
+

|
|
68
|
+
|
|
69
|
+
### Using pip
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
# Install from PyPI
|
|
73
|
+
pip install flamingo-thz
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### From source
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
# Clone the repository
|
|
80
|
+
git clone https://github.com/TimVog/flamingo.git
|
|
81
|
+
cd flamingo
|
|
82
|
+
|
|
83
|
+
# Install in development mode
|
|
84
|
+
pip install -e .
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
## Project Structure
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
flamingo/
|
|
92
|
+
├── README.md
|
|
93
|
+
├── flamingo.spec # PyInstaller specification for executable
|
|
94
|
+
├── pyproject.toml # Package configuration
|
|
95
|
+
└── src/ # Source code
|
|
96
|
+
└── flamingo/ # Main package
|
|
97
|
+
├── __init__.py
|
|
98
|
+
├── cli.py # Command-line interface
|
|
99
|
+
├── gui.py # Graphical user interface
|
|
100
|
+
├── main.py # Main API entry points
|
|
101
|
+
├── algorithms/ # Error correction algorithms
|
|
102
|
+
│ ├── __init__.py
|
|
103
|
+
│ ├── correction_methods.py
|
|
104
|
+
│ └── error_fit_functions.py
|
|
105
|
+
├── core/ # Core processing functionality
|
|
106
|
+
│ ├── __init__.py
|
|
107
|
+
│ ├── optimization_parameter.py
|
|
108
|
+
│ └── processing_pipeline.py
|
|
109
|
+
├── gui/ # GUI components
|
|
110
|
+
│ ├── __init__.py
|
|
111
|
+
│ └── components.py
|
|
112
|
+
├── utils/ # Utility functions
|
|
113
|
+
│ ├── __init__.py
|
|
114
|
+
│ ├── config.py
|
|
115
|
+
│ ├── helper_functions.py
|
|
116
|
+
│ ├── log_capture.py
|
|
117
|
+
│ └── progress.py
|
|
118
|
+
└── visualization/ # Plotting tools
|
|
119
|
+
├── __init__.py
|
|
120
|
+
└── plot_data.py
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## Usage
|
|
124
|
+
|
|
125
|
+
Flamingo provides three different interfaces for flexibility:
|
|
126
|
+
|
|
127
|
+
### Graphical User Interface
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
# Launch the GUI
|
|
131
|
+
flamingo-gui
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+

|
|
135
|
+
|
|
136
|
+

|
|
137
|
+
|
|
138
|
+
The GUI provides an intuitive interface with:
|
|
139
|
+
- File selection
|
|
140
|
+
- Processing parameter configuration
|
|
141
|
+
- Interactive visualizations
|
|
142
|
+
- Optimization parameter adjustment
|
|
143
|
+
- Export functionality for corrected data
|
|
144
|
+
|
|
145
|
+
### Python API
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
from flamingo import process_data
|
|
149
|
+
|
|
150
|
+
# Process data with custom parameters
|
|
151
|
+
data, correction_params, trace_time, freq = process_data(
|
|
152
|
+
filepath='path/to/your/data.h5',
|
|
153
|
+
trace_start=0,
|
|
154
|
+
trace_end=1000,
|
|
155
|
+
lowcut=0.2e12, # Low cut frequency in Hz
|
|
156
|
+
config_options={
|
|
157
|
+
"enable_dilatation": True,
|
|
158
|
+
"enable_periodic": True
|
|
159
|
+
}
|
|
160
|
+
)
|
|
161
|
+
|
|
162
|
+
# For more advanced usage with full access to the processing pipeline:
|
|
163
|
+
from flamingo import ProcessingPipeline
|
|
164
|
+
from flamingo.core.optimization_parameter import CorrectionConfig
|
|
165
|
+
|
|
166
|
+
# Create configuration with custom settings
|
|
167
|
+
config = CorrectionConfig()
|
|
168
|
+
config.enabled_corrections["dilatation"] = True
|
|
169
|
+
config.enabled_corrections["periodic"] = True
|
|
170
|
+
|
|
171
|
+
# Create processing pipeline
|
|
172
|
+
pipeline = ProcessingPipeline(config)
|
|
173
|
+
|
|
174
|
+
# Process file
|
|
175
|
+
result = pipeline.process_file(
|
|
176
|
+
filepath='path/to/your/data.h5',
|
|
177
|
+
trace_start=0,
|
|
178
|
+
trace_end=1000,
|
|
179
|
+
lowcut=0.2e12
|
|
180
|
+
)
|
|
181
|
+
|
|
182
|
+
# Export corrected data to a new file
|
|
183
|
+
pipeline.export_corrected_data(
|
|
184
|
+
'path/to/your/data.h5',
|
|
185
|
+
'path/to/output/corrected_data.h5',
|
|
186
|
+
trace_start=0,
|
|
187
|
+
trace_end=1000
|
|
188
|
+
)
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Command-Line Interface
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
# Basic usage
|
|
195
|
+
flamingo --input data.h5 --output results/ --start 0 --end 1000 --lowcut 0.2e12
|
|
196
|
+
|
|
197
|
+
# Disable specific corrections
|
|
198
|
+
flamingo --input data.h5 --no-dilatation --no-periodic
|
|
199
|
+
|
|
200
|
+
# Export corrected data
|
|
201
|
+
flamingo --input data.h5 --export corrected_data.h5
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
## Data Format
|
|
206
|
+
|
|
207
|
+
Flamingo expects H5 files containing THz time-domain spectroscopy data with the following structure:
|
|
208
|
+
- Time trace axis stored as `timeaxis`
|
|
209
|
+
- Multiple amplitude time traces stored as numeric keys ("0", "1", "2", ...)
|
|
210
|
+
- All traces must have the same number of samples and be based on the same time axis
|
|
211
|
+
|
|
212
|
+
### Example Data
|
|
213
|
+
|
|
214
|
+
If you'd like to try flamingo but don't have suitable THz-TDS data available, you can download an example file:
|
|
215
|
+
|
|
216
|
+
1. Get the file `04-12-2023_0mb_50k_100ps.h5` from [this research data repository](https://entrepot.recherche.data.gouv.fr/dataset.xhtml?persistentId=doi:10.57745/Y35DYN)
|
|
217
|
+
2. This file is already in the correct format for flamingo
|
|
218
|
+
|
|
219
|
+
**Note**: This example file contains 50 000 traces, which is a large dataset. For an initial exploration of the software's capabilities, try setting the "End trace" parameter to 1 000 in the GUI or via the command line. This is typically sufficient to get a good feel for the software while keeping processing times reasonable.
|
|
220
|
+
|
|
221
|
+
## Correction Methods
|
|
222
|
+
|
|
223
|
+
Flamingo implements several correction methods to improve the quality of THz-TDS data:
|
|
224
|
+
|
|
225
|
+
1. **Delay Correction**: Compensates for time shifts between traces
|
|
226
|
+
2. **Dilatation Correction**: Corrects for stretching/compression effects in the time domain
|
|
227
|
+
3. **Residual Noise Correction**: Reduces amplitude variations
|
|
228
|
+
4. **Periodic Error Correction**: Suppresses "Ghost" spectra caused by periodic sampling errors
|
|
229
|
+
|
|
230
|
+
## Visualization
|
|
231
|
+
|
|
232
|
+
The package includes comprehensive visualization tools:
|
|
233
|
+
- Time-domain signal plots
|
|
234
|
+
- Frequency-domain spectrum plots
|
|
235
|
+
- Correction parameter visualization
|
|
236
|
+
- Before/after comparison plots
|
|
237
|
+
|
|
238
|
+
```python
|
|
239
|
+
from flamingo.visualization import plot_data
|
|
240
|
+
|
|
241
|
+
# Generate plots of processed data
|
|
242
|
+
plot_data.visualize_processing_steps(data, trace_time, freq)
|
|
243
|
+
plot_data.plot_comparison(data, trace_time, freq)
|
|
244
|
+
plot_data.plot_correction_parameter(correction_params)
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
## How does this software compare to the other THz-TDS packages like [parrot](https://github.com/puls-lab/parrot) and [phoeniks](https://github.com/puls-lab/phoeniks)?
|
|
248
|
+
|
|
249
|
+
- **parrot** :parrot: is a fully-fledged solution for continuously recorded THz data with two raw streams (position and THz signal). It takes care of cutting, correcting the phase shift between these two streams, interpolation and so on. The presented algorithms are also going into parrot to keep it as a complete package.
|
|
250
|
+
- **phoeniks** :bird: is at the end of the processing chain, if one is interested in the complex refractive index. It uses already averaged data as an input and needs a sample and reference trace.
|
|
251
|
+
- **flamingo** :flamingo: is more specialized, using already interpolated traces like they can be recorded with commercial THz-TDS. By correcting subtle errors, which can be detected having an ensemble of traces, the standard deviation of the dataset can be reduced, improving phase accuracy, which is a pre-requisite for accurate extraction of the complex refractive index.
|
|
252
|
+
|
|
253
|
+
## Contributing
|
|
254
|
+
|
|
255
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
256
|
+
|
|
257
|
+
## Credits
|
|
258
|
+
|
|
259
|
+
- Original [Correct-TDS](https://github.com/THzbiophotonics/Correct-TDS) implementation by [Romain Peretti's group](https://www.tuscany-erc.fr/)
|
|
260
|
+
- Algorithms based on the paper by E. Denakpo et al. (2025)
|
|
261
|
+
- Package development by Tim Vogel
|
|
262
|
+
- GUI development and object-oriented architecture support by Claude 3.7 Sonnet, which provided assistance in restructuring the codebase from linear scripts to a modular, object-oriented package with a modern graphical interface
|
|
263
|
+
|
|
264
|
+
## License
|
|
265
|
+
|
|
266
|
+
This project is licensed under the MIT License - see the LICENSE file for details.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=42", "wheel", "build"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "flamingo-thz"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Data Correction Tool for THz Time Domain Spectroscopy"
|
|
9
|
+
authors = [
|
|
10
|
+
{ name = "Tim Vogel", email = "32876663+TimVog@users.noreply.github.com" },
|
|
11
|
+
]
|
|
12
|
+
classifiers = [
|
|
13
|
+
"Programming Language :: Python",
|
|
14
|
+
"Programming Language :: Python :: 3.9",
|
|
15
|
+
"Programming Language :: Python :: 3.10",
|
|
16
|
+
"Programming Language :: Python :: 3.11",
|
|
17
|
+
"Programming Language :: Python :: 3.12",
|
|
18
|
+
"Operating System :: OS Independent"
|
|
19
|
+
]
|
|
20
|
+
readme = {file = "README.md", content-type = "text/markdown"}
|
|
21
|
+
requires-python = ">=3.9"
|
|
22
|
+
license = "MIT"
|
|
23
|
+
dependencies = [
|
|
24
|
+
"numpy",
|
|
25
|
+
"scipy",
|
|
26
|
+
"matplotlib",
|
|
27
|
+
"h5py",
|
|
28
|
+
"tqdm",
|
|
29
|
+
"colorama",
|
|
30
|
+
"customtkinter>=5.1.2",
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
[project.urls]
|
|
34
|
+
Homepage = "https://github.com/TimVog/flamingo"
|
|
35
|
+
Repository = "https://github.com/TimVog/flamingo"
|
|
36
|
+
|
|
37
|
+
[project.scripts]
|
|
38
|
+
flamingo = "flamingo.main:main"
|
|
39
|
+
flamingo-gui = "flamingo.gui:main"
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
"""Algorithm implementations for THz data correction."""
|
|
2
|
+
|
|
3
|
+
from flamingo.algorithms.correction_methods import (
|
|
4
|
+
apply_delay_correction,
|
|
5
|
+
apply_dilatation_correction,
|
|
6
|
+
apply_amplitude_correction,
|
|
7
|
+
apply_periodic_correction,
|
|
8
|
+
apply_delay_dilatation_correction
|
|
9
|
+
)
|
|
10
|
+
|
|
11
|
+
from flamingo.algorithms.error_fit_functions import (
|
|
12
|
+
fit_periodic_sampling,
|
|
13
|
+
initialize_delay_dilatation,
|
|
14
|
+
fit_delay_dilatation
|
|
15
|
+
)
|