pyrfu.mms package #

Raises:

TypeError – If defatt is not a Dataset or a numpy.ndarray.

Examples

>>> from pyrfu.mms import get_data, load_ancillary, dsl2gse

Define time interval

>>> tint = ["2015-05-09T14:00:000", "2015-05-09T17:59:590"]

Load magnetic field in spacecraft coordinates

>>> b_xyz = get_data("b_dmpa_fgm_brst_l2", tint, 1)

Load spacecraft attitude

>>> defatt = load_ancillary("defatt", tint, 1)

Transform magnetic field to GSE

>>> b_gse = dsl2gse(b_xyz, defatt)

pyrfu.mms.dsl2gsm(inp: DataArray, defatt: Dataset | ndarray, direction: int | None = 1) → DataArray[source]#

Transform time series from MMS’s DSL to GSM.

Parameters:

inp (DataArray) – Input time series to convert.
defatt (Dataset or numpy.ndarray) – Spacecraft attitude.
direction ({1, -1}, Optional) – Direction of transformation. +1 DSL -> GSE, -1 GSE -> DSL. Default is 1.

Returns:

Time series of the input field in the new coordinates systems.

Return type:

DataArray

Raises:

TypeError – If defatt is not xarray.Dataset or numpy.ndarray.

Examples

>>> from pyrfu.mms import get_data, load_ancillary, dsl2gse

Define time interval

>>> tint = ["2015-05-09T14:00:000", "2015-05-09T17:59:590"]

Load magnetic field in spacecraft coordinates

>>> b_xyz = get_data("b_dmpa_fgm_brst_l2", tint, 1)

Load spacecraft attitude

>>> defatt = load_ancillary("defatt", tint, 1)

Transform magnetic field to GSE

>>> b_gse = dsl2gse(b_xyz, defatt)

pyrfu.mms.eis_ang_ang(inp_allt, en_chan: list | None = None, defatt: Dataset | None = None)[source]#

Generates EIS angle-angle distribution.

Parameters:

inp_allt (xarray.Dataset) – Dataset of the fluxes of all 6 telescopes.
en_chan (array_like, Optional) – Energy channels to use. Default use all energy channels.

Returns:

out – EIS skymap-like distribution.

Return type:

pyrfu.mms.eis_combine_proton_pad(phxtof_allt, extof_allt, vec: DataArray | None = None, energy: list | None = None, pa_width: int = 15, despin: bool = False)[source]#

Combines EPD-EIS Energy by Time Of Flight (ExTOF) and Pulse Height by Time Of Flight (PHxTOF) proton Pitch-Angle Distributions (PADs).

Parameters:

phxtof_allt (xarray.Dataset) – Dataset containing the energy spectrum of the 6 telescopes of the Energy Ion Spectrometer (EIS) for MCP Pulse Height by Time Of Flight (PHxTOF).
extof_allt (xarray.Dataset) – Dataset containing the energy spectrum of the 6 telescopes of the Energy Ion Spectrometer (EIS) for Energy by Time Of Flight (ExTOF).
vec (xarray.DataArray, Optional) – Axis with to compute pitch-angle. Default is X-GSE.
energy (array_like, Optional) – Energy range to include in the calculation. Default is [55, 800].
pa_width (int, Optional) – Size of the pitch angle bins, in degrees. Default is 15.
despin (bool, Optional) – Remove spintone. Default is False.

Returns:

out – Combined PHxTOF and ExTOF proton PADs.

Return type:

pyrfu.mms.eis_combine_proton_skymap(phxtof_allt, extof_allt, en_chan: list | None = None, to_psd: bool = True)[source]#

Combines ExTOF and PHxTOF proton energy spectra and generate proton skymap distribution.

Parameters:

phxtof_allt (xarray.Dataset) – Dataset containing the PHxTOF energy spectrum of the 6 telescopes.
extof_allt (xarray.Dataset) – Dataset containing the ExTOF energy spectrum of the 6 telescopes.
en_chan (array_like, Optional) – Energy channels to use. Default use all energy channels.
to_psd (bool, Optional) – Flag to convert differential particle flux to phase space density.

Returns:

eis_skymap – EIS skymap distribution

Return type:

pyrfu.mms.eis_combine_proton_spec(phxtof_allt, extof_allt)[source]#

Combine ExTOF and PHxTOF proton energy spectra into a single combined Dataset.

Parameters:

phxtof_allt (xarray.Dataset) – Dataset containing the PHxTOF energy spectrum of the 6 telescopes.
extof_allt (xarray.Dataset) – Dataset containing the ExTOF energy spectrum of the 6 telescopes.

Returns:

comb_allt – Dataset containing the combined PHxTOF and ExTOF energy spectrum of the 6 telescopes.

Return type:

pyrfu.mms.eis_moments(inp, specie: str = 'proton', n_bg: DataArray | None = None, p_bg: DataArray | None = None)[source]#

Computes the partial moments given the omni-directional differential particle flux and the ion specie under the assumption of angular isotropy and non-relativistic ions using the formula from [1]

\[ \begin{align}\begin{aligned}\begin{split}n \\left [ m^{-3} \\right ] = 4 \\pi \\sqrt{\\frac{m_i}{2}} \\sum_{i} \\left ( E_i^{1/2} \\right)^0 \\left ( \\frac{J_i}{E_i}\\right) \\left ( E_i^{1/2} \\textrm{d} E_i\\right)\end{split}\\\begin{split}P \\left [ Pa \\right ] = 4 \\pi \\sqrt{\\frac{m_i}{2}} \\sum_{i} \\left ( E_i^{1/2} \\right)^2 \\left ( \\frac{J_i}{E_i}\\right) \\left ( E_i^{1/2} \\textrm{d} E_i\\right)\end{split}\\\begin{split}T \\left [ K \\right ] = \\frac{P}{n k_b}\end{split}\end{aligned}\end{align} \]

Parameters:

inp (xarray.DataArray) – Omni-directional differential particle flux.
specie ({"proton", "alpha", "oxygen"}, Optional) – Particle specie. Default is “proton”.
n_bg (xarray.DataArray, Optional) – Time series of the background density. If None do not remove penetrating radiations.
p_bg (xarray.DataArray, Optional) – Time series of the background pressure. If None do not remove the penetrating radiations.

Returns:

n (xarray.DataArray) – Time series of the number density in [cm^{-3}]
p (xarray.DataArray) – Time series of the pressure in [nPa]
t (xarray.DataArray) – Time series of the temperature in [eV]

Notes

The input omni-directional differential particle flux must be given in [(1/cm^2 s sr keV)^{-1}], and the energy must be in [keV]. The integration is performed using the composite Simpson’s rule.

References

[1]

Mauk, B. H., D. G. Mitchell, R. W. McEntire, C. P. Paranicas, E. C. Roelof, D. J. Williams, S. M. Krimigis, and A. Lagg (2004), Energetic ion characteristics and neutral gas interactions in Jupiter’s magnetosphere, J. Geophys. Res., 109, A09S12, doi:10.1029/2003JA010270.

pyrfu.mms.eis_omni(eis_allt, method: str = 'mean')[source]#

Calculates the omni-directional flux for all 6 telescopes.

Parameters:: eis_allt (xarray.Dataset) – Dataset of the fluxes of all 6 telescopes.
Returns:: flux_omni – Omni-directional flux for all 6 telescopes
Return type:: xarray.DataArray

See also

pyrfu.mms.get_eis_allt

Examples

>>> from pyrfu import mms

Define spacecraft index and time interval

>>> tint = ["2017-07-23T16:10:00", "2017-07-23T18:10:00"]
>>> ic = 2

Get EIS ExTOF all 6 telescopes fluxes

>>> extof_allt = mms.get_eis_allt("flux_extof_proton_srvy_l2", tint, ic)

Compute the omni-directional flux for all 6 telescopes

>>> extof_omni = mms.eis_omni(extof_allt)

pyrfu.mms.eis_pad(inp_allt, vec: DataArray | None = None, energy: list | None = None, pa_width: int = 15)[source]#

