pytdo 0.2.2.2__py3-none-any.whl

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.
@@ -0,0 +1,997 @@
1
+ """TDO Processor class to analyse TDO experiments."""
2
+
3
+ import logging
4
+ from collections.abc import Callable
5
+ from pathlib import Path
6
+ from typing import Literal, Self
7
+
8
+ import numpy as np
9
+ from pyuson import BaseProcessor
10
+ from scipy import signal
11
+
12
+ from .. import sp
13
+ from ..config import Config
14
+ from ._types import MetadataProcessor, tTDOProcessor
15
+
16
+ logger = logging.getLogger(__name__)
17
+
18
+ MEAS_TO_CROP = (
19
+ "pickup_time",
20
+ "pickup",
21
+ "magfield_time",
22
+ "magfield",
23
+ "signal_time",
24
+ )
25
+
26
+ TDO_SIGNAL_NAME = "tdo_signal" # name of the TDO signal (the frequencies barycenters)
27
+ PROGRAM_NAME = "pytdo"
28
+ OUT_FORMAT = (".csv", ".tsv", ".txt", ".out")
29
+ CSV_TDO_NCOLS = 3
30
+ CSV_RES_NCOLS = 11
31
+
32
+
33
+ class TDOProcessor(tTDOProcessor, BaseProcessor):
34
+ """A Processor class for TDO experiments."""
35
+
36
+ def __init__(self, *args, **kwargs):
37
+ self._program_name = PROGRAM_NAME
38
+ self._config_cls = Config
39
+ super().__init__(*args, **kwargs)
40
+
41
+ self.metadata = MetadataProcessor()
42
+
43
+ self._meas_name = [*self.cfg.measurements.keys()][0]
44
+ self._tdo_name = TDO_SIGNAL_NAME
45
+ self._tdo_det_inc_name = self._tdo_name + "_detrend_inc"
46
+ self._tdo_det_dec_name = self._tdo_name + "_detrend_dec"
47
+ self._tdo_inv_inc_name = self._tdo_det_inc_name.replace("detrend", "inverse")
48
+ self._tdo_inv_dec_name = self._tdo_det_dec_name.replace("detrend", "inverse")
49
+
50
+ self.npoints_raw = 0
51
+
52
+ self.is_cropped = {meas_name: False for meas_name in MEAS_TO_CROP}
53
+ self.is_cropped[self._meas_name] = False
54
+
55
+ @property
56
+ def expid(self) -> str:
57
+ """Experiment ID, linked to the Config object."""
58
+ return self.cfg.expid
59
+
60
+ @expid.setter
61
+ def expid(self, value: str):
62
+ """Setter for expid."""
63
+ self.cfg.expid = value
64
+ self.cfg.build_filenames()
65
+
66
+ @property
67
+ def data_directory(self) -> Path:
68
+ """Data directory, linked to the Config object."""
69
+ return self.cfg.data_directory
70
+
71
+ @data_directory.setter
72
+ def data_directory(self, value: str | Path):
73
+ """Setter for `data_directory`."""
74
+ self.cfg.data_directory = Path(value)
75
+ self.cfg.build_filenames()
76
+
77
+ def load_pickup(self) -> Self:
78
+ """
79
+ Load the pickup binary file with the settings from the configuration.
80
+
81
+ The experiment temperature and the sampling rate is also read from the file and
82
+ added to the metadata.
83
+ """
84
+ # Get reader settings
85
+ filename = Path(self.cfg.filenames["pickup"])
86
+ precision = self.cfg.files["pickup"].precision
87
+ endian = self.cfg.files["pickup"].endian
88
+ order = self.cfg.files["pickup"].order
89
+ npickups = self.cfg.parameters.pickup_number
90
+ pickup_index = self.cfg.parameters.pickup_index
91
+
92
+ logger.info(f"Loading pickup data from from {filename.name}...")
93
+ if filename.is_file():
94
+ # Load file
95
+ pu = self._load_pickup(
96
+ filename,
97
+ precision=precision,
98
+ endian=endian,
99
+ order=order,
100
+ nseries=npickups,
101
+ index=pickup_index,
102
+ )
103
+ # Store metadata
104
+ self.metadata["fs_pickup"] = float(pu[0])
105
+ self.metadata["temperature"] = float(pu[1])
106
+
107
+ # Store in the Data object
108
+ nsamples = pu.shape[0] - 2
109
+ self.set_data_raw(
110
+ "pickup_time",
111
+ np.linspace(
112
+ 0, nsamples / self.metadata["fs_pickup"], nsamples, endpoint=False
113
+ ),
114
+ )
115
+ self.set_data_raw("pickup", pu[2:])
116
+
117
+ logger.info(
118
+ f"Pickup loaded. Temperature : {self.metadata['temperature']:2.4f}K, "
119
+ f"{nsamples} points sampled at {self.metadata['fs_pickup'] / 1e3}kHz."
120
+ )
121
+ else:
122
+ # We'll simulate a fake pickup when we'll know the signal size
123
+ logger.info(f"{filename.name} not found, skipping.")
124
+ self.set_data_raw("pickup_time", np.array([]))
125
+ self.set_data_raw("pickup", np.array([]))
126
+ self.metadata["fs_pickup"] = 1.0
127
+
128
+ self.is_cropped["pickup_time"] = False
129
+ self.is_cropped["pickup"] = False
130
+
131
+ return self
132
+
133
+ def load_oscillo(self) -> Self:
134
+ """
135
+ Load TDO signal.
136
+
137
+ Corresponding data is stored in `data_raw`.
138
+ """
139
+ # Get reader settings
140
+ filename = Path(self.cfg.filenames["oscillo"])
141
+ precision = self.cfg.files["oscillo"].precision
142
+ endian = self.cfg.files["oscillo"].endian
143
+
144
+ if not filename.is_file():
145
+ logger.error(f"{filename.name} not found.")
146
+ return self
147
+
148
+ # Load data
149
+ logger.info(f"Loading data from {filename.name}...")
150
+ data = self.load_bin(filename, precision=precision, endian=endian)
151
+
152
+ # Store metadata
153
+ self.metadata["fs_signal"] = float(data[0])
154
+ temperature = float(data[1])
155
+ self.npoints_raw = data.shape[0] - 2
156
+
157
+ if "temperature" in self.metadata:
158
+ # Already the temperature found in the pickup binary file
159
+ other_temperature = self.metadata.pop("temperature")
160
+ if temperature != other_temperature:
161
+ logger.error(
162
+ "Temperatures found in the files do not match "
163
+ f"(got {temperature} and {other_temperature})."
164
+ )
165
+
166
+ # Keep the one from the TDO binary file
167
+ self.metadata["temperature"] = temperature
168
+
169
+ # Store data
170
+ self.set_data_raw(self._meas_name, data[2:])
171
+ self.get_signal_time()
172
+
173
+ self.is_cropped[self._meas_name] = False
174
+
175
+ logger.info(
176
+ f"{self._meas_name} loaded. "
177
+ f"Temperature : {temperature:2.4f}K, {self.npoints_raw} points sampled"
178
+ f" at {self.metadata['fs_signal'] / 1e6}MHz."
179
+ )
180
+
181
+ return self
182
+
183
+ def get_signal_time(self, fs: float | None = None) -> Self:
184
+ """Get the experiment time vector corresponding to the raw data."""
185
+ if fs is None:
186
+ fs = self.metadata["fs_signal"]
187
+ elif "fs_signal" not in self.metadata:
188
+ self.load_oscillo()
189
+
190
+ self.set_data_raw(
191
+ "signal_time",
192
+ np.linspace(
193
+ 0,
194
+ self.npoints_raw / fs,
195
+ self.npoints_raw,
196
+ endpoint=False,
197
+ ),
198
+ )
199
+ self.is_cropped["signal_time"] = False
200
+
201
+ return self
202
+
203
+ def compute_field(self, method: str = "trapz") -> Self:
204
+ """Compute magnetic field."""
205
+ # Checks
206
+ if "pickup" not in self.data_raw:
207
+ self.load_pickup()
208
+
209
+ # Get parameters
210
+ surface = self.cfg.parameters.pickup_surface
211
+
212
+ # Integrate and store
213
+ self._compute_field(surface=surface, method=method)
214
+
215
+ self.is_cropped["magfield"] = False
216
+ self.is_cropped["magfield_time"] = False
217
+
218
+ return self
219
+
220
+ def _crop_signal(
221
+ self,
222
+ meas_name: str,
223
+ start: int,
224
+ stop: int,
225
+ where: Literal["raw", "processed"] = "raw",
226
+ force: bool = False,
227
+ append: str = "_full",
228
+ ):
229
+ """
230
+ Crop a 1D vector from `start` to `stop`.
231
+
232
+ The dataset named `meas_name` must be a 1D vector.
233
+
234
+ Parameters
235
+ ----------
236
+ meas_name : str
237
+ Dataset name. Must be allowed to be re-cropped, e.g. exists in the
238
+ `is_cropped` dict.
239
+ start, stop : int
240
+ Start and stop index.
241
+ where : {"raw", "processed"}, optional
242
+ Where to get and set the data (`data_raw` or `data_processed`). Default is
243
+ "raw".
244
+ force : bool, optional
245
+ Whether to crop even if a dataset named `meas_name + append` already exists.
246
+ Default is False.
247
+ append : str, optional
248
+ Bit of text that is appended to the base measurement name to store the
249
+ original data. Default is "_full".
250
+ """
251
+ match where:
252
+ case "raw":
253
+ getter = getattr(self, "get_data_raw")
254
+ setter = getattr(self, "set_data_raw")
255
+ case "processed":
256
+ getter = getattr(self, "get_data_processed")
257
+ setter = getattr(self, "set_data_processed")
258
+
259
+ if getter(meas_name + append, checkonly=True) and not force:
260
+ self.is_cropped[meas_name] = True
261
+ logger.info(f"{meas_name} not cropped because already cropped.")
262
+ elif getter(meas_name, checkonly=True):
263
+ sig = getter(meas_name)
264
+ setter(meas_name + append, sig.copy())
265
+ setter(meas_name, sig[start:stop])
266
+ self.is_cropped[meas_name] = True
267
+ logger.info(f"{meas_name} cropped.")
268
+ else:
269
+ self.is_cropped[meas_name] = False
270
+ logger.warning(f"{meas_name} not cropped because not loaded or created.")
271
+
272
+ def crop_signal(self, force: bool = False) -> Self:
273
+ """
274
+ Crop signal up until `max_time` defined in the settings.
275
+
276
+ The resulting signal is put in `data_raw`, the original data is kept with a
277
+ trailing `_full`.
278
+ """
279
+ logger.info("Cropping data...")
280
+
281
+ # Signal
282
+ if "fs_signal" in self.metadata:
283
+ idx_crop = int(self.metadata["fs_signal"] * self.cfg.settings.max_time)
284
+ self._crop_signal(self._meas_name, 0, idx_crop, where="raw", force=force)
285
+ self._crop_signal("signal_time", 0, idx_crop, where="raw", force=force)
286
+ else:
287
+ logger.warning("Data not loaded.")
288
+
289
+ # Pickup and magnetic field
290
+ if "fs_pickup" in self.metadata:
291
+ idx_crop = int(self.metadata["fs_pickup"] * self.cfg.settings.max_time)
292
+ self._crop_signal("pickup_time", 0, idx_crop, where="raw", force=force)
293
+ self._crop_signal("pickup", 0, idx_crop, where="raw", force=force)
294
+ self._crop_signal(
295
+ "magfield_time", 0, idx_crop, where="processed", force=force
296
+ )
297
+ self._crop_signal("magfield", 0, idx_crop, where="processed", force=force)
298
+ else:
299
+ logger.warning("Pickup not loaded.")
300
+
301
+ return self
302
+
303
+ def compute_spectrogram(self) -> Self:
304
+ """
305
+ Perform a spectrogram on the raw signal.
306
+
307
+ This a FFT performed on overlapping time windows of the signal. This results in
308
+ a power spectral density (PSD) as a function of time and frequency.
309
+ Parameters for the spectrogram are defined in the settings section of the
310
+ configuration.
311
+
312
+ The time and frequency vector and the 2D PSD are stored in `data_processed`.
313
+ """
314
+ # Check if data was loaded
315
+ if not self._check_data_loaded():
316
+ self.load_oscillo()
317
+ # Check if data was time-cropped
318
+ if not self.is_cropped[self._meas_name]:
319
+ self.crop_signal()
320
+
321
+ # Get parameters
322
+ window = "hann"
323
+ nperseg = self.cfg.settings.spectro_nperseg
324
+ detrend = "linear"
325
+ noverlap = self.cfg.settings.spectro_noverlap
326
+ nfft = self.cfg.settings.spectro_win_size
327
+
328
+ if noverlap == -1:
329
+ noverlap = nperseg // 2
330
+
331
+ # Perform spectrogram
332
+ logger.info(
333
+ "Computing spectrogram (time-window size : "
334
+ f"{nperseg / self.metadata['fs_signal'] * 1e6:2.2f}µs)..."
335
+ )
336
+ fxx, txx, sxx = signal.spectrogram(
337
+ self.get_data_raw(self._meas_name),
338
+ self.metadata["fs_signal"],
339
+ window=window,
340
+ nperseg=nperseg,
341
+ noverlap=noverlap,
342
+ nfft=nfft,
343
+ detrend=detrend,
344
+ )
345
+ logger.info("Spectrogram computed.")
346
+
347
+ # Store data
348
+ self.set_data_processed("spectro_f", fxx)
349
+ self.set_data_processed("spectro_t", txx)
350
+ self.set_data_processed("spectro_s", sxx)
351
+
352
+ return self
353
+
354
+ def find_barycenters(self) -> Self:
355
+ """
356
+ Find barycenters in the spectrogram.
357
+
358
+ The maxima are found in the 2D PSD. The barycenter of the corresponding
359
+ frequencies is computed in a time window around the maxima, defined by the
360
+ settings in the configuration.
361
+
362
+ This results in a time vector (the time windows) and the TDO signal (the
363
+ barycenters, e.g. frequencies). Those two quantities are stored in
364
+ `data_processed`.
365
+ """
366
+ # Checks
367
+ if not self._check_spectro_computed():
368
+ logger.error("Spectrogram not computed. Run `compute_spectrogram()` first")
369
+ return self
370
+
371
+ logger.info(
372
+ "Finding spectrogram barycenters (frequency-window size : "
373
+ f"{2 * self.cfg.settings.barycenters_fwindow:2.3f}Hz)..."
374
+ )
375
+ self.set_data_processed(
376
+ self._tdo_name,
377
+ sp.find_barycenters(
378
+ self.get_data_processed("spectro_f"),
379
+ self.get_data_processed("spectro_s"),
380
+ self.cfg.settings.barycenters_fwindow,
381
+ fast=self.cfg.settings.barycenters_fast,
382
+ ),
383
+ )
384
+ # Corresponding time vector (start at 0)
385
+ time_tdo = self.get_data_processed("spectro_t")
386
+ self.set_data_processed("time_exp", time_tdo - time_tdo[0])
387
+
388
+ # Remove previously-computed values based on this TDO signal
389
+ self.remove_data_processed(self._tdo_name + "_fit_inc")
390
+ self.remove_data_processed(self._tdo_name + "_fit_dec")
391
+ self.remove_data_processed(self._tdo_det_inc_name)
392
+ self.remove_data_processed(self._tdo_det_dec_name)
393
+ logger.info("TDO signal extracted.")
394
+
395
+ return self
396
+
397
+ def align_field(self) -> Self:
398
+ """Align magnetic field on the `time_exp` vector."""
399
+ if not self._check_field_computed():
400
+ self.compute_field()
401
+ self.crop_signal()
402
+
403
+ if not self._check_barycenters_computed():
404
+ self.find_barycenters()
405
+ if not self._check_barycenters_computed():
406
+ logger.error("TDO signal could not be extracted, check messages above.")
407
+ return self
408
+
409
+ exptime = self.get_data_processed("time_exp")
410
+ magtime = self.get_data_processed("magfield_time")
411
+ magfield = self.get_data_processed("magfield")
412
+ self.set_data_processed(
413
+ "magfield", np.interp(exptime, magtime, magfield, left=0)
414
+ )
415
+ self.set_data_processed("magfield_time", exptime)
416
+
417
+ # Get the up / down indices
418
+ self.get_up_down_indices()
419
+
420
+ return self
421
+
422
+ def get_up_down_indices(self) -> Self:
423
+ """Get increasing and decreasing field indices."""
424
+ self.inds_inc, self.inds_dec = sp.get_up_down_indices(
425
+ self.get_data_processed("magfield")
426
+ )
427
+
428
+ return self
429
+
430
+ def detrend_polyfit(self) -> Self:
431
+ """Fit the signal to detrend it."""
432
+ # Checks
433
+ if not self._check_field_aligned():
434
+ self.align_field()
435
+ if not self._check_field_aligned():
436
+ logger.error(
437
+ "Magnetic field could not be aligned, check messages above"
438
+ )
439
+ return self
440
+
441
+ if not hasattr(self, "inds_inc") or not hasattr(self, "inds_dec"):
442
+ self.get_up_down_indices()
443
+
444
+ # Get parameters
445
+ b1, b2 = self.cfg.settings.poly_window
446
+ deg = self.cfg.settings.poly_deg
447
+
448
+ # Fit and detrend
449
+ logger.info(
450
+ f"Fitting (degree : {deg}) and detrending TDO signal in {b1, b2}T..."
451
+ )
452
+ fp_inc, res_inc = sp.fit_poly(
453
+ self.get_data_processed("magfield")[self.inds_inc],
454
+ self.get_data_processed(self._tdo_name)[self.inds_inc],
455
+ b1,
456
+ b2,
457
+ deg,
458
+ )
459
+
460
+ fp_dec, res_dec = sp.fit_poly(
461
+ self.get_data_processed("magfield")[self.inds_dec],
462
+ self.get_data_processed(self._tdo_name)[self.inds_dec],
463
+ b1,
464
+ b2,
465
+ deg,
466
+ )
467
+
468
+ # Store
469
+ self.set_data_processed(self._tdo_name + "_fit_inc", fp_inc)
470
+ self.set_data_processed(self._tdo_name + "_fit_dec", fp_dec)
471
+ self.set_data_processed(self._tdo_det_inc_name, res_inc)
472
+ self.set_data_processed(self._tdo_det_dec_name, res_dec)
473
+
474
+ logger.info("TDO signal detrended.")
475
+
476
+ return self
477
+
478
+ def oversample_inverse_field(self) -> Self:
479
+ """Express data in 1/B and oversample."""
480
+ # Checks
481
+ if not self._check_tdo_detrended():
482
+ self.detrend_polyfit()
483
+
484
+ # Get parameters
485
+ b1, b2 = self.cfg.settings.fft_window
486
+ npoints = self.cfg.settings.npoints_interp_inverse
487
+
488
+ if b1 == -1:
489
+ b1 = self.cfg.settings.poly_window[0]
490
+ if b2 == -1:
491
+ b2 = self.cfg.settings.poly_window[1]
492
+
493
+ # Interpolate inverse field
494
+ logger.info(
495
+ f"Oversampling TDO signal in 1/B ({npoints} points in {b1, b2}T)..."
496
+ )
497
+ field_inverse_inc, tdo_inverse_inc = sp.interpolate_inverse(
498
+ self.get_data_processed("magfield")[self.inds_inc],
499
+ self.get_data_processed(self._tdo_det_inc_name),
500
+ b1,
501
+ b2,
502
+ npoints,
503
+ )
504
+
505
+ field_inverse_dec, tdo_inverse_dec = sp.interpolate_inverse(
506
+ self.get_data_processed("magfield")[self.inds_dec],
507
+ self.get_data_processed(self._tdo_det_dec_name),
508
+ b1,
509
+ b2,
510
+ npoints,
511
+ )
512
+
513
+ # Store
514
+ self.set_data_processed("magfield_inverse_inc", field_inverse_inc)
515
+ self.set_data_processed(self._tdo_inv_inc_name, tdo_inverse_inc)
516
+ self.set_data_processed("magfield_inverse_dec", field_inverse_dec)
517
+ self.set_data_processed(self._tdo_inv_dec_name, tdo_inverse_dec)
518
+
519
+ logger.info("TDO signal interpolated in 1/B.")
520
+
521
+ return self
522
+
523
+ def fft_inverse_field(self) -> Self:
524
+ """
525
+ FFT on the signal in 1/B.
526
+
527
+ The resulting "frequencies" are therefore in units of B (teslas).
528
+ """
529
+ # Checks
530
+ if not self._check_tdo_inverse():
531
+ self.oversample_inverse_field()
532
+
533
+ # FFT
534
+ logger.info("FFT on TDO signal in 1/B...")
535
+ f_inc, fft_inc = sp.fourier_transform(
536
+ self.get_data_processed(self._tdo_inv_inc_name),
537
+ np.mean(np.diff(self.get_data_processed("magfield_inverse_inc"))),
538
+ pad_mult=self.cfg.settings.fft_pad_mult,
539
+ )
540
+
541
+ f_dec, fft_dec = sp.fourier_transform(
542
+ self.get_data_processed(self._tdo_inv_dec_name),
543
+ np.mean(np.diff(self.get_data_processed("magfield_inverse_dec"))),
544
+ pad_mult=self.cfg.settings.fft_pad_mult,
545
+ )
546
+
547
+ # Clip
548
+ idx_max_bfreq = sp.find_nearest_index(f_dec, self.cfg.settings.max_bfreq)
549
+ f_inc = f_inc[:idx_max_bfreq]
550
+ fft_inc = fft_inc[:idx_max_bfreq]
551
+ f_dec = f_dec[:idx_max_bfreq]
552
+ fft_dec = fft_dec[:idx_max_bfreq]
553
+
554
+ # Store
555
+ self.set_data_processed("bfreq_inc", f_inc)
556
+ self.set_data_processed("fft_inc", fft_inc)
557
+ self.set_data_processed("bfreq_dec", f_dec)
558
+ self.set_data_processed("fft_dec", fft_dec)
559
+
560
+ logger.info(
561
+ f"FFT computed and cropped up until {self.cfg.settings.max_bfreq}T."
562
+ )
563
+
564
+ return self
565
+
566
+ def extract_tdo(self) -> Self:
567
+ """Helper function that does everything required to extract the TDO signal."""
568
+ self.compute_spectrogram().find_barycenters().align_field()
569
+
570
+ return self
571
+
572
+ def remove_background(self) -> Self:
573
+ """Helper function to detrend the signal and sort signal in 1/B."""
574
+ self.detrend_polyfit().oversample_inverse_field()
575
+
576
+ return self
577
+
578
+ def collect_arrays(self, array_names_list: list[str]) -> list[np.ndarray]:
579
+ """Collect and data in `data_processed`."""
580
+ return [self.get_data_processed(name) for name in array_names_list]
581
+
582
+ def get_csv_filename(self, suffix: str = "", ext: str = ".csv") -> str:
583
+ """Build the output file name."""
584
+ return str(self.data_directory / (self.expid + suffix + ext))
585
+
586
+ def save_tdo_csv(self, filename: str | Path | None = None, sep: str = "\t") -> Self:
587
+ """
588
+ Save intermediate results as a CSV file.
589
+
590
+ The intermediate results correspond to the extracted TDO signal, before any
591
+ post-processing (detrending, ...).
592
+ If the file already exists, it is overwritten.
593
+ """
594
+ if filename is None:
595
+ filename = self.get_csv_filename(suffix="-tdo")
596
+
597
+ logger.info("Saving extracted TDO signal...")
598
+
599
+ if not self._check_field_aligned():
600
+ logger.warning(
601
+ "The TDO signal and the magnetic fields are not aligned, aligning now"
602
+ )
603
+ self.align_field()
604
+
605
+ to_save = ["time_exp", "magfield", self._tdo_name]
606
+ a = sp.collate_arrays(self.collect_arrays(to_save))
607
+
608
+ header = sep.join(["time", "field", "tdo"])
609
+
610
+ np.savetxt(
611
+ filename,
612
+ a,
613
+ delimiter=sep,
614
+ header=header,
615
+ comments="",
616
+ )
617
+
618
+ logger.info(f"Saved at {Path(filename).name}.")
619
+
620
+ return self
621
+
622
+ def _get_result_names_list(self, ud: Literal["inc", "dec"]):
623
+ """
624
+ Generate the list of things to save.
625
+
626
+ Either in increasing or decreasing magnetic field.
627
+ """
628
+ return [
629
+ "time_exp",
630
+ "magfield",
631
+ self._tdo_name,
632
+ self._tdo_name + "_fit_" + ud,
633
+ self._tdo_det_dec_name if ud == "dec" else self._tdo_det_inc_name,
634
+ "magfield_inverse_" + ud,
635
+ self._tdo_inv_dec_name if ud == "dec" else self._tdo_inv_inc_name,
636
+ "bfreq_" + ud,
637
+ "fft_" + ud,
638
+ ]
639
+
640
+ def _get_results_up_down(
641
+ self, ud: Literal["inc", "dec"]
642
+ ) -> tuple[np.ndarray, list[str]]:
643
+ """Save increasing or decreasing magnetic field results in a CSV file."""
644
+ names_list = self._get_result_names_list(ud)
645
+ to_save = self.collect_arrays(names_list)
646
+ names_list.insert(3, "magfield_" + ud)
647
+ to_save.insert(
648
+ 3,
649
+ self.get_data_processed("magfield")[
650
+ self.inds_dec if ud == "dec" else self.inds_inc
651
+ ],
652
+ )
653
+ names_list.insert(4, self._tdo_name + "_" + ud)
654
+ to_save.insert(
655
+ 4,
656
+ self.get_data_processed(self._tdo_name)[
657
+ self.inds_dec if ud == "dec" else self.inds_inc
658
+ ],
659
+ )
660
+ return sp.collate_arrays(to_save), names_list
661
+
662
+ def save_results_csv(
663
+ self,
664
+ filename_prefix: str | Path | None = None,
665
+ sep: str = "\t",
666
+ ) -> Self:
667
+ """
668
+ Save analysed results as CSV.
669
+
670
+ It includes : time, aligned magnetic field, TDO signal, detrended TDO signal,
671
+ 1/B, TDO signal oversampled in 1/B, Fourier transform.
672
+ """
673
+ if filename_prefix is None:
674
+ filename_prefix = Path(self.get_csv_filename(suffix="-results"))
675
+ else:
676
+ filename_prefix = Path(filename_prefix)
677
+
678
+ logger.info("Saving analysed results...")
679
+
680
+ # Increasing magnetic field
681
+ filename_inc = filename_prefix.with_stem(filename_prefix.stem + "-up")
682
+ to_save, header = self._get_results_up_down("inc")
683
+ header_inc = sep.join(header)
684
+ np.savetxt(
685
+ filename_inc,
686
+ to_save,
687
+ delimiter=sep,
688
+ header=header_inc,
689
+ comments="",
690
+ )
691
+
692
+ # Decreasing magnetic field
693
+ filename_dec = filename_prefix.with_stem(filename_prefix.stem + "-down")
694
+ to_save, header = self._get_results_up_down("dec")
695
+ header_dec = sep.join(header)
696
+ np.savetxt(
697
+ filename_dec,
698
+ to_save,
699
+ delimiter=sep,
700
+ header=header_dec,
701
+ comments="",
702
+ )
703
+
704
+ logger.info(f"Saved at {filename_inc.name} and {filename_dec.name}.")
705
+
706
+ return self
707
+
708
+ def load_csv(self, filepath: Path, sep: str | None = None):
709
+ """Load data from a CSV file."""
710
+ filepath = Path(filepath)
711
+ if not filepath.is_file():
712
+ logger.error("File does not exist")
713
+ return
714
+
715
+ reader, delimiter = self._determine_file_format(filepath, sep=sep)
716
+
717
+ if isinstance(reader, str) and reader == "unknown":
718
+ logger.error(f"Could not load input file ({filepath})")
719
+ return
720
+
721
+ logger.info(f"Reading data from {filepath.name}...")
722
+ status = reader(filepath, sep=delimiter)
723
+ if not status:
724
+ logger.error(f"Failed to read {filepath.name}, check messages above")
725
+ return
726
+
727
+ # Get the up / down indices
728
+ self.get_up_down_indices()
729
+
730
+ logger.info(f"Read data from {filepath.name}.")
731
+
732
+ def _determine_file_format(
733
+ self, filepath: Path, sep: str | None = None
734
+ ) -> tuple[Callable[[Path, str], bool] | str, str]:
735
+ """Determine what type of file we got."""
736
+ match filepath.suffix:
737
+ case ".out":
738
+ return self._load_csv_legacy_tdo, " " if sep is None else sep
739
+ case ".txt":
740
+ return self._load_csv_legacy_results, "," if sep is None else sep
741
+ case ".csv" | ".tsv":
742
+ return self._determine_csv_format(filepath, sep=sep)
743
+ case _:
744
+ logger.error(f"Unknown file extension : {filepath.suffix}")
745
+ return "unknown", ""
746
+
747
+ def _determine_csv_format(
748
+ self, filepath: Path, sep: str | None = None
749
+ ) -> tuple[Callable[[Path, str], bool] | str, str]:
750
+ """Determine what type of CSV file we got."""
751
+ # Read first line
752
+ with open(filepath) as f:
753
+ header = f.readline()
754
+
755
+ # Count how much delimiters there are to find the number of columns
756
+ if sep is None:
757
+ sep = "\t"
758
+ ncols = header.count(sep) + 1
759
+
760
+ if ncols == CSV_TDO_NCOLS:
761
+ return self._load_csv_tdo, sep
762
+ elif ncols == CSV_RES_NCOLS:
763
+ return self._load_csv_results, sep
764
+ else:
765
+ logger.error(
766
+ f"Could not determine what type of file this is : {filepath.name}"
767
+ )
768
+ return "unknown", ""
769
+
770
+ def _load_csv_legacy_tdo(self, filepath: Path, sep: str = " ") -> bool:
771
+ """Load already extracted TDO signal from a legacy .out file."""
772
+ logger.info("Loading TDO signal from a (legacy) .out file...")
773
+ data = np.loadtxt(filepath, delimiter=sep, skiprows=1, usecols=(0, 1))
774
+
775
+ # data is ["magfield", self._tdo_name]
776
+ self.set_data_processed("magfield", data[:, 0])
777
+ self.set_data_processed(self._tdo_name, data[:, 1])
778
+
779
+ # Create the time vector to pass the field-aligned checks
780
+ self.set_data_processed(
781
+ "time_exp", np.linspace(0, self.cfg.settings.max_time, data.shape[0])
782
+ )
783
+ self.set_data_processed("magfield_time", self.get_data_processed("time_exp"))
784
+
785
+ # Get the up / down indices
786
+ self.get_up_down_indices()
787
+
788
+ return True
789
+
790
+ def _load_csv_legacy_results(self, filepath: Path, sep: str = ",") -> bool:
791
+ """Load already computed results from a legacy .txt file."""
792
+ logger.info("Loading results from a (legacy) .txt file...")
793
+
794
+ # Load data
795
+ data = np.loadtxt(filepath, delimiter=sep, skiprows=1)
796
+
797
+ # Guess if it's increasing or decreasing magnetic field
798
+ inc_or_dec = self._determine_inc_or_dec(filepath)
799
+ if inc_or_dec == "unknown":
800
+ logger.error(
801
+ "Couldn't determine if the file is for increasing or decreasing "
802
+ "magnetic field"
803
+ )
804
+ return False
805
+ self._set_map_in_data_processed(self._map_cols_legacy_results(data, inc_or_dec))
806
+
807
+ # Set extra data (to pass field-aligned check)
808
+ self.set_data_processed("magfield_time", self.get_data_processed("time_exp"))
809
+
810
+ return True
811
+
812
+ def _load_csv_tdo(self, filepath: Path, sep: str = "\t") -> bool:
813
+ """Load already extracted TDO signal from a CSV file."""
814
+ logger.info("Loading TDO signal from CSV file...")
815
+ data = np.loadtxt(filepath, delimiter=sep, skiprows=1, usecols=(0, 1, 2))
816
+
817
+ # data is ["time_exp", "magfield", self._tdo_name]
818
+ self.set_data_processed("time_exp", data[:, 0])
819
+ self.set_data_processed("magfield_time", data[:, 0])
820
+ self.set_data_processed("magfield", data[:, 1])
821
+ self.set_data_processed(self._tdo_name, data[:, 2])
822
+
823
+ return True
824
+
825
+ def _load_csv_results(self, filepath: Path, sep: str = "\t") -> bool:
826
+ """Load already computed results from a CSV file."""
827
+ logger.info("Loading results from a CSV file...")
828
+
829
+ # Load data
830
+ data = np.loadtxt(filepath, delimiter=sep, skiprows=1)
831
+
832
+ # Guess if it's increasing or decreasing magnetic field
833
+ inc_or_dec = self._determine_inc_or_dec(filepath)
834
+ if inc_or_dec == "unknown":
835
+ logger.error(
836
+ "Couldn't determine if the file is for increasing or decreasing "
837
+ "magnetic field"
838
+ )
839
+ return False
840
+ self._set_map_in_data_processed(self._map_cols_results(data, inc_or_dec))
841
+
842
+ # Set extra data (to pass field-aligned check)
843
+ self.set_data_processed("magfield_time", self.get_data_processed("time_exp"))
844
+
845
+ return True
846
+
847
+ def _determine_inc_or_dec(
848
+ self, filepath: Path, keywords: tuple[str] = ("inc", "dec")
849
+ ) -> Literal["inc", "dec", "unknown"]:
850
+ """
851
+ Determine if CSV file is for increasing or decreasing magnetic field.
852
+
853
+ Parameters
854
+ ----------
855
+ filepath : Path
856
+ Path to the CSV file.
857
+ keywords : tuple[str]
858
+ Two-elements tuple with the strings that allow to determine if it is
859
+ increasing or decreasing, respectively. Default is ("inc", "dec").
860
+
861
+ Returns
862
+ -------
863
+ inc_or_dec : {"inc", "dec", "unknown"}
864
+ """
865
+ with open(filepath) as f:
866
+ header = f.readline()
867
+
868
+ ninc = header.count(keywords[0])
869
+ ndec = header.count(keywords[1])
870
+
871
+ if ninc > ndec:
872
+ return "inc"
873
+ elif ninc < ndec:
874
+ return "dec"
875
+ else:
876
+ return "unknown"
877
+
878
+ def _map_cols_legacy_results(
879
+ self, data: np.ndarray, kw: Literal["inc", "dec"]
880
+ ) -> dict[str, np.ndarray]:
881
+ """
882
+ Map a field name with a column in the legacy results CSV file.
883
+
884
+ Parameters
885
+ ----------
886
+ data : np.ndarray
887
+ Tabular data read from the legacy results CSV file.
888
+ kw : {"inc", "dec"}
889
+ Increasing or decreasing magnetic field identifier (usually "inc" or "dec").
890
+ """
891
+ where_nan = np.isnan(data)
892
+
893
+ def extract_col(idx):
894
+ return data[~where_nan[:, idx], idx]
895
+
896
+ return {
897
+ "time_exp": extract_col(0),
898
+ "magfield": extract_col(1),
899
+ self._tdo_name: extract_col(2),
900
+ self._tdo_name + "_fit_" + kw: extract_col(7),
901
+ self._tdo_det_dec_name
902
+ if kw == "dec"
903
+ else self._tdo_det_inc_name: extract_col(8),
904
+ "magfield_inverse_" + kw: extract_col(9),
905
+ self._tdo_inv_dec_name
906
+ if kw == "dec"
907
+ else self._tdo_inv_inc_name: extract_col(10),
908
+ "bfreq_" + kw: extract_col(11),
909
+ "fft_" + kw: extract_col(12),
910
+ }
911
+
912
+ def _map_cols_results(
913
+ self, data: np.ndarray, kw: Literal["inc", "dec"]
914
+ ) -> dict[str, np.ndarray]:
915
+ """
916
+ Map a field name with a column in the results CSV file.
917
+
918
+ Parameters
919
+ ----------
920
+ data : np.ndarray
921
+ Tabular data read from the results CSV file.
922
+ kw : {"inc", "dec"}
923
+ Increasing or decreasing magnetic field identifier (usually "inc" or "dec").
924
+ """
925
+ where_nan = np.isnan(data)
926
+
927
+ def extract_col(idx):
928
+ return data[~where_nan[:, idx], idx]
929
+
930
+ return {
931
+ "time_exp": extract_col(0),
932
+ "magfield": extract_col(1),
933
+ self._tdo_name: extract_col(2),
934
+ self._tdo_name + "_fit_" + kw: extract_col(5),
935
+ self._tdo_det_dec_name
936
+ if kw == "dec"
937
+ else self._tdo_det_inc_name: extract_col(6),
938
+ "magfield_inverse_" + kw: extract_col(7),
939
+ self._tdo_inv_dec_name
940
+ if kw == "dec"
941
+ else self._tdo_inv_inc_name: extract_col(8),
942
+ "bfreq_" + kw: extract_col(9),
943
+ "fft_" + kw: extract_col(10),
944
+ }
945
+
946
+ def _set_map_in_data_processed(self, data: dict[str, np.ndarray]):
947
+ """Set data in `data_processed`."""
948
+ for key, value in data.items():
949
+ self.set_data_processed(key, value)
950
+
951
+ def _check_pickup_loaded(self) -> bool:
952
+ """Check if the pickup data was loaded."""
953
+ if ("pickup" not in self.data_raw) or ("fs_pickup" not in self.metadata):
954
+ return False
955
+ else:
956
+ return True
957
+
958
+ def _check_data_loaded(self) -> bool:
959
+ """Check if oscilloscope data was loaded."""
960
+ return (self._meas_name in self.data_raw) and ("fs_signal" in self.metadata)
961
+
962
+ def _check_field_computed(self) -> bool:
963
+ """Check if magnetic field was computed."""
964
+ return self.get_data_processed(
965
+ "magfield_time", checkonly=True
966
+ ) and self.get_data_processed("magfield", checkonly=True)
967
+
968
+ def _check_spectro_computed(self) -> bool:
969
+ """Check if the spectrogram was computed."""
970
+ return self.get_data_processed("spectro_s", checkonly=True)
971
+
972
+ def _check_barycenters_computed(self) -> bool:
973
+ """Check if the frequencies barycenters were computed."""
974
+ return self.get_data_processed(
975
+ self._tdo_name, checkonly=True
976
+ ) and self.get_data_processed("time_exp", checkonly=True)
977
+
978
+ def _check_field_aligned(self) -> bool:
979
+ """Check if the magnetic field was aligned on the TDO signal."""
980
+ if not (self._check_field_computed() and self._check_barycenters_computed()):
981
+ return False
982
+ return (
983
+ self.get_data_processed("time_exp").size
984
+ == self.get_data_processed("magfield_time").size
985
+ )
986
+
987
+ def _check_tdo_detrended(self) -> bool:
988
+ """Check if the TDO signal has been detrended."""
989
+ return self.get_data_processed(
990
+ self._tdo_det_inc_name, checkonly=True
991
+ ) and self.get_data_processed(self._tdo_det_dec_name, checkonly=True)
992
+
993
+ def _check_tdo_inverse(self) -> bool:
994
+ """Check if the TDO signal was oversampled in 1/B."""
995
+ return self.get_data_processed(
996
+ self._tdo_inv_inc_name, checkonly=True
997
+ ) and self.get_data_processed(self._tdo_inv_dec_name, checkonly=True)