Routines that return fields data structures
One needs to know what data is available, and then transfer it from
shared memory to data structures accessible from within IDL.
Currently the FAST fields routines return two sorts of data. The
first sort is an anonymous IDL structure known as a `FAST fields data'
structure. Such a structure contains sample times, data values,
units, calibration information, and data gap information. The second
sort is known as a `TPLOT quantity', which is a set of anonymous data
structures stored on the IDL memory heap and accessible to the TPLOT
plotting package in IDL.
Most of the data reduction routines (FA_FIELDS_COMBINE, FF_FILTER,
FA-FIELDS_SPEC, etc) operate on FAST fields data structures to produce
either other FAST fields data structures or TPLOT quantities.
Data Acquisition Routines
GET_FA_FIELDS: basic routine for acquiring data from shared memory.
Data can be loaded in calibrated or uncalibrated form (enforced
calibration depending upon setting of the FAST_CALIBRATE environment
variable), and is returned as either a FAST fields structure or as a
TPLOT quantity.
FF_POTENTIAL:
GET_DENSITY:
FA_FIELDS_CYCLOTRON:
computes electron, H+, He+, and O+ cyclotron frequencies from
measured magnetic field data (the DQI MagDC is required), as well as |B| and
angle between spin plane and B.
FA_FIELDS_DSP:
acquire DSP spectral data and compute OMNI spectral density,
then store results as TPLOT quantities.
FA_FIELDS_SFA:
acquire SFA spectral data and compute OMNI spectral density,
then store results as TPLOT quantities.
FA_FIELDS_PWT:
acquire PWT data, compute spectral density, offset frequencies,
and store as a TPLOT quantity.
FF_DSP_POWER:
compute integrated spectral density of OMNI electric field and
Mag3ac magnetic field DSP data. Frequency interval for integration
can be specified.
DC Perturbation Magnetic Field Estimation:
UCLA_MAG_DESPIN: The extraction of an estimate of the vector
DC perturbation magnetic field from low- or mid-altitude satellite
magnetometer data is a daunting task. It requires on-orbit estimation
of fluxgate magnetometer calibration parameters, precision attitude
estimation, despin and projection of estimated field into various
coordinate systems, and finally subtraction of model (IGRF) magnetic
field, all to a precision of at least 1 part in 1000. This task is
accomplished on FAST using the UCLA_MAG_DEPSPIN routine. This routine
is conservative, and will warn the user about both the assumptions
that it is using in order to accomplish its task, and when those
assumptions appear to have broken down. When operating correctly, it
estimates of the vector perturbation magnetic field suitable for
studies of current systems, low-frequency electromagnetic
perturbations, and stress transmission. Details of the algorithm can
be found in the IDL code itself (ucla_mag_despin.pro). Be certain to read
the caveats on DC Magnetic Field Data in the Pitfalls section
above prior to interpreting any reduced magnetometer data.
Ignore all the other DC B-field reduction routines (FA_FIELDS_MAGDC
and supporting code).
Despin:
The electric field estimates from a spinning spacecraft
such as FAST are useful in and of themselves, but are much easier to
interpret if transformed (or despun) into a geophysically-relevant
coordinate system, such as one organized around the local magnetic
field. This process of despinning the data is described in greater
detail in the Despinning section below, and involves estimating and
correcting for any gain or offset differences between the two (or
three in the case of 3d despin of HSBM data) antennas used as input to
the despinning procedure. An accurate estimate of the relative
orientation of the antennas and the ambient magnetic field is also
required (although not with the precision needed in the DC magnetic
field estimation procedure).
FA_FIELDS_PHASE: estimates the angle of the vector pointing towards
the Sun and along the ambient magnetic field in the spacecraft spin
plane using on-board sun sensor and magnetometer data.
FA_FIELDS_DESPIN: estimates despun spin plane electric field (original
version, optimized for DC E-field estimation (few Hz and below)).
FA_FIELDS_DESPIN_SVY_LONG: newer version of FA_FIELDS_DESPIN, again
optimized for DC E-field estimation.
FA_FIELDS_DESPIN_{4K,16K,HSBM}: newer versions of despin codes
optimized for Burst and HSBM data; HSBM supports three-axis despin.
Results are stored as TPLOT quantities.
FA_FIELDS_DESPIN_HG: refilters HG-type data from the original
high-pass frequency of 3.5 kHz to 300 Hz, then despins and stores as a
TPLOT quantity.
SIMPLE_DESPIN: a bare-bones despin routine that handles the
transformation of contiguously sampled data from pairs of antennas.
No gain or offset adjustment is performed. Suitable for careful use
on AC electric fields. Produces FAST fields data structures.
All the newer versions of DESPIN support spectral density estimation
of the despun electric field data within the routines themselves,
rather than through a separate call to the spectral density estimation
routines (see Spectral Estimates below).
Spectral Estimates:
auto and cross spectra.
FA_FIELDS_SPEC: computes the auto-spectrum (aka. power spectrum) of a
given time series stored in a FAST fields data structure, and return
as either a FAST fields data structure or a TPLOT quantity. The
spectrum is estimated using an averaged FFT algorithm, and the
parameters of that algorithm (overlap, points/FFT, FFTs/spectrum,
etc.) can be specified via keywords. Specification of a valid
sampling rate (allowing the selection FastSurvey over SLowSurvey data)
is also allowed.
FA_FIELDS_CROSS: similar to FA_FIELDS_SPEC, but computes the
cross-spectrum (coherence and phase shift) of two signals using an
averaged FFT algorithm.
Utility Routines:
Informational Routines
SHOW_DQIS: lists the DQDs (or DQIs) currently loaded into shared
memory by SDT, along with the timespans and number of points available
for each.
interpolation, merging of channels, sensor information.
FF_INTERP,
FA_FIELDS_COMBINE,
FA_MODE_INFO,
FF_INFO