Calculates Pitch Angle Distributions (PADs) using data from the MMS Energetic Ion Spectrometer (EIS)

Parameters:

inp_allt (xarray.Dataset) – Energy spectrum for all telescopes.
vec (xarray.DataArray, Optional) – Axis with to compute pitch-angle. Default is X-GSE.
energy (array_like, Optional) – Energy range to include in the calculation. Default is [55, 800].
pa_width (int, Optional) – Size of the pitch angle bins, in degrees. Default is 15.

Returns:

pa_flux – Pitch-angle angle distribution for every energy channels in the energy range.

Return type:

See also

pyrfu.mms.get_eis_allt

pyrfu.mms.eis_pad_combine_sc(pads)[source]#

Generate composite Pitch Angle Distributions (PAD) from the EIS sensors across the MMS spacecraft.

Parameters:: pads (list of xarray.DataArray) – Pitch-angle distribution for all spacecrafts.
Returns:: allmms_pad_avg – Composite pitch angle distribution.
Return type:: xarray.DataArray

pyrfu.mms.eis_pad_spinavg(inp, spin_nums)[source]#

Calculates spin-averaged Pitch-Angle Distribution (PAD) for the EIS instrument.

Parameters:

inp (xarray.DataArray) – Pitch-Angle Distribution.
spin_nums (xarray.DataArray) – Spin #s associated with each measurement.

Returns:

out – Spin-averaged PAD.

Return type:

pyrfu.mms.eis_proton_correction(flux_eis)[source]#

Corrects proton flux values based on FPI/HPCA/EPD-EIS cross calibration. Correction to the EIS PHxTOF data are made by applying an energy-dependent numerical correction of the form:

where E is energy and \(\alpha_{PH} = -0.3\) , \(\beta_{PH} = 0.049\) , \(\gamma_{PH} = 0.001\) are coefficients. Minor adjustments were also made to the lowest energy EIS ExTOF data to correct for foil efficiencies. This correction is of the form:

where E is energy and \(\alpha_{E} = -0.3\) , \(\beta_{E} = 0.049\) , \(\gamma_{E} = 0.001\) are coefficients.

Parameters:: flux_eis (xarray.DataArray) – Omni-directional energy spectrum from EPD-EIS.
Returns:: flux_eis_corr – Cross-calibrated omni-directional energy spectrum from EIS-EPD.
Return type:: xarray.DataArray

pyrfu.mms.eis_skymap(inp_ang_ang, to_psd: bool = True)[source]#

Construct skymap distribution from angle-angle distribution.

Parameters:

inp_ang_ang (xarray.DataArray) – EIS angle-angle distribution.
to_psd (bool, Optional) – Flag to convert differential particle flux to phase space density.

Returns:

out – EIS skymap distribution.

Return type:

See also

pyrfu.mms.eis_ang_ang

pyrfu.mms.eis_skymap_combine_sc(skymaps, method: str = 'mean')[source]#

Generate composite skymap from the EIS sensors across the MMS spacecraft.

Parameters:

skymaps (list of xarray.Dataset) – Skymap distribution for all spacecraft.
method (str, Optional) – Method to combine spectra, “mean” or “sum”

Returns:

out – Composite skymap distribution

Return type:

pyrfu.mms.eis_spec_combine_sc(omni_vars, method: str = 'mean')[source]#

Combines omni-directional energy spectrogram variable from EIS on multiple MMS spacecraft.

Parameters:

omni_vars (list of xarray.DataArray) – Omni-directional energy spectrograms of all spacecraft.
method (str, Optional) – Method to combine spectra, “mean” or “sum”

Returns:

omni_spec – Combined omni-directional energy spectrogram.

Return type:

Examples

>>> from pyrfu.mms import get_eis_allt, eis_omni, eis_spec_combine_sc

Define time interval

>>> tint = ["2017-07-23T16:10:00", "2017-07-23T18:10:00"]

Load EIS ExTOF flux spectrograms for all 6 telescopes for all spacecraft

>>> extof_allt_mms = []
>>> for ic in range(2, 5):
...     extof_allt_mms.append(get_eis_allt("flux_extof_proton_srvy_l2",
...                             tint, ic))

Compute the omni-direction flux spectrogram for all spacecraft

>>> extof_omni_mms = []
>>> for extof_allt in extof_allt_mms:
...     extof_omni_mms.append(eis_omni(extof_allt))

Combine spectrograms of all spacecraft

>>> extof_omni_mmsx = eis_spec_combine_sc(extof_omni_mms)

pyrfu.mms.eis_spin_avg(eis_allt, method: str = 'mean')[source]#

Calculates spin-averaged fluxes for the EIS instrument.

Parameters:

eis_allt (xarray.Dataset) – Dataset of the fluxes of all 6 telescopes.
method ({"mean", "sum"}) – Method.

Returns:

spin_avg_fluxes – Spin-averaged fluxes for all 6 telescopes.

Return type:

Examples

>>> from pyrfu import mms

Define spacecraft index and time interval

>>> tint = ["2017-07-23T16:10:00", "2017-07-23T18:10:00"]
>>> ic = 2

Get EIS ExTOF all 6 telescopes fluxes

>>> extof_allt = mms.get_eis_allt("flux_extof_proton_srvy_l2", tint, ic)

Spin average all 6 telescopes fluxes

>>> extof_allt_despin = mms.eis_spin_avg(extof_allt)

pyrfu.mms.estimate_phase_speed(f_k_power, freq, k, f_min: float = 100.0)[source]#

Simple function to estimate the phase speed from the frequency wave number power spectrum. Fits \(f = v k/ 2 \\pi\) to the power spectrum.

Parameters:

f_k_power (ndarray) – 2D array of powers.
freq (ndarray) – 1D array of frequencies.
k (ndarray) – 1D array of wave numbers.
f_min (float, Optional) – Set low frequency threshold of points used to estimate the speed. Default f_min = 100.

Returns:

vph – Estimated phase speed by fitting linear dispersion relation to data.

Return type:

float

Notes

Draft version but seems to work well. Does not yet handle multiple modes in the same power spectrum.

See also

pyrfu.mms.fk_power_spectrum: Calculates the frequency-wave number power spectrum
pyrfu.mms.probe_align_times: Returns times when f-a electrostatic waves can be characterized.

pyrfu.mms.feeps_active_eyes(var, tint, mms_id)[source]#

This function returns the FEEPS active eyes, based on date/mms_id/species/rate.

Parameters:

var (dict) – Hash table containing parameters.
tint (list of str) – Time range.
mms_id (int or str) – mms_id e.g., ‘4’ for MMS4.

Returns:

sensors –

Hash table containing 2 keys :

out[“top”] : maps to the active top eyes.
out[“bottom”] : maps to the active bottom eyes.

Return type:

dict

Notes

Burst mode should include all sensors (TOP and BOTTOM) :
- electrons : [1, 2, 3, 4, 5, 9, 10, 11, 12].
- ions : [6, 7, 8].
SITL should return (TOP only) :
- electrons : set_intersection([5, 11, 12], active_eyes).
- ions : None.
From Drew Turner, 9/7/2017, srvy mode :
- before 16 August 2017 :
  
  electrons : [3, 4, 5, 11, 12].
  
  ion : [6, 7, 8].
- after 16 August 2017 :
  
  MMS1 :
  
  Top Eyes : 3, 5, 6, 7, 8, 9, 10, 12
  
  Bot Eyes : 2, 4, 5, 6, 7, 8, 9, 10
  
  MMS2 :
  
  Top Eyes : 1, 2, 3, 5, 6, 8, 10, 11
  
  Bot Eyes : 1, 4, 5, 6, 7, 8, 9, 11
  
  MMS3
  
  Top Eyes : 3, 5, 6, 7, 8, 9, 10, 12
  
  Bot Eyes : 1, 2, 3, 6, 7, 8, 9, 10
  
  MMS4 :
  
  Top Eyes : 3, 4, 5, 6, 8, 9, 10, 11
  
  Bot Eyes : 3, 5, 6, 7, 8, 9, 10, 12

pyrfu.mms.feeps_correct_energies(feeps_alle)[source]#

