---
# System prepended metadata

title: TFA toolbox

---

# TFA toolbox

## Initial notes

Notes based on project requirements

- MAG (LR/HR) B_NEC with CHAOS model (or just residuals directly with viresclient `residuals=True`)
    - HR might need performance improvement on server side
    - Could calculate model locally with chaosmagpy or eoxmagmod (adds much complexity - could be revisited at a later date to allow flexibility to use outside data sources)
- Track segmentation [-90, +90] MLAT
    - Can use vires auxiliary `QDOrbitDirection`? (flag is -1 / +1 depending on if the craft is heading towards QD pole or away)
- Additional data:
    - Vires auxiliaries: Latitude, QDLatitude, MLT
    - Extensions:
        - Swarm products: EFI, IBI, FAC, IPD, MIT(?)
        - INTERMAGNET
- Lm / L* is needed
    - `SW_OPER_MITx_LP_2F` already contains `L_value` - but it is not clear from documentation which one it is
    - Or run IRBEM from SpacePy to get it?
    - Or even add as an auxiliary within VirES
- Data versioning
    - VirES only gives the latest available data
    - How to handle this?
- What are the visualisation requirements?

Old Matlab tool:
https://gitlab.com/constantinus.0/swarm_indices
![](https://i.imgur.com/5ymleF3.png)

## 2022/07/14

- Input requirements:
    - User chooses between:
        - MAGx_LR, MAGx_HR, EFIx_LP (+ more to come)
        - Which model to use
    - Optional toggles `MFA`:
        - from B_NEC to B_MFA
    - Time range is padded with +- 3 hours (MAGx_LR and others) / +- 5 minutes (MAGx_HR) compared to the user-specified time
    - Flag-based cleaning
- In current tfa_classes.py, TFA_Data holds dataframe (`.DF`) together with references to arrays of interest:
    - `D`: DatetimeIndex
    - `t`: Matplotlib dates (from `md.date2num(D`))
    - `d`: `md.num2date(t)`
    - `X`: B_NEC / (what is specified by user within `meta[General][Field]`)
        - Optionally (if `B_MFA` is chosen in `Field`), rotate vector to the mean field coordinates, i.e. B_NEC_Model direction
    - `meta`, `params`, `label` describing data/process configuration
    - `s` set by `Wavelet` process (scales)
    - `W` set by `Wavelet` process (spectrum)
    - `I` would be set by `.wave_index`
- TFA_Data also holds quickview methods:
    - plot: plots a time series or other line plot
    - image: plots the spectrogram
- Usage pattern:
    ```
    tfa = TFA_Data()  # just initialise object
    tfa.meta = {...}  # Configure the run
    tfa.retrieve_data()  # fetches the input data
    <TFA_Process>.apply(tfa)  # apply a step of the process to the data
    ```
- TFA_Process is an abstract class with `init(params)`, `.apply(target)`, `.append_params(target)` with concrete classes:
    - Cadence: applies `tfalib.constant_cadence` (modifies `tfa.t`, `tfa.X`)
    - Cleaning: applies `tfalib.outliers` + some interp over gaps (modifies `tfa.X`)
    - Filtering: applies `ftalib.filter` to `tfa.X`
    - Wavelet: applied `wavelet_scales, _transform, _normalize`, setting `tfa.s` and `tfa.W`
- process applications are tracked by adding to the `.params` property each time one of the above are used

## 2022/07/26


### L-parameter

So assuming you have the time in CDF_EPOCH (milliseconds since year 0) in a variable, lets say "time" and the position in cartesian coordinates in the GEI system (in km) in a variable "pos" then you do something like

```python
import numpy as np
import spacepy.irbempy as sp
import spacepy.time as t
import spacepy.coordinates as c
import spacepy.toolbox as tbx

tbx.update(leapsecs=True)
REF_RADIUS = 6371.2

ticks = t.Ticktock(time, dtype='CDF')
loci = c.Coords(pos/REF_RADIUS, 'GEI', 'car')
alpha = [90]
extMag = 'OPQUIET'
intMag = 'IGRF' # if you change this, change the options in get_Lstar() as well!
if not L_STAR:
    irbem_res = sp.get_Lm(ticks, loci, alpha, extMag, intMag)
    Lm = np.reshape(irbem_res['Lm'], (-1,1))
else:
    irbem_res = sp.get_Lstar(ticks, loci, alpha, extMag, options=[1,0,0,0,0])
    Lstar = np.reshape(irbem_res['Lstar'], (-1,1))
```

and that gives you either Lm (the McIlwein L value) or the L star, depending on the value of the boolean flag L_STAR.
The alpha is set to 90 degrees and kept constant. It implies that we will calculate L/L* at the position of the satellite and not at some other point farther along the field line