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.
Files changed (31) hide show
  1. flamingo_thz-0.1.0/LICENSE +22 -0
  2. flamingo_thz-0.1.0/PKG-INFO +292 -0
  3. flamingo_thz-0.1.0/README.md +266 -0
  4. flamingo_thz-0.1.0/pyproject.toml +39 -0
  5. flamingo_thz-0.1.0/setup.cfg +4 -0
  6. flamingo_thz-0.1.0/src/__init__.py +7 -0
  7. flamingo_thz-0.1.0/src/flamingo/__init__.py +7 -0
  8. flamingo_thz-0.1.0/src/flamingo/algorithms/__init__.py +15 -0
  9. flamingo_thz-0.1.0/src/flamingo/algorithms/correction_methods.py +104 -0
  10. flamingo_thz-0.1.0/src/flamingo/algorithms/error_fit_functions.py +211 -0
  11. flamingo_thz-0.1.0/src/flamingo/cli.py +65 -0
  12. flamingo_thz-0.1.0/src/flamingo/core/__init__.py +4 -0
  13. flamingo_thz-0.1.0/src/flamingo/core/optimization_parameter.py +157 -0
  14. flamingo_thz-0.1.0/src/flamingo/core/processing_pipeline.py +426 -0
  15. flamingo_thz-0.1.0/src/flamingo/gui/__init__.py +1 -0
  16. flamingo_thz-0.1.0/src/flamingo/gui/components.py +634 -0
  17. flamingo_thz-0.1.0/src/flamingo/gui.py +365 -0
  18. flamingo_thz-0.1.0/src/flamingo/main.py +46 -0
  19. flamingo_thz-0.1.0/src/flamingo/utils/__init__.py +20 -0
  20. flamingo_thz-0.1.0/src/flamingo/utils/config.py +65 -0
  21. flamingo_thz-0.1.0/src/flamingo/utils/helper_functions.py +127 -0
  22. flamingo_thz-0.1.0/src/flamingo/utils/log_capture.py +136 -0
  23. flamingo_thz-0.1.0/src/flamingo/utils/progress.py +129 -0
  24. flamingo_thz-0.1.0/src/flamingo/visualization/__init__.py +7 -0
  25. flamingo_thz-0.1.0/src/flamingo/visualization/plot_data.py +281 -0
  26. flamingo_thz-0.1.0/src/flamingo_thz.egg-info/PKG-INFO +292 -0
  27. flamingo_thz-0.1.0/src/flamingo_thz.egg-info/SOURCES.txt +29 -0
  28. flamingo_thz-0.1.0/src/flamingo_thz.egg-info/dependency_links.txt +1 -0
  29. flamingo_thz-0.1.0/src/flamingo_thz.egg-info/entry_points.txt +3 -0
  30. flamingo_thz-0.1.0/src/flamingo_thz.egg-info/requires.txt +7 -0
  31. 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
+ ![GUI Screenshot](images/screenshot_01.png)
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
+ ![screenshot_02.PNG](images/screenshot_02.png)
161
+
162
+ ![screenshot_03.PNG](images/screenshot_03.png)
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
+ ![GUI Screenshot](images/screenshot_01.png)
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
+ ![screenshot_02.PNG](images/screenshot_02.png)
135
+
136
+ ![screenshot_03.PNG](images/screenshot_03.png)
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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,7 @@
1
+ """flamingo: Data Correction Tool for THz Time Domain Spectroscopy."""
2
+
3
+ __version__ = "0.1.0"
4
+
5
+ # Export key classes/functions for simpler imports
6
+ from flamingo.core.processing_pipeline import ProcessingPipeline
7
+ from flamingo.main import process_data, main
@@ -0,0 +1,7 @@
1
+ """flamingo: Data Correction Tool for THz Time Domain Spectroscopy."""
2
+
3
+ __version__ = "0.1.0"
4
+
5
+ # Export key classes/functions for simpler imports
6
+ from flamingo.core.processing_pipeline import ProcessingPipeline
7
+ from flamingo.main import process_data, 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
+ )