Modifies the energy table in FEEPS spectra (intensity, count_rate, counts) using the function: mms_feeps_energy_table (which is s/c, sensor head and sensor ID dependent)

Parameters:: feeps_alle (xarray.Dataset) – Dataset containing the energy spectrum of the available eyes of the Fly’s Eye Energetic Particle Spectrometer (FEEPS).
Returns:: out – Dataset containing the energy spectrum of the available eyes of the Fly’s Eye Energetic Particle Spectrometer (FEEPS) with corrected energy table.
Return type:: xarray.Dataset

pyrfu.mms.feeps_energy_table(mms_id, eye, sensor_id)[source]#

This function returns the energy table based on each spacecraft and eye; based on the table from : FlatFieldResults_V3.xlsx

Parameters:

mms_id (int) – Spacecraft index e.g., “4” for MMS4.
eye (str) – Sensor eye #.
sensor_id (int) – Sensor ID.

Returns:

out – Energy table.

Return type:

Notes

Bad eyes are replaced by NaNs. Different original energy tables are used depending on if the sensor head is 6-8 (ions) or not (electrons) :

Electron Eyes: 1, 2, 3, 4, 5, 9, 10, 11, 12

Ion Eyes: 6, 7, 8

pyrfu.mms.feeps_flat_field_corrections(inp_alle)[source]#

Apply flat field correction factors to FEEPS ion/electron data. Correct factors are from the gain factor found in: FlatFieldResults_V3.xlsx from Drew Turner, 1/19/2017

Parameters:: inp_alle (xarray.Dataset) – Dataset containing the energy spectrum of the available eyes of the Fly’s Eye Energetic Particle Spectrometer (FEEPS).
Returns:: out – Dataset containing the energy spectrum of the available eyes of the Fly’s Eye Energetic Particle Spectrometer (FEEPS) with corrected data.
Return type:: xarray.Dataset

pyrfu.mms.feeps_omni(inp_dataset)[source]#

Calculates the omni-directional FEEPS spectrogram.

Parameters:: inp_dataset (xarray.Dataset) – Dataset with all active telescopes data.
Returns:: flux_omni – Omni-directional FEEPS spectrogram.
Return type:: xarray.DataArray

Notes

The dataset can be raw data, but it is better to remove bad datas, sunlight contamination and split before.

pyrfu.mms.feeps_pad(inp_dataset, b_bcs, bin_size: float = 16.3636, energy: list | None = None)[source]#

Compute pitch angle distribution using FEEPS data.

Parameters:

inp_dataset (xarray.Dataset) – Energy spectrum of all eyes.
b_bcs (xarray.DataArray) – Time series of the magnetic field in spacecraft coordinates.
bin_size (float, Optional) – Width of the pitch angles bins. Default is 16.3636.
energy (array_like, Optional) – Energy range of particles. Default is [70., 600.]

Returns:

pad – Time series of the pitch angle distribution.

Return type:

pyrfu.mms.feeps_pad_spinavg(pad, spin_sectors, bin_size: float = 16.3636)[source]#

Spin-average the FEEPS pitch angle distributions.

Parameters:

pad (xarray.DataArray) – Pitch angle distribution.
spin_sectors (xarray.DataArray) – Time series of the spin sectors.
bin_size (float, Optional) – Size of the pitch angle bins

Returns:

out – Spin averaged pitch angle distribution.

Return type:

pyrfu.mms.feeps_pitch_angles(inp_dataset, b_bcs)[source]#

Computes the FEEPS pitch angles for each telescope from magnetic field data.

Parameters:

inp_dataset (xarray.Dataset) – Dataset of the time series of the energy spectrum for each eye of FEEPS telescopes.
b_bcs (xarray.DataArray) – Time series of the magnetic in spacecraft coordinates system.

Returns:

out (xarray.DataArray) – Time series of the pitch angles.
idx_maps (dict) – to fill.

pyrfu.mms.feeps_remove_bad_data(inp_dataset)[source]#

This function removes bad eyes, bad lowest energy channels based on data from Drew Turner

Parameters:: inp_dataset (xarray.Dataset) – Dataset with all active telescopes data.
Returns:: inp_dataaset_clean_all – Dataset with all active telescopes data where bad eyes and lab lowest energy channels are set to NaN.
Return type:: xarray.Dataset

pyrfu.mms.feeps_remove_sun(inp_dataset)[source]#

Removes the sunlight contamination from FEEPS data.

Parameters:: inp_dataset (xarray.Dataset) – Dataset of energy spectrum of all eyes.
Returns:: out – Dataset of cleaned energy spectrum of all eyes.
Return type:: xarray.Dataset

See also

pyrfu.mms.get_feeps_alleyes: Read energy spectrum for all FEEPS eyes.

Examples

>>> from pyrfu import mms

Define time interval

>>> tint = ["2017-07-18T13:04:00.000", "2017-07-18T13:07:00.000"]

Spacecraft index

>>> mms_id = 2

Load data from FEEPS

>>> cps_i = mms.get_feeps_alleyes("CPSi_brst_l2", tint, mms_id)
>>> cps_i_clean, _ = mms.feeps_split_integral_ch(cps_i)
>>> cps_i_clean_sun_removed = mms.feeps_remove_sun(cps_i_clean)

pyrfu.mms.feeps_sector_spec(inp_alle)[source]#

Creates sector-spectrograms with FEEPS data (particle data organized by time and sector number)

Parameters:: inp_alle (xarray.Dataset) – Dataset of energy spectrum of all eyes.
Returns:: out – Sector-spectrograms with FEEPS data for all eyes.
Return type:: xarray.Dataset

pyrfu.mms.feeps_spin_avg(flux_omni, spin_sectors)[source]#

spin-average the omni-directional FEEPS energy spectra

Parameters:

flux_omni (xarray.DataArray) – Omni-direction flux.
spin_sectors (xarray.DataArray) – Time series of the spin sectors.

Returns:

spin_avg_flux – Spin averaged omni-directional flux.

Return type:

pyrfu.mms.feeps_split_integral_ch(inp_dataset)[source]#

This function splits the last integral channel from the FEEPS spectra, creating 2 new DataArrays

Parameters:

inp_dataset (xarray.Dataset) – Energetic particles energy spectrum from FEEPS.

Returns:

out (xarray.Dataset) – Energetic particles energy spectra with the integral channel removed.
out_500kev (xarray.Dataset) – Integral channel that was removed.

pyrfu.mms.fft_bandpass(inp, f_min, f_max)[source]#

Perform simple bandpass using FFT - returns fields between with f_min < f < f_max.

Parameters:

inp (xarray.DataArray) – Time series to be bandpassed filtered.
f_min (float or int) – Minimum frequency of filter, f < f_min are removed.
f_max (float or int) – Maximum frequency of filter, f > f_max are removed.

Returns:

out – Time series of the bandpassed filtered data.

Return type:

Notes

Can be some spurius effects near boundary. Can take longer interval then use tlim to remove.

Examples

>>> from pyrfu import mms

Define time interval

>>> tint = ["2017-07-23T16:54:24.000", "2017-07-23T17:00:00.000"]

Spacecraft index

>>> mms_id = 1

Load Electric Field

>>> e_xyz = mms.get_data("e_gse_edp_brst_l2", tint, mms_id)

Bandpass filter

>>> e_xyz_bp = mms.fft_bandpass(e_xyz, 1e1, 1e2)

pyrfu.mms.fk_power_spectrum_4sc(e, r, b, tints, cav: int = 8, num_k: int = 500, num_f: int = 200, df: float | None = None, w_width: int = 1, f_range: list | None = None)[source]#

Calculates the frequency-wave number power spectrum using the four MMS spacecraft. Uses a generalization of mms.fk_powerspectrum. Wavelet based cross-spectral analysis is used to calculate the phase difference each spacecraft pair and determine 3D wave vector. A generalization of the method used in mms.fk_powerspectrum to four point measurements.

Parameters:

