# 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

## 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

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