e (list of xarray.DataArray) – Fields to apply 4SC cross-spectral analysis to. e.g., e or b fields (if multiple components only the first is used).
r (list of xarray.DataArray) – Positions of the four spacecraft.
b (list of xarray.DataArray) – background magnetic field in the same coordinates as r. Used to determine the parallel and perpendicular wave numbers using 4SC average.
tints (list of str) – Time interval over which the power spectrum is calculated. To avoid boundary effects use a longer time interval for e and b.
cav (int, Optional) – Number of points in time series used to estimate phase. Default cav = 8.
num_k (int, Optional) – Number of wave numbers used in spectrogram. Default num_k = 500.
df (float, Optional) – Linear spacing of frequencies. Default df = None (log spacing).
num_f (int, Optional) – Number of frequencies used in spectrogram. Default num_f = 200.
w_width (float, Optional) – Multiplier for Morlet wavelet width. Default w_width = 1.
f_range (list of float, Optional) – Frequency range for k-k plots. [minf maxf].

Returns:

out – Dataset of array of powers as a function of frequency and wavenumber. Power is normalized to the maximum value.

Return type:

Notes

Wavelength must be larger than twice the spacecraft separations, otherwise spatial aliasing will occur.

Examples

>>> from pyrfu.mms import get_data, fk_power_spectrum_4sc
>>> from pyrfu.pyrf import extend_tint, convert_fac

Load data

>>> tint = ["2015-10-16T13:05:24.00", "2015-10-16T13:05:50.000"]
>>> ic = range(1, 5)
>>> b_fgm = [get_data("b_gse_fgm_brst_l2", tint, i) for i in ic]
>>> b_scm = [get_data("b_gse_scm_brst_l2", tint, i) for i in ic]

Load spacecraft position

>>> tint_long = extend_tint(tint, [-60, 60])
>>> r_gse_mms = [get_data("r_gse", tint_long, i) for i in range(1, 5)]

Convert magnetic field fluctuations to field aligned coordinates

>>> b_fac = [convert_fac(b_s, b_f) for b_s, b_f in zip(b_scm, b_fgm)]
>>> b_par = [b_s[:, 0] for b_s in b_fac]

Compute dispersion relation

>>> tint = ["2015-10-16T13:05:26.500", "2015-10-16T13:05:27.000"]
>>> pwer = fk_power_spectrum_4sc(b_par, r_gse, b_fgm, tint, 4, 500, 2,
... 10, 2)

pyrfu.mms.get_data(var_str, tint, mms_id, verbose: bool = True, data_path: str = '', source: str = '')[source]#

Load a variable. var_str must be in var (see below)

Parameters:

var_str (str) – Key of the target variable (use mms.get_data() to see keys.).
tint (list of str) – Time interval.
mms_id (str or int) – Index of the target spacecraft.
verbose (bool, Optional) – Set to True to follow the loading. Default is True.
data_path (str, Optional) – Local path of MMS data. Default uses that provided in pyrfu/mms/config.json
source ({"local", "sdc", "aws"}, Optional) – Ressource to fetch data from. Default uses default in pyrfu/mms/config.json

Returns:

out – Time series of the target variable of measured by the target spacecraft over the selected time interval.

Return type:

xarray.DataArray or xarray.Dataset

See also

pyrfu.mms.get_ts: Read time series.
pyrfu.mms.get_dist: Read velocity distribution function.

Examples

>>> from pyrfu import mms

Define time interval

>>> tint_brst = ["2019-09-14T07:54:00.000", "2019-09-14T08:11:00.000"]

Index of MMS spacecraft

>>> ic = 1

Load magnetic field from FGM

>>> b_xyz = mms.get_data("b_gse_fgm_brst_l2", tint_brst, ic)

pyrfu.mms.get_dist(file_path, cdf_name, tint: list | None = None)[source]#

Read field named cdf_name in file and convert to velocity distribution function.

Parameters:

file_path (str) – Path of the cdf file.
cdf_name (str) – Name of the target variable in the cdf file.
tint (list of str, Optional) – Time interval.

Returns:

out – Time series of the velocity distribution function if the target specie in the selected time interval.

Return type:

pyrfu.mms.get_eis_allt(tar_var, tint, mms_id, verbose: bool = True, data_path: str = '')[source]#

Read energy spectrum of the selected specie in the selected energy range for all telescopes.

Parameters:

tar_var (str) – Key of the target variable like {data_unit}_{dtype}_{specie}_{data_rate}_{data_lvl}.
tint (list of str) – Time interval.
mms_id (int or float or str) – Index of the spacecraft.
verbose (bool, Optional) – Set to True to follow the loading. Default is True.
data_path (str, Optional) – Path of MMS data.

Returns:

out – Dataset containing the energy spectrum of the 6 telescopes of the Energy Ion Spectrometer.

Return type:

Examples

>>> from pyrfu import mms

Define time interval

>>> tint_brst = ["2017-07-23T16:54:24.000", "2017-07-23T17:00:00.000"]

Read proton energy spectrum for all EIS telescopes

>>> eis_allt = mms.get_eis_allt("Flux_extof_proton_srvy_l2", tint_brst, 2)

pyrfu.mms.get_feeps_alleyes(tar_var, tint, mms_id, verbose: bool = True, data_path: str = '')[source]#

Read energy spectrum of the selected specie in the selected energy range for all FEEPS eyes.

Parameters:

tar_var (str) – Key of the target variable like {data_unit}{specie}_{data_rate}_{data_lvl}.
tint (list of str) – Time interval.
mms_id (int or float or str) – Index of the spacecraft.
verbose (bool, Optional) – Set to True to follow the loading. Default is True.
data_path (str, Optional) – Path of MMS data. Default uses pyrfu.mms.mms_config.py

Returns:

out – Dataset containing the energy spectrum of the available eyes of the Fly’s Eye Energetic Particle Spectrometer (FEEPS).

Return type:

Examples

>>> from pyrfu import mms

Define time interval

>>> tint_brst = ["2017-07-23T16:54:24.000", "2017-07-23T17:00:00.000"]

Read electron energy spectrum for all FEEPS eyes

>>> feeps_all_eyes = mms.get_feeps_alleyes("fluxe_brst_l2", tint_brst, 2)

pyrfu.mms.get_feeps_omni(tar_var, tint, mms_id, verbose: bool = True, data_path: str = '', spin_avg: bool = False)[source]#

Computes the omni-directional energy spectrum of the target data unit for the target specie over the target energy range. The data are washed, splitted and sunlight contamination free.

Parameters:

tar_var (str) – Key of the target variable like {data_unit}_{specie}_{data_rate}_{data_lvl}.
tint (list of str) – Time interval.
mms_id (int or str) – Index of the spacecraft.
verbose (bool, Optional) – Set to True to follow the loading. Default is True.
data_path (str, Optional) – Path of MMS data. Default uses pyrfu.mms.mms_config.py
spin_avg (bool, Optional) – Spin average the omni-directional flux. Default is False.

Returns:

flux_omni – Energy spectrum of the target data unit for the target specie in omni direction.

Return type:

pyrfu.mms.get_hpca_dist(inp, azimuth)[source]#

Returns pseudo-3D particle data structures containing mms hpca data for use with spd_slice2d.

Parameters:

inp (xarray.DataArray) – HPCA ion spec
azimuth (xarray.DataArray) – Azimuthal angles.

Returns:

out – HPCA distribution

Return type:

dict

pyrfu.mms.get_pitch_angle_dist(vdf, b_xyz, tint: list | None = None, **kwargs)[source]#

Computes the pitch angle distributions from l1b brst particle data.

Parameters:

vdf (xarray.Dataset) – to fill
b_xyz (xarray.DataArray) – to fill
tint (list of str, Optional) – Time interval for closeup.
angles (int or float or list of ndarray) – User defined angles.
meanorsum ({'mean', 'sum', 'sum_weighted'}) – Method.

Returns:

pad – Particle pitch angle distribution

Return type:

Examples

>>> from pyrfu import mms

Define time intervals

>>> tint_long = ["2017-07-24T12:48:34.000", "2017-07-24T12:58:20.000"]
>>> tint_zoom = ["2017-07-24T12:49:18.000", "2017-07-24T12:49:30.000"]

Load ions velocity distribution for MMS1

>>> vdf_i = mms.get_data("pdi_fpi_brst_l2", tint_long, 1)

Load magnetic field in the spacecraft coordinates system.

>>> b_dmpa = mms.get_data("b_dmpa_fgm_brst_l2", tint_long, 1)

Compute pitch angle distribution

>>> options = dict(angles=24)
>>> pad_i = mms.get_pitch_angle_dist(vdf, b_dmpa, tint_zoom, **options)

pyrfu.mms.get_ts(file_path, cdf_name, tint: list | None = None)[source]#

Reads field named cdf_name in file and convert to time series.

Parameters:

file_path (str) – Path of the cdf file.
cdf_name (str) – Name of the target variable in the cdf file.
tint (list of str, Optional) – Time interval.

Returns:

out – Time series of the target variable in the selected time interval.

Return type:

pyrfu.mms.get_variable(file_path, cdf_name)[source]#

Reads field named cdf_name in file and convert to DataArray.

Parameters:

file_path (str) – Path of the cdf file.
cdf_name (str) – Name of the target variable in the cdf file.

Returns:

out – Target variable.

Return type:

pyrfu.mms.hpca_calc_anodes(inp, fov: list | None = None, method: str = 'mean')[source]#

Averages over anodes (or a given field of view) for HPCA ion data.

Parameters:

inp (xarray.DataArray) – Ion flux; [nt, npo16, ner63], looking direction
fov (list of float, Optional) – Field of view, in angles, from 0-360. Default is [0., 360.].
method ({"mean", "sum"}, Optional) – Method. Default is “mean”.

Returns:

out – HPCA ion flux averaged over the anodes within the selected field of view.

Return type:

pyrfu.mms.hpca_energies()[source]#: Construct Hot Plasma Composition Analyser (HPCA) energy bins

pyrfu.mms.hpca_pad(vdf, saz, aze, b_xyz, elim=None)[source]#

Computes HPCA pitch angle distribution.

Parameters:

vdf (xarray.DataArray) – Ion PSD or flux; [nt, npo16, ner63], looking direction
saz (xarray.DataArray) – Start index of azimuthal angle; [nt, 1], (0 - 15)
aze (xarray.DataArray) – Azimuthal angle per energy; [nT, naz16, npo16, ner63]
b_xyz (xarray.DataArray) – B in dmpa coordinate
elim (list, Optional) – [emin, emax], energy range for PAD

Returns:

pad_spec – PAD spectrum

Return type:

Examples

>>> pad_ = hpca_pad(vdf, saz, aze, elev, ien, b_xyz, elim=[500, 3000])

pyrfu.mms.hpca_spin_sum(inp, saz, method: str = 'mean')[source]#

Sum or average teh Hot Plasma Composition Analyser (HPCA) data over each spin.

Parameters:

inp (xarray.DataArray) – Ion PSD or flux; [nt, npo16, ner63], looking direction
saz (xarray.DataArray) – Start azimuthal spin indices.
method ({"mean", "sum"}, Optional) – Method either “sum” or “mean”. Default is “mean”

Returns:

out – Distribution averaged over each spin.

Return type:

pyrfu.mms.lh_wave_analysis(tints, e_xyz, b_scm, b_xyz, n_e, min_freq: float = 10.0, max_freq: float = 0.0, lowpass_b_xyz: float = 2.0)[source]#

Calculates lower-hybrid wave properties from MMS data

Parameters:

tints (list of str) – Time interval
e_xyz (xarray.DataArray) – Time series pf the electric field
b_scm (xarray.DataArray) – Time series of the fluctuations of the magnetic field
b_xyz (xarray.DataArray) – Time series of the background magnetic field
n_e (xarray.DataArray) – Time series of the number density
min_freq (float, Optional) – Minimum frequency in the highpass filter for LH fluctuations. Default is 10.
max_freq (float, Optional) – Maximum frequency in the bandpass filter for LH fluctuations. Default is 0 (highpass filter).
lowpass_b_xyz (float, Optional) – Maximum frequency for low-pass filter of background magnetic field (FGM)

Returns:

phi_eb (xarray.DataArray) – to fill
v_best (ndarray) – to fill
dir_best (ndarray) – to fill
thetas (ndarray) – to fill
corrs (ndarray) – to fill

Examples

>>> from pyrfu.mms import get_data, lh_wave_analysis

Define time intervals

>>> tint_long = ["2015-12-14T01:17:39.000", "2015-12-14T01:17:43.000"]
>>> tint_zoom = ["2015-12-14T01:17:40.200","2015-12-14T01:17:41.500"]

Load fields and density

>>> b_gse = get_data("b_gse_fgm_brst_l2", tint_long, 2)
>>> e_gse = get_data("e_gse_edp_brst_l2", tint_long, 2)
>>> b_scm = get_data("b_gse_scm_brst_l2", tint_long, 2)
>>> n_e = get_data("ne_fpi_brst_l2", tint_long, 2)

Lower Hybrid Waves Analysis

>>> opt = dict(lhfilt=[5, 100])
>>> res = lh_wave_analysis(tint, e_xyz, b_scm, b_xyz, n_e, **opt)

pyrfu.mms.list_files(tint, mms_id, var, data_path: str = '')[source]#

Find available files in the data directories of the target instrument, data type, data rate, mms_id and level during the target time interval.

Parameters:

tint (array_like) – Time interval
mms_id (str or int) – Index of the spacecraft
var (dict) –
Dictionary containing 4 keys
- var[“inst”] : name of the instrument
- var[“tmmode”] : data rate
- var[“lev”] : data level
- var[“dtype”] : data type
data_path (str, Optional) – Path of MMS data. Default uses pyrfu.mms.mms_config.py

Returns:

file_names – List of files corresponding to the parameters in the selected time interval

Return type:

pyrfu.mms.list_files_ancillary(tint, mms_id, product, data_path: str = '')[source]#

Find available ancillary files in the data directories for the target product type.

Parameters:

tint (list of str) – Time interval
mms_id (str or int) – Spacecraft index
product ({"predatt", "predeph", "defatt", "defeph"}) – Ancillary type.
data_path (str, Optional) – Path of MMS data. If None use pyrfu.mms.mms_config.py

Returns:

file_names – Ancillary files in interval.

Return type:

pyrfu.mms.list_files_ancillary_sdc(tint, mms_id, product)[source]#

Find available ancillary files from LASP SDC for the target product type.

Parameters:

tint (list of str) – Time interval
mms_id (str or int) – Spacecraft index
product ({"predatt", "predeph", "defatt", "defeph"}) – Ancillary type.

Returns:

file_names – Ancillary files in interval.

Return type:

pyrfu.mms.list_files_aws(tint, mms_id, var, bucket_prefix: str = '')[source]#

Find available files from the Amazon Wed Services (AWS) for the target instrument, data type, data rate, mms_id and level during the target time interval.

Parameters:

tint (array_like) – Time interval
mms_id (str or int) – Index of the spacecraft
var (dict) –
Dictionary containing 4 keys
- var[“inst”] : name of the instrument
- var[“tmmode”] : data rate
- var[“lev”] : data level
- var[“dtype”] : data type
bucket_prefix (str, Optional) – Name of AWS S3 bucket.

Returns:

file_names – List of files corresponding to the parameters in the selected time interval

Return type:

pyrfu.mms.list_files_sdc(tint, mms_id, var)[source]#

Find availables files from the LASP SDC for the target instrument, data type, data rate, mms_id and level during the target time interval.

Parameters:

tint (array_like) – Time interval
mms_id (str or int) – Index of the spacecraft
var (dict) –
Dictionary containing 4 keys
- var[“inst”] : name of the instrument
- var[“tmmode”] : data rate
- var[“lev”] : data level
- var[“dtype”] : data type
username (str, Optional) – Login to LASP MMS SITL. Default downloads from https://lasp.colorado.edu/mms/sdc/public/

Returns:

file_names – List of files corresponding to the parameters in the selected time interval

Return type:

pyrfu.mms.load_ancillary(product, tint, mms_id, verbose: bool = True, data_path: str = '')[source]#

Loads ancillary data.

Parameters:

product ({"predatt", "predeph", "defatt", "defeph"}) – Ancillary type.
tint (list of str) – Time interval
mms_id (str or int) – Spacecraft index
verbose (bool, Optional) – Set to True to follow the loading. Default is True
data_path (str, Optional) – Path of MMS data. If None use pyrfu.mms.mms_config.py

Returns:

out – Time series of the ancillary data

Return type:

pyrfu.mms.load_brst_segments(tint, data_path: str | None = None, download: bool = True)[source]#

Load burst segment time intervals associated with the input time interval tint.

Parameters:

tint (list) – Time interval to look for burst segments.
data_path (str, Optional) – Path of MMS data. If None use pyrfu/mms/config.json

Returns:

brst_segments – Segments of burst mode data.

Return type:

pyrfu.mms.make_model_kappa(vdf, n_s, v_xyz_s, t_s, kappa: float = 7.0)[source]#

Make a general isottropic kappa distribution function based on particle moment data in the same format as vdf.

Parameters:

vdf (xarray.Dataset) – Particle distribution (skymap).
n_s (xarray.DataArray) – Time series of the number density.
v_xyz_s (xarray.DataArray) – Time series of the bulk velocity.
t_s (xarray.DataArray) – Time series of the scalar temperature.
kappa (float. Optional) – Kappa index, Default is 7.

Returns:

out – Distribution function in the same format as vdf.

Return type:

pyrfu.mms.make_model_vdf

See also

Todo

Generalize to bi-Kappa distributions.

pyrfu.mms.make_model_vdf(vdf, b_xyz, sc_pot, n_s, v_xyz, t_xyz, isotropic: bool = False)[source]#

Make a general bi-Maxwellian distribution function based on particle moment data in the same format as PDist.

Parameters:

vdf (xarray.Dataset) – Particle distribution (skymap).
b_xyz (xarray.DataArray) – Time series of the background magnetic field.
sc_pot (xarray.DataArray) – Time series of the spacecraft potential.
n_s (xarray.DataArray) – Time series of the number density of specie s.
v_xyz (xarray.DataArray) – Time series of the bulk velocity.
t_xyz (xarray.DataArray) – Time series of the temperature tensor.
isotropic (bool, Optional) – Flag to make an isotropic model distribution. Default is False.

Returns:

model_vdf – Distribution function in the same format as vdf.

Return type:

See also

pyrfu.mms.calculate_epsilon: Calculates epsilon parameter using model distribution.

Examples

>>> from pyrfu.mms import get_data, make_model_vdf

Define time interval

>>> tint_brst = ["2015-10-30T05:15:20.000", "2015-10-30T05:16:20.000"]

Load magnetic field and spacecraft potential

>>> b_dmpa = get_data("b_dmpa_fgm_brst_l2", tint_brst, 1)
>>> scpot = get_data("V_edp_brst_l2", tint_brst, 1)

Load electron velocity distribution function

>>> vdf_e = get_data("pde_fpi_brst_l2", tint_brst, 1)

Load moments of the electron velocity distribution function

>>> n_e = get_data("ne_fpi_brst_l2", tint_brst, 1)
>>> v_xyz_e = get_data("ve_dbcs_fpi_brst_l2", tint_brst, 1)
>>> t_xyz_e = get_data("te_dbcs_fpi_brst_l2", tint_brst, 1)

Compute model electron velocity distribution function

>>> vdf_m_e = make_model_vdf(vdf_e, b_xyz, scpot, n_e, v_xyz_e, t_xyz_e)

pyrfu.mms.probe_align_times(e_xyz, b_xyz, sc_pot, z_phase)[source]#

Returns times when field-aligned electrostatic waves can be characterized using interferometry techniques. The same alignment conditions as Graham et al., JGR, 2015 are used. Optional figure produced showing E_FAC, probe fields, and probe potentials to view time delays between electric fields aligned with B. Currently p5-p6 are not used in this routine; the analysis is the same as the one used for Cluster.

For the figure the panels are :

1. B in DMPA Coordinates
1. Magnitude of B in and out of the spin plane
1. Angles between B and probes 1 and 3 in the spin plane (angle between 0 and 90 degrees)
1. Spacecraft potential from probes perpendicular to B
1. E fields from p1-p4 and SC for probes closely aligned with B
1. E in field-aligned coordinates
1. E from probes p1-p2 and p3-p4.

Parameters:

e_xyz (xarray.DataArray) – Electric field in DSL coordinates, brst mode.
b_xyz (xarray.DataArray) – Magnetic field in DMPA coordinates.
sc_pot (xarray.DataArray) – L2 Spacecraft potential data. Timing corrections are applied in this
z_phase (xarray.DataArray) – Spacecraft phase (z_phase). Obtained from ancillary_defatt.

Returns:

start_time1 (to fill) – Start times of intervals which satisfy the probe alignment conditions for probe combinates p1-p2.
end_time1 (to fill) – End times of intervals which satisfy the probe alignment conditions for probe combinates p1-p2.
start_time3 (to fill) – Start times of intervals which satisfy the probe alignment conditions for probe combinates p3-p4.
end_time3 (to fill) – End times of intervals which satisfy the probe alignment conditions for probe combinates p3-p4.

pyrfu.mms.psd2def(inp)[source]#

Changes units to differential energy flux.

Parameters:

vdf (xarray.Dataset) –

Time series of the 3D velocity distribution with :

time : Time samples.
data : 3D velocity distribution.
energy : Energy levels.
phi : Azimuthal angles.
theta : Elevation angle.

Returns:

out –

Time series of the 3D differential energy flux with :

time : Time samples.
data : 3D density energy flux.
energy : Energy levels.
phi : Azimuthal angles.
theta : Elevation angle.

Return type:

pyrfu.mms.psd2dpf(inp)[source]#

Compute differential particle flux from phase density.

Parameters:

vdf (xarray.Dataset) –

Time series of the velocity distribution function with :

time : Time samples.
data : 3D velocity distribution.
energy : Energy levels.
phi : Azimuthal angles.
theta : Elevation angle.

Returns:

dpf –

Time series of the 3D differential particle flux in 1/(cm^2 s sr keV) with :

time : Time samples.
data : 3D density particle flux.
energy : Energy levels.
phi : Azimuthal angles.
theta : Elevation angle.

Return type:

pyrfu.mms.psd_moments(vdf, sc_pot, **kwargs)[source]#

Computes moments from the FPI particle phase-space densities.

Parameters:

vdf (xarray.Dataset) – 3D skymap velocity distribution.
sc_pot (xarray.DataArray) – Time series of the spacecraft potential.
energy_range (array_like) – Set energy range in eV to integrate over [E_min E_max]. Energy range is applied to energy0 and the same elements are used for energy1 to ensure that the same number of points are integrated over.
no_sc_pot (bool) – Set to 1 to set spacecraft potential to zero. Calculates moments without correcting for spacecraft potential.
en_channels (array_like) – Set energy channels to integrate over [min max]; min and max between must be between 1 and 32.
partial_moments (numpy.ndarray or xarray.DataArray) – Use a binary array to select which psd points are used in the moments calculation. partial_moments must be a binary array (1s and 0s, 1s correspond to points used). Array (or data of Dataarray) must be the same size as vdf.data.
inner_electron ({"on", "off"}) – inner_electrontron potential for electron moments.

Returns:

n_psd (xarray.DataArray) – Time series of the number density (1rst moment).
v_psd (xarray.DataArray) – Time series of the bulk velocity (2nd moment).
p_psd (xarray.DataArray) – Time series of the pressure tensor (3rd moment).
p2_psd (xarray.DataArray) – Time series of the pressure tensor.
t_psd (xarray.DataArray) – Time series of the temperature tensor.
h_psd (xarray.DataArray) – to fill.

Examples

>>> from pyrfu import mms

Define time interval

>>> tint_brst = ["2015-10-30T05:15:20.000", "2015-10-30T05:16:20.000"]

Load magnetic field and spacecraft potential

>>> scpot = mms.get_data("V_edp_brst_l2", tint_brst, 1)

Load electron velocity distribution function

>>> vdf_e = mms.get_data("pde_fpi_brst_l2", tint_brst, 1)

Compute moments

>>> options = dict(energy_range=[1, 1000])
>>> moments_e = mms.psd_moments(vdf_e, scpot, **options)

pyrfu.mms.psd_rebin(vdf: ~xarray.core.dataset.Dataset, phi: ~numpy.ndarray, energy0: ~numpy.ndarray, energy1: ~numpy.ndarray, esteptable: ~numpy.ndarray) -> (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>, <class 'numpy.ndarray'>, <class 'numpy.ndarray'>)[source]#

Convert burst mode distribution into 64 energy channel distribution.

Takes the burst mode distribution sampled in two energy tables and converts to a single energy table with 64 energy channels. Time resolution is halved and phi angles are averaged over adjacent times.

Parameters:

vdf (xarray.Dataset) – Time series of the particle distribution.
phi (numpy.ndarray) – Time series of the phi angles.
energy0 (numpy.ndarray) – Energy table 0.
energy1 (numpy.ndarray) – Energy table 1.
esteptable (numpy.ndarray) – Time series of the stepping table between energies (burst).

Returns:

time_r (numpy.ndarray) – Revised time steps.
vdf_r (numpy.ndarray) – Rebinned particle distribution.
energy_r (numpy.ndarray) – Revised energy table.
phi_r (numpy.ndarray) – Time series of the recalculated phi angle.

Raises:

TypeError – If vdf is not a xarray.Dataset.
TypeError – If phi is not a numpy.ndarray.
TypeError – If energy0 is not a numpy.ndarray.
TypeError – If energy1 is not a numpy.ndarray.
TypeError – If esteptable is not a numpy.ndarray.

Notes

I’m assuming no gaps in the burst data interval. If there is a gap use time_clip before running. To be updated later.

pyrfu.mms.read_feeps_sector_masks_csv(tint)[source]#

Reads the FEEPS sectors to mask due to sunlight contamination from csv files.x

Parameters:: tint (list of str) – time range of interest [starttime, endtime] with the format “YYYY-MM-DD”, “YYYY-MM-DD” or to specify more or less than a day [ ‘YYYY-MM-DD/hh:mm:ss’,’YYYY-MM-DD/hh:mm:ss’]
Returns:: mask – Hash table containing the sectors to mask for each spacecraft and sensor ID
Return type:: dict

pyrfu.mms.reduce(vdf, xyz, dim: str = '1d', base: str = 'pol', **kwargs)[source]#

Reduces (integrates) 3D distribution to 1D (line) or 2D (plane). Draft do not use!!

Parameters:

vdf (xarray.Dataset) – 3D skymap velocity distribution function.
xyz (xarray.DataArray or numpy.ndarray) – Transformation matrix from instrument frame to desired frame.
base (str, Optional) – Base for the 2D projection either cartesian ‘cart’ (default) or polar ‘pol’.
**kwargs – Keyword arguments

Returns:

out – Time series of reduced velocity distribution function.

Return type:

pyrfu.mms.remove_edist_background(vdf, n_sec: float = 0.0, n_art: float = -1.0)[source]#

Remove secondary photoelectrons from electron distribution function according to [1].

Parameters:

vdf (xarray.Dataset) – Measured electron velocity distribution function.
n_sec (float, Optional) – Artificial secondary electron density (isotropic). Default is 0.
n_art (float, Optional) – Artificial photoelectron density (sun-angle dependant), Default is ephoto_scale from des-emoms GlobalAttributes.

Returns:

vdf_new (xarray.Dataset) – Electron VDF with photoelectrons removed.
vdf_bkg (xarray.Dataset) – Photoelectron VDF.
photoe_scle (float) – Artificial photoelectron and secondary electron density

References

[1]

Gershman, D. J., Avanov, L. A., Boardsen,S. A., Dorelli, J. C., Gliese, U., Barrie, A. C.,… Pollock, C. J. (2017). Spacecraft and instrument photoelectrons measured by the dual electron spectrometers on MMS. Journal of Geophysical Research:Space Physics,122, 11,548–11,558. https://doi.org/10.1002/2017JA024518

pyrfu.mms.remove_idist_background(vdf, def_bg)[source]#

Remove the mode background population due to penetrating radiation def_bg from the ion velocity distribution function vdf using the method from [1].

Parameters:

vdf (xarray.Dataset) – Ion velocity distribution function.
def_bg (xarray.DataArray) – Omni-directional ion differential energy flux.

Returns:

vdf_new – Ion velocity distribution function cleaned.

Return type:

References

[1]

Gershman, D. J., Dorelli, J. C., Avanov,L. A., Gliese, U., Barrie, A., Schiff, C.,et al. (2019). Systematic uncertainties in plasma parameters reported by the fast plasma investigation on NASA’s magnetospheric multiscale mission. Journal of Geophysical Research: Space Physics, 124, https://doi.org/10.1029/2019JA026980

pyrfu.mms.remove_imoms_background(n_i, v_gse_i, p_gse_i, n_bg_i, p_bg_i)[source]#

Remove the mode background population due to penetrating radiation from the the moments (density n_i, bulk velocity v_gse_i and pressure tensor p_gse_i) of the ion velocity distribution function using the method from [1].

Parameters:

n_i (xarray.DataArray) – Time series of the ion density.
v_gse_i (xarray.DataArray) – Time series of the ion bulk velocity.
p_gse_i (xarray.DataArray) – Time series of the ion pressure tensor.
n_bg_i (xarray.DataArray) – Time series of the background ion number density.
p_bg_i (xarray.DataArray) – Time series of the background ion pressure scalar.

Returns:

n_i_new (xarray.DataArray) – Time series of the corrected ion number density.
v_gse_i_new (xarray.DataArray) – Time series of the corrected ion bulk velocity.
p_gse_i (xarray.DataArray) – Time series of the corrected ion pressure tensor.

References

[1]

Gershman, D. J., Dorelli, J. C., Avanov,L. A., Gliese, U., Barrie, A., Schiff, C.,et al. (2019). Systematic uncertainties in plasma parameters reported by the fast plasma investigation on NASA’s magnetospheric multiscale mission. Journal of Geophysical Research: Space Physics, 124, https://doi.org/10.1029/2019JA026980

pyrfu.mms.rotate_tensor(inp, rot_flag, vec, perp: str = 'pp')[source]#

Rotates pressure or temperature tensor into another coordinate system.

Parameters:

PeIJ/Peall (xarray.DataArray) – Time series of either separated terms of the tensor or the complete tensor. If columns (PeXX,PeXY,PeXZ,PeYY,PeYZ,PeZZ)
rot_flag (str) –
Flag of the target coordinates system :
- ”fac”Field-aligned coordinates, requires background
  magnetic field Bback, optional flag “pp” \(\mathbf{P}_{\perp 1} = \mathbf{P}_{\perp2}\) or “qq” \(\mathbf{P}_{\perp 1}\) and \(\mathbf{P}_{\perp 2}\) are most unequal, sets P_{23} to zero.
- ”rot”Arbitrary coordinate system, requires new x-direction
  xnew, new y and z directions ynew, znew (if not included y and z directions are orthogonal to xnew and closest to the original y and z directions)
- ”gse” : GSE coordinates, requires MMS spacecraft number
vec (xarray.DataArray or numpy.ndarray) – Vector or coordinates system to rotate the tensor. If vec is timeseries of a vector tensor is rotated in field aligned coordinates. If vec is a numpy.ndarray rotates to a time independant coordinates system.
perp (str, Optional) –
Flag for perpandicular components of the tensor. Default is pp.
- ”pp” : perpendicular diagonal components are equal
- ”qq” : perpendicular diagonal components are most unequal

Returns:

Pe – Time series of the pressure or temperature tensor in field-aligned, user-defined, or GSE coordinates. For “fac” Pe = [Ppar P12 P13; P12 Pperp1 P23; P13 P23 Pperp2]. For “rot” and “gse” Pe = [Pxx Pxy Pxz; Pxy Pyy Pyz; Pxz Pyz Pzz]

Return type:

Examples

>>> from pyrfu import mms, pyrf
>>> # Time interval
>>> tint = ["2015-10-30T05:15:20.000", "2015-10-30T05:16:20.000"]
>>> # Spacecraft index
>>> mms_id = 1
>>> # Load magnetic field and ion temperature tensor
>>> b_xyz = mms.get_data("B_gse_fgm_srvy_l2", tint, mms_id)
>>> t_xyz_i = mms.get_data("Ti_gse_fpi_fast_l2", tint, mms_id)
>>> # Compute ion temperature in field aligned coordinates
>>> t_xyzfac_i = mms.rotate_tensor(t_xyz_i, "fac", b_xyz, "pp")

TODO : implement method “gse”

pyrfu.mms.scpot2ne(sc_pot, n_e, t_e, i_aspoc: DataArray | None = None)[source]#

Compute number density from spacecraft potential. Function uses number density and electron temperature to compute electron thermal current. A best fit of the photoelectron current to the thermal current is used to determine the photoelectron currents and temperatures. These are then used to construct a new number density from the spacecraft potential.

Parameters:

sc_pot (xarray.DataArray) – Time series of the spacecraft potential.
n_e (xarray.DataArray) – Time series of the electron number density.
t_e (xarray.DataArray) – Time series of the electron temperature. Function accepts scalar temperature or tensor (scalar temperature is used in either case).
i_aspoc (xarray.DataArray, Optional) – Time series of the ASPOC current in \(\\mu\) A.

Returns:

n_esc (xarray.DataArray) – Time series of the number density estimated from SCpot, at the same resolution as sc_pot.
i_ph0 (float) – Value of the photoelectron currents ( \(\\mu\) A) of the first population.
t_ph0 (float) – Value of the temperature (eV) of the first population.
i_ph1 (float) – Value of the photoelectron currents ( \(\\mu\) A) of the second population.
t_ph1 (float) – Value of the temperature (eV) of the second population.

Notes

Usual assumptions are made for thermal and photoelectron current, vis., planar geometry for photoelectrons and spherical geometry for thermal electrons. Currently the calculation neglects the ion thermal current, secondary electrons, and other sources of current. ASPOC on does not work very well.

pyrfu.mms.spectr_to_dataset(spectr)[source]#

Convert energy spectrum (DataArray) to Dataset.

Parameters:: spectr (xarray.DataArray) – Spectrogram in DataArray format.
Returns:: out – Spectrogram in Dataset format.
Return type:: xarray.Dataset

pyrfu.mms.tokenize(var_str)[source]#

Parses the variable keys.

Parameters:

var_str (str) – Input key of variable

Returns:

out –

Hash table containing :

param : Variable key.
to : Tensor order.
cs : Coordinate system.
inst : Instrument.
tmmode : Time mode.
lev” : Level of data.

Return type:

dict

pyrfu.mms.vdf_elim(vdf, e_int)[source]#

Limits the skymap distribution to the selected energy range.

Parameters:

vdf (xarray.Dataset) – Skymap velocity distribution to clip.
e_int (list or float) – Energy interval boundaries (list) or energy to slice.

Returns:

vdf_e_clipped – Skymap of the clipped velocity distribution.

Return type:

pyrfu.mms.vdf_frame_transformation(vdf, v_gse)[source]#

Move the skymap into the desired frame associated with the bulk velocity v_gse.

Parameters:

vdf (xarray.Dataset) – Skymap distribution in the initial frame.
v_gse (xarray.DataArray) – Time series of the bulk velocity to shift.

Returns:

out – Skymap distribution into the new frame.

Return type:

Notes

The new skymap grid is identical to the original one. The bulk velocity must be in the same coordinates system as the skymap (i.e spacecraft for FPI and GSE for EIS)

See also

_interp_skymap_cart.py, _interp_skymap_sphe.py

pyrfu.mms.vdf_omni(vdf, method: str = 'mean')[source]#

Computes omni-directional distribution, without changing the units.

Parameters:

vdf (xarray.Dataset) –
Time series of the 3D velocity distribution with :
- time : Time samples.
- data : 3D velocity distribution.
- energy : Energy levels.
- phi : Azimuthal angles.
- theta : Elevation angle.
method ({"mean", "sum"}, Optional) – Method of computation. Use “sum” for counts and “mean” for everything else. Default is “mean”.

Returns:

out – Time series of the omnidirectional velocity distribution function.

Return type:

pyrfu.mms.vdf_projection(vdf, tint, coord_sys: ndarray = array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]), sc_pot: DataArray | None = None, e_lim: float = 20, bins_correction: bool = False)[source]#

Compute the projection of the velocity distribution onto a specified plane.

Parameters:

vdf (xarray.Dataset) – Electron or ion 3D skymap velocity distribution function.
tint (list of str) – Computes data for time interval if len(tint) = 2 or closest time if len(tint) = 1. For tint includes two or more distributions the energies are rebinned into 64 channels.
coord_sys (ndarray, Optional) – 3x3 matrix with 1st column is x, 2nd column is y and 3rd column is z. z is normal to the projection plane and x and y are made orthogonal to z and each other if they are not already. Default is np.eye(3) (project onto spacecraft spin plane).
sc_pot (xarray.DataArray, Optional) – Spacecraft potential to correct velocities. For a single value of tint the closest potential is used. For an interval the spacecraft potential is average over that interval. Default is None (no correction).
e_lim (float, Optional) – Elevation angle limit in degrees above/below projection plane to include in projection. Default is e_lim = 20.
bins_correction (bool, Optional) – Flag to correction elevation bins. Default is False.

Returns:

v_x (numpy.ndarray) – 2D grid of the velocities in the x direction.
v_y (numpy.ndarray) – 2D grid of the velocities in the y direction.
f_mat (numpy.ndarray) – 2D projection of the velocity distribution onto the specified plane

pyrfu.mms.vdf_reduce(vdf, tint, dim, x_vec, z_vec: list | None = None, v_int: list | None = None, n_vpt: int = 100)[source]#

Interpolate the skymap distribution onto the velocity grid defined by the velocity interval v_int along the axes x_vec and z_vec, and reduce (integrate) it along 1 (if dim is “2d”) or 2 (if dim is “1d”).

Parameters:

vdf (xarray.Dataset) – Skymap distribution to reduce.
tint (list of strs) – Time interval over which the time series of the skymap distribution is averaged.
dim ({"1d", "2d"}) – Dimension of the output reduced distribution.
x_vec (array_like) – X axis. For the “1d” case, it is the axis on which the skymap is plotted. For the “2d” case, it is the first of the two axes on which the skymap is plotted.
z_vec (array_like, Optional) – Axis along which the skymap is integrated. Needed only for the “2d” case.
v_int (array_like, Optional) – Velocity interval.
n_vpt (int, Optional) – Number of points along the plot direction(s).

Returns:

out – Reduced distribution.

Return type:

pyrfu.mms.vdf_to_e64(vdf_e32)[source]#

Recompile data into 64 energy channels. Time resolution is halved. Only applies to skymap.

Parameters:: vdf_e32 (xarray.Dataset) – Time series of the particle distribution with 32 energy channels.
Returns:: vdf_e64 – Time series of the particle distribution with 32 energy channels.
Return type:: xarray.Dataset

pyrfu.mms.whistler_b2e(b2, freq, theta_k, b_mag, n_e)[source]#

Computes electric field power as a function of frequency for whistler waves using magnetic field power and cold plasma theory.

Parameters:

b2 (xarray.DataArray) – Time series of the power of whistler magnetic field in nT^2 Hz^{-1}.
freq (ndarray) – frequencies in Hz corresponding B2.
theta_k (float) – wave-normal angle of whistler waves in radians.
b_mag (xarray.DataArray) – Time series of the magnitude of the magnetic field in nT.
n_e (xarray.DataArray) – Time series of the electron number density in cm^{-3}.

Returns:

e2 – Time series of the electric field power.

Return type: