diff --git a/docs/source/rbsp.rst b/docs/source/rbsp.rst index f9b54376..8e620d7a 100644 --- a/docs/source/rbsp.rst +++ b/docs/source/rbsp.rst @@ -1,6 +1,6 @@ Van Allen Probes (RBSP) ======================================================================== -The routines in this module can be used to load data from the Van Allen Probes (RBSP) mission. +The routines in this module can be used to load and process data (in case of RBSPICE) from the Van Allen Probes (RBSP) mission. Electric and Magnetic Field Instrument Suite and Integrated Science (EMFISIS) @@ -68,7 +68,9 @@ Example :align: center :class: imgborder +.. autofunction:: pyspedas.rbsp.rbspice_lib.rbsp_rbspice_pad +.. autofunction:: pyspedas.rbsp.rbspice_lib.rbsp_rbspice_pad_spinavg Energetic Particle, Composition, and Thermal Plasma Suite (ECT) - MagEIS ---------------------------------------------------------- diff --git a/pyspedas/rbsp/__init__.py b/pyspedas/rbsp/__init__.py index bd485fd7..ebbc9c53 100644 --- a/pyspedas/rbsp/__init__.py +++ b/pyspedas/rbsp/__init__.py @@ -28,25 +28,16 @@ def emfisis(trange=['2018-11-5', '2018-11-6'], Parameters ---------- - trange : 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 + trange : list of str, default=['2018-11-5', '2018-11-6'] + 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'] - probe: str or list of str - Spacecraft probe name ('a' or 'b'); default: a - - cadence: str - Data cadence (default: 4sec); other options: '1sec', 'hires' - - coord: str - Data coordinate system (default: sm) - - level: str - Data level; options: 'l1', 'l2', 'l3', l4' + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' - datatype: str - Data type; valid options: + datatype : str, default='magnetometer' + Data type with options varying by data level. Level 1: 'magnetometer' 'hfr' @@ -55,72 +46,83 @@ def emfisis(trange=['2018-11-5', '2018-11-6'], 'spaceweather' 'wfr' 'wna' - Level 2: 'magnetometer' 'wfr' 'hfr' 'housekeeping' - Level 3: 'magnetometer' - Level 4: 'density' 'wna-survey' - wavetype: str - Type of level 2 waveform data; valid options: - For WFR data: - 'waveform' (default) - 'waveform-continuous-burst' - 'spectral-matrix' - 'spectral-matrix-diagonal' - 'spectral-matrix-diagonal-merged' + level : str, default='l3' + Data level; options: 'l1', 'l2', 'l3', l4' - For HFR data: - 'waveform' - 'spectra' - 'spectra-burst' - 'spectra-merged' + cadence : str, default='4sec' + Data cadence; options: '1sec', 'hires', '4sec' + + coord : str, default='sm' + Data coordinate system + wavetype : str, default='waveform' + Type of level 2 waveform data with options: + For WFR data: + 'waveform' (default) + 'waveform-continuous-burst' + 'spectral-matrix' + 'spectral-matrix-diagonal' + 'spectral-matrix-diagonal-merged' + For HFR data: + 'waveform' + 'spectra' + 'spectra-burst' + 'spectra-merged' For descriptions of these data, see: https://emfisis.physics.uiowa.edu/data/L2_products + suffix: str + The tplot variable names will be given this suffix. By default, + no suffix is added. - suffix: str - The tplot variable names will be given this suffix. By default, - no suffix is added. + suffix : str, optional + Suffix for tplot variable names. By default, no suffix is added. - get_support_data: bool + get_support_data : bool, default=False Data with an attribute "VAR_TYPE" with a value of "support_data" - will be loaded into tplot. By default, only loads in data with a + will be loaded into tplot. By default, only loads in data with a "VAR_TYPE" attribute of "data". - varformat: str + varformat : str, optional The file variable formats to load into tplot. Wildcard character "*" is accepted. By default, all variables are loaded in. - varnames: list of str + varnames: list of str, optional List of variable names to load (if not specified, all data variables are loaded) - downloadonly: bool - Set this flag to download the CDF files, but not load them into + downloadonly: bool, default=False + Set this flag to download the CDF files, but not load them into tplot variables - notplot: bool + notplot: bool, default=False Return the data in hash tables instead of creating tplot variables - no_update: bool + no_update: bool, default=False If set, only load data from your local cache - time_clip: bool + time_clip: bool, default=False Time clip the variables to exactly the range specified in the trange keyword Returns - ---------- - List of tplot variables created. - + ------- + tvars : dict or list + List of created tplot variables or dict of data tables if notplot is True. + + Examples + -------- + >>> emfisis_vars = pyspedas.rbsp.emfisis(trange=['2018-11-5/10:00', '2018-11-5/15:00'], datatype='magnetometer', level='l3', time_clip=True) + >>> tplot(['Mag', 'Magnitude']) """ return load(instrument='emfisis', wavetype=wavetype, trange=trange, probe=probe, datatype=datatype, level=level, cadence=cadence, coord=coord, suffix=suffix, get_support_data=get_support_data, varformat=varformat, varnames=varnames, downloadonly=downloadonly, notplot=notplot, time_clip=time_clip, no_update=no_update) @@ -142,27 +144,30 @@ def rbspice(trange=['2018-11-5', '2018-11-6'], Parameters ---------- - trange : list of str + trange : list of str, default=['2018-11-5', '2018-11-6'] 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'] - probe: str or list of str - Spacecraft probe name ('a' or 'b'); default: a + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' + + datatype: str, default='TOFxEH' + Data type; Valid options are specific to different data levels. - datatype: str - Data type (default: tofxeh); Valid options: + level : str, default='l3' + Data level. Valid options: 'l1', 'l2', 'l3' - suffix: str + suffix: str, optional The tplot variable names will be given this suffix. By default, no suffix is added. - get_support_data: bool + get_support_data: bool, default=True Data with an attribute "VAR_TYPE" with a value of "support_data" - will be loaded into tplot. By default, only loads in data with a + will be loaded into tplot. By default, only loads in data with a "VAR_TYPE" attribute of "data". - varformat: str + varformat: str, optional The file variable formats to load into tplot. Wildcard character "*" is accepted. By default, all variables are loaded in. @@ -170,23 +175,33 @@ def rbspice(trange=['2018-11-5', '2018-11-6'], List of variable names to load (if not specified, all data variables are loaded) - downloadonly: bool + downloadonly: bool, default=False Set this flag to download the CDF files, but not load them into tplot variables - notplot: bool + notplot: bool, default=False Return the data in hash tables instead of creating tplot variables - no_update: bool + no_update: bool, default=False If set, only load data from your local cache - time_clip: bool + time_clip: bool, default=False Time clip the variables to exactly the range specified in the trange keyword Returns - ---------- - List of tplot variables created. - + ------- + tvars : dict or list + List of created tplot variables or dict of data tables if notplot is True. + + Examples + -------- + >>> rbspice_vars = pyspedas.rbsp.rbspice(trange=['2018-11-5', '2018-11-6'], datatype='TOFxEH', level='l3') + >>> tplot('rbspa_rbspice_l3_TOFxEH_proton_omni_spin') + + # Calculate the pitch angle distributions + >>> from pyspedas.rbsp.rbspice_lib.rbsp_rbspice_pad import rbsp_rbspice_pad + >>> rbsp_rbspice_pad(probe='a', datatype='TOFxEH', level='l3') + >>> tplot('rbspa_rbspice_l3_TOFxEH_proton_omni_0-1000keV_pad_spin') """ # Valid names @@ -244,51 +259,59 @@ def efw(trange=['2015-11-5', '2015-11-6'], Parameters ---------- - trange : list of str + trange : list of str, default=['2015-11-5', '2015-11-6'] 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'] - probe: str or list of str - Spacecraft probe name ('a' or 'b'); default: a + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' - datatype: str - Data type; Valid options: + datatype : str, default='spec' + Data type. Valid options are specific to different data levels. - suffix: str - The tplot variable names will be given this suffix. By default, + level : str, default='l3' + Data level. Valid options: 'l1', 'l2', 'l3', 'l4' + + suffix: str, optional + The tplot variable names will be given this suffix. By default, no suffix is added. - get_support_data: bool + get_support_data: bool, default=False Data with an attribute "VAR_TYPE" with a value of "support_data" - will be loaded into tplot. By default, only loads in data with a + will be loaded into tplot. By default, only loads in data with a "VAR_TYPE" attribute of "data". - varformat: str + varformat: str, optional The file variable formats to load into tplot. Wildcard character "*" is accepted. By default, all variables are loaded in. - varnames: list of str + varnames: list of str, optional List of variable names to load (if not specified, all data variables are loaded) - downloadonly: bool - Set this flag to download the CDF files, but not load them into + downloadonly: bool, default=False + Set this flag to download the CDF files, but not load them into tplot variables - notplot: bool + notplot: bool, default=False Return the data in hash tables instead of creating tplot variables - no_update: bool + no_update: bool, default=False If set, only load data from your local cache - time_clip: bool + time_clip: bool, default=False Time clip the variables to exactly the range specified in the trange keyword Returns - ---------- - List of tplot variables created. - + ------- + tvars : dict or list + List of created tplot variables or dict of data tables if notplot is True. + + Examples + -------- + >>> efw_vars = pyspedas.rbsp.efw(trange=['2015-11-5', '2015-11-6'], level='l3') + >>> tplot(['efield_in_inertial_frame_spinfit_mgse', 'spacecraft_potential']) """ return load(instrument='efw', trange=trange, probe=probe, datatype=datatype, level=level, suffix=suffix, get_support_data=get_support_data, varformat=varformat, varnames=varnames, downloadonly=downloadonly, notplot=notplot, time_clip=time_clip, no_update=no_update) @@ -311,51 +334,62 @@ def mageis(trange=['2015-11-5', '2015-11-6'], Parameters ---------- - trange : 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 + trange : list of str, default=['2015-11-5', '2015-11-6'] + 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'] - probe: str or list of str - Spacecraft probe name ('a' or 'b'); default: a + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' - datatype: str - Data type; Valid options: + datatype : str, default='' + Data type. Valid options are specific to different data levels. - suffix: str - The tplot variable names will be given this suffix. By default, + level : str, default='l3' + Data level. Valid options: 'l1', 'l2', 'l3', 'l4' + + rel : str, default='rel04' + Release version of the data. + + suffix: str, optional + The tplot variable names will be given this suffix. By default, no suffix is added. - get_support_data: bool + get_support_data: bool, default=False Data with an attribute "VAR_TYPE" with a value of "support_data" - will be loaded into tplot. By default, only loads in data with a + will be loaded into tplot. By default, only loads in data with a "VAR_TYPE" attribute of "data". - varformat: str + varformat: str, optional The file variable formats to load into tplot. Wildcard character "*" is accepted. By default, all variables are loaded in. - varnames: list of str + varnames: list of str, optional List of variable names to load (if not specified, all data variables are loaded) - downloadonly: bool - Set this flag to download the CDF files, but not load them into + downloadonly: bool, default=False + Set this flag to download the CDF files, but not load them into tplot variables - notplot: bool + notplot: bool, default=False Return the data in hash tables instead of creating tplot variables - no_update: bool + no_update: bool, default=False If set, only load data from your local cache - time_clip: bool + time_clip: bool, default=False Time clip the variables to exactly the range specified in the trange keyword Returns - ---------- - List of tplot variables created. - + ------- + tvars : dict or list + List of created tplot variables or dict of data tables if notplot is True. + + Examples + -------- + >>> mageis_vars = pyspedas.rbsp.mageis(trange=['2018-11-5', '2018-11-6'], level='l3', rel='rel04') + >>> tplot('I') """ return load(instrument='mageis', rel=rel, trange=trange, probe=probe, datatype=datatype, level=level, suffix=suffix, get_support_data=get_support_data, varformat=varformat, varnames=varnames, downloadonly=downloadonly, notplot=notplot, time_clip=time_clip, no_update=no_update) @@ -378,52 +412,64 @@ def hope(trange=['2015-11-5', '2015-11-6'], Parameters ---------- - trange : 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 + trange : list of str, default=['2015-11-5', '2015-11-6'] + 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'] - probe: str or list of str - Spacecraft probe name ('a' or 'b'); default: a + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' - datatype: str - Data type; Valid options: + datatype : str, default='moments' + Data type. Valid options are specific to different data levels. - suffix: str - The tplot variable names will be given this suffix. By default, + level : str, default='l3' + Data level. Valid options: 'l1', 'l2', 'l3', 'l4' + + rel : str, default='rel04' + Release version of the data. + + suffix: str, optional + The tplot variable names will be given this suffix. By default, no suffix is added. - get_support_data: bool + get_support_data: bool, default=False Data with an attribute "VAR_TYPE" with a value of "support_data" - will be loaded into tplot. By default, only loads in data with a + will be loaded into tplot. By default, only loads in data with a "VAR_TYPE" attribute of "data". - varformat: str + varformat: str, optional The file variable formats to load into tplot. Wildcard character "*" is accepted. By default, all variables are loaded in. - varnames: list of str + varnames: list of str, optional List of variable names to load (if not specified, all data variables are loaded) - downloadonly: bool - Set this flag to download the CDF files, but not load them into + downloadonly: bool, default=False + Set this flag to download the CDF files, but not load them into tplot variables - notplot: bool + notplot: bool, default=False Return the data in hash tables instead of creating tplot variables - no_update: bool + no_update: bool, default=False If set, only load data from your local cache - time_clip: bool + time_clip: bool, default=False Time clip the variables to exactly the range specified in the trange keyword Returns - ---------- - List of tplot variables created. - + ------- + tvars : dict or list + List of created tplot variables or dict of data tables if notplot is True. + + Examples + -------- + >>> hope_vars = pyspedas.rbsp.hope(trange=['2018-11-5', '2018-11-6'], datatype='moments', level='l3', rel='rel04') + >>> tplot('Ion_density') """ + return load(instrument='hope', rel=rel, trange=trange, probe=probe, datatype=datatype, level=level, suffix=suffix, get_support_data=get_support_data, varformat=varformat, varnames=varnames, downloadonly=downloadonly, notplot=notplot, time_clip=time_clip, no_update=no_update) @@ -445,52 +491,64 @@ def rept(trange=['2015-11-5', '2015-11-6'], Parameters ---------- - trange : 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 + trange : list of str, default=['2015-11-5', '2015-11-6'] + 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'] - probe: str or list of str - Spacecraft probe name ('a' or 'b'); default: a + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' - datatype: str - Data type; Valid options: + datatype : str, default='' + Data type. Valid options are specific to different data levels. - suffix: str - The tplot variable names will be given this suffix. By default, + level : str, default='l3' + Data level. Valid options: 'l1', 'l2', 'l3', 'l4' + + rel : str, default='rel03' + Release version of the data. + + suffix: str, optional + The tplot variable names will be given this suffix. By default, no suffix is added. - get_support_data: bool + get_support_data: bool, default=False Data with an attribute "VAR_TYPE" with a value of "support_data" - will be loaded into tplot. By default, only loads in data with a + will be loaded into tplot. By default, only loads in data with a "VAR_TYPE" attribute of "data". - varformat: str + varformat: str, optional The file variable formats to load into tplot. Wildcard character "*" is accepted. By default, all variables are loaded in. - varnames: list of str + varnames: list of str, optional List of variable names to load (if not specified, all data variables are loaded) - downloadonly: bool - Set this flag to download the CDF files, but not load them into + downloadonly: bool, default=False + Set this flag to download the CDF files, but not load them into tplot variables - notplot: bool + notplot: bool, default=False Return the data in hash tables instead of creating tplot variables - no_update: bool + no_update: bool, default=False If set, only load data from your local cache - time_clip: bool + time_clip: bool, default=False Time clip the variables to exactly the range specified in the trange keyword Returns - ---------- - List of tplot variables created. - + ------- + tvars : dict or list + List of created tplot variables or dict of data tables if notplot is True. + + Examples + -------- + >>> rept_vars = pyspedas.rbsp.rept(trange=['2018-11-5', '2018-11-6'], level='l3', rel='rel03') + >>> tplot('FEDU') """ + return load(instrument='rept', rel=rel, trange=trange, probe=probe, datatype=datatype, level=level, suffix=suffix, get_support_data=get_support_data, varformat=varformat, varnames=varnames, downloadonly=downloadonly, notplot=notplot, time_clip=time_clip, no_update=no_update) @@ -511,54 +569,85 @@ def rps(trange=['2015-11-5', '2015-11-6'], Parameters ---------- - trange : 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 + trange : list of str, default=['2015-11-5', '2015-11-6'] + 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'] - probe: str or list of str - Spacecraft probe name ('a' or 'b'); default: a + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' - datatype: str - Data type; Valid options: + datatype : str, default='rps-1min' + Data type. Valid options are specific to different data levels. - suffix: str - The tplot variable names will be given this suffix. By default, + level : str, default='l2' + Data level. Valid options: 'l1', 'l2', 'l3', 'l4' + + suffix: str, optional + The tplot variable names will be given this suffix. By default, no suffix is added. - get_support_data: bool + get_support_data: bool, default=False Data with an attribute "VAR_TYPE" with a value of "support_data" - will be loaded into tplot. By default, only loads in data with a + will be loaded into tplot. By default, only loads in data with a "VAR_TYPE" attribute of "data". - varformat: str + varformat: str, optional The file variable formats to load into tplot. Wildcard character "*" is accepted. By default, all variables are loaded in. - varnames: list of str + varnames: list of str, optional List of variable names to load (if not specified, all data variables are loaded) - downloadonly: bool - Set this flag to download the CDF files, but not load them into + downloadonly: bool, default=False + Set this flag to download the CDF files, but not load them into tplot variables - notplot: bool + notplot: bool, default=False Return the data in hash tables instead of creating tplot variables - no_update: bool + no_update: bool, default=False If set, only load data from your local cache - time_clip: bool + time_clip: bool, default=False Time clip the variables to exactly the range specified in the trange keyword Returns - ---------- - List of tplot variables created. - + ------- + tvars : dict or list + List of created tplot variables or dict of data tables if notplot is True. + + Examples + -------- + >>> rps_vars = pyspedas.rbsp.rps(trange=['2018-11-5', '2018-11-6'], datatype='rps', level='l2') + >>> tplot('DOSE1') """ return load(instrument='rps', trange=trange, probe=probe, datatype=datatype, level=level, suffix=suffix, get_support_data=get_support_data, varformat=varformat, varnames=varnames, downloadonly=downloadonly, notplot=notplot, time_clip=time_clip, no_update=no_update) def datasets(instrument=None, label=True): + """ + Retrieves available datasets for the specified instrument on the Van Allen Probes (RBSP) mission. + + Parameters + ---------- + instrument : str, optional + Name of the instrument for which to find datasets. If None, finds datasets for all instruments on the mission. + + label : bool, default=True + If True, the function prints both the dataset ID and label. If False, only the dataset ID is printed. + + Returns + ------- + list of str + List of available datasets for the specified instrument or for all instruments if no instrument is specified. + + Examples + -------- + >>> pyspedas.rbsp.find_datasets(instrument='REPT', label=True) + ... + RBSPA_REL03_ECT-REPT-SCI-L3: RBSP/ECT REPT Pitch Angle Resolved Electron and Proton Fluxes. Electron energies: 2 - 59.45 MeV. Proton energies: 21.25 - 0 MeV - D. Baker (University of Colorado at Boulder) + ... + """ return find_datasets(mission='Van Allen Probes (RBSP)', instrument=instrument, label=label) diff --git a/pyspedas/rbsp/load.py b/pyspedas/rbsp/load.py index 8137ec4a..d8187375 100644 --- a/pyspedas/rbsp/load.py +++ b/pyspedas/rbsp/load.py @@ -5,17 +5,18 @@ from .config import CONFIG -def load(trange=['2018-11-5', '2018-11-6'], + +def load(trange=['2018-11-5', '2018-11-6'], probe='a', - instrument='emfisis', + instrument='emfisis', level='l3', - datatype='magnetometer', - suffix='', - cadence='4sec', # for EMFISIS mag data - coord='sm', # for EMFISIS mag data - wavetype='waveform', # for EMFISIS waveform data - rel='rel04', # for ECT data - get_support_data=False, + datatype='magnetometer', + suffix='', + cadence='4sec', # for EMFISIS mag data + coord='sm', # for EMFISIS mag data + wavetype='waveform', # for EMFISIS waveform data + rel='rel04', # for ECT data + get_support_data=False, varformat=None, varnames=[], downloadonly=False, @@ -23,18 +24,82 @@ def load(trange=['2018-11-5', '2018-11-6'], no_update=False, time_clip=False): """ - This function loads Van Allen Probes (RBSP) data; this function is not meant - to be called directly; instead, see the wrappers: - pyspedas.rbsp.emfisis - pyspedas.rbsp.rbspice - pyspedas.rbsp.efw - pyspedas.rbsp.mageis - pyspedas.rbsp.hope - pyspedas.rbsp.rept - pyspedas.rbsp.rps - + Load Van Allen Probes (RBSP) data for various instruments and data levels. + + It is not intended to be called directly. Instead, use the following wrappers for specific instruments: + - pyspedas.rbsp.emfisis + - pyspedas.rbsp.rbspice + - pyspedas.rbsp.efw + - pyspedas.rbsp.mageis + - pyspedas.rbsp.hope + - pyspedas.rbsp.rept + - pyspedas.rbsp.rps + + Parameters + ---------- + trange : list of str + Time range of interest in the format ['YYYY-MM-DD', 'YYYY-MM-DD'] or + ['YYYY-MM-DD/hh:mm:ss', 'YYYY-MM-DD/hh:mm:ss']. Default is ['2018-11-5', '2018-11-6']. + + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' + + instrument : str, default='emfisis' + Name of the instrument. + + level : str, default='l3' + Data level + + datatype : str, default='magnetometer' + Instrument-specific data type. + + suffix : str, default='' + Suffix for the tplot variable names. + + cadence : str, default='4sec' + Data cadence + + coord : str, default='sm' + Data coordinate system. + + wavetype : str, default='waveform' + Type of level 2 waveform data (applicable for WFR and HFR data). + + rel : str, default='rel04' + Data release version (for ECT data). + + get_support_data : bool, default=False + If True, loads data with attribute "VAR_TYPE" of "support_data". + + varformat : str, optional + The file variable formats to load. Accepts wildcard character "*". + + varnames : list of str, optional + List of variable names to load. If not specified, all variables are loaded. + + downloadonly : bool, default=False + If True, downloads the CDF files but does not load them into tplot variables. + + notplot : bool, default=False + If True, returns data in hash tables instead of creating tplot variables. + + no_update : bool, default=False + If True, only load data from the local cache. + + time_clip : bool, default=False + If True, clips the variables to the specified range in trange. + + Returns + ------- + tvars : dict or list + List of created tplot variables or dict of data tables if notplot is True. + + Examples + -------- + This function is not intended to be called directly. """ + if not isinstance(probe, list): probe = [probe] @@ -51,43 +116,45 @@ def load(trange=['2018-11-5', '2018-11-6'], for prb in probe: if instrument == 'emfisis': if datatype == 'density' or datatype == 'housekeeping' or datatype == 'wna-survey': - pathformat = 'rbsp'+prb+'/'+level+'/'+instrument+'/'+datatype+'/%Y/rbsp-'+prb+'_'+datatype+'_'+instrument+'-'+level+'_%Y%m%d_v*.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/' + instrument + '/' + datatype + '/%Y/rbsp-' + prb + '_' + datatype + '_' + instrument + '-' + level + '_%Y%m%d_v*.cdf' elif datatype == 'wfr' or datatype == 'hfr': - pathformat = 'rbsp'+prb+'/'+level+'/'+instrument+'/'+datatype+'/'+wavetype+'/%Y/rbsp-'+prb+'_'+datatype+'-'+wavetype+'_'+instrument+'-'+level+'_%Y%m%d*_v*.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/' + instrument + '/' + datatype + '/' + wavetype + '/%Y/rbsp-' + prb + '_' + datatype + '-' + wavetype + '_' + instrument + '-' + level + '_%Y%m%d*_v*.cdf' else: if level == 'l2' and datatype == 'magnetometer': - pathformat = 'rbsp'+prb+'/'+level+'/'+instrument+'/'+datatype+'/uvw/%Y/rbsp-'+prb+'_'+datatype+'_uvw_'+instrument+'-'+level+'_%Y%m%d*_v*.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/' + instrument + '/' + datatype + '/uvw/%Y/rbsp-' + prb + '_' + datatype + '_uvw_' + instrument + '-' + level + '_%Y%m%d*_v*.cdf' else: - pathformat = 'rbsp'+prb+'/'+level+'/'+instrument+'/'+datatype+'/'+cadence+'/'+coord+'/%Y/rbsp-'+prb+'_'+datatype+'_'+cadence+'-'+coord+'_'+instrument+'-'+level+'_%Y%m%d_v*.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/' + instrument + '/' + datatype + '/' + cadence + '/' + coord + '/%Y/rbsp-' + prb + '_' + datatype + '_' + cadence + '-' + coord + '_' + instrument + '-' + level + '_%Y%m%d_v*.cdf' elif instrument == 'rbspice': - pathformat = 'rbsp'+prb+'/'+level+'/'+instrument+'/'+datatype+'/%Y/rbsp-'+prb+'-'+instrument+'_lev-'+str(level[-1])+'?'+datatype+'_%Y%m%d_v*.cdf' - prefix = 'rbsp'+prb+'_rbspice_'+level+'_'+datatype_in+'_' + pathformat = 'rbsp' + prb + '/' + level + '/' + instrument + '/' + datatype + '/%Y/rbsp-' + prb + '-' + instrument + '_lev-' + str( + level[-1]) + '?' + datatype + '_%Y%m%d_v*.cdf' + prefix = 'rbsp' + prb + '_rbspice_' + level + '_' + datatype_in + '_' elif instrument == 'efw': if level == 'l3': - pathformat = 'rbsp'+prb+'/'+level+'/'+instrument+'/%Y/rbsp'+prb+'_'+instrument+'-'+level+'_%Y%m%d_v??.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/' + instrument + '/%Y/rbsp' + prb + '_' + instrument + '-' + level + '_%Y%m%d_v??.cdf' else: - pathformat = 'rbsp'+prb+'/'+level+'/'+instrument+'/'+datatype+'/%Y/rbsp'+prb+'_'+instrument+'-'+level+'_'+datatype+'_%Y%m%d_v??.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/' + instrument + '/' + datatype + '/%Y/rbsp' + prb + '_' + instrument + '-' + level + '_' + datatype + '_%Y%m%d_v??.cdf' elif instrument == 'mageis': - pathformat = 'rbsp'+prb+'/'+level+'/ect/'+instrument+'/sectors/'+rel+'/%Y/rbsp'+prb+'_'+rel+'_ect-mageis-'+level+'_%Y%m%d_v*.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/ect/' + instrument + '/sectors/' + rel + '/%Y/rbsp' + prb + '_' + rel + '_ect-mageis-' + level + '_%Y%m%d_v*.cdf' elif instrument == 'hope': if datatype == 'moments': - pathformat = 'rbsp'+prb+'/'+level+'/ect/'+instrument+'/'+datatype+'/'+rel+'/%Y/rbsp'+prb+'_'+rel+'_ect-hope-mom-'+level+'_%Y%m%d_v*.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/ect/' + instrument + '/' + datatype + '/' + rel + '/%Y/rbsp' + prb + '_' + rel + '_ect-hope-mom-' + level + '_%Y%m%d_v*.cdf' elif datatype == 'pitchangle': - pathformat = 'rbsp'+prb+'/'+level+'/ect/'+instrument+'/'+datatype+'/'+rel+'/%Y/rbsp'+prb+'_'+rel+'_ect-hope-pa-'+level+'_%Y%m%d_v*.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/ect/' + instrument + '/' + datatype + '/' + rel + '/%Y/rbsp' + prb + '_' + rel + '_ect-hope-pa-' + level + '_%Y%m%d_v*.cdf' elif datatype == 'spinaverage': - pathformat = 'rbsp'+prb+'/'+level+'/ect/'+instrument+'/'+datatype+'/'+rel+'/%Y/rbsp'+prb+'_'+rel+'_ect-hope-sci-'+level+'sa_%Y%m%d_v*.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/ect/' + instrument + '/' + datatype + '/' + rel + '/%Y/rbsp' + prb + '_' + rel + '_ect-hope-sci-' + level + 'sa_%Y%m%d_v*.cdf' elif instrument == 'rept': - pathformat = 'rbsp'+prb+'/'+level+'/ect/'+instrument+'/sectors/'+rel+'/%Y/rbsp'+prb+'_'+rel+'_ect-rept-sci-'+level+'_%Y%m%d_v*.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/ect/' + instrument + '/sectors/' + rel + '/%Y/rbsp' + prb + '_' + rel + '_ect-rept-sci-' + level + '_%Y%m%d_v*.cdf' elif instrument == 'rps': if datatype == 'rps-1min': - pathformat = 'rbsp'+prb+'/'+level+'/rps/psbr-rps-1min/%Y/rbsp'+prb+'_'+level+'-1min_psbr-rps_%Y%m%d_v*.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/rps/psbr-rps-1min/%Y/rbsp' + prb + '_' + level + '-1min_psbr-rps_%Y%m%d_v*.cdf' elif datatype == 'rps': - pathformat = 'rbsp'+prb+'/'+level+'/rps/psbr-rps/%Y/rbsp'+prb+'_'+level+'_psbr-rps_%Y%m%d_v*.cdf' + pathformat = 'rbsp' + prb + '/' + level + '/rps/psbr-rps/%Y/rbsp' + prb + '_' + level + '_psbr-rps_%Y%m%d_v*.cdf' # find the full remote path names using the trange remote_names = dailynames(file_format=pathformat, trange=trange) - files = download(remote_file=remote_names, remote_path=CONFIG['remote_data_dir'], local_path=CONFIG['local_data_dir'], no_download=no_update) + files = download(remote_file=remote_names, remote_path=CONFIG['remote_data_dir'], + local_path=CONFIG['local_data_dir'], no_download=no_update) if files is not None: for file in files: out_files.append(file) @@ -112,4 +179,3 @@ def load(trange=['2018-11-5', '2018-11-6'], tclip(new_var, trange[0], trange[1], suffix='') return tvars - diff --git a/pyspedas/rbsp/rbspice_lib/rbsp_load_rbspice_read.py b/pyspedas/rbsp/rbspice_lib/rbsp_load_rbspice_read.py index e413f476..55cb3f43 100644 --- a/pyspedas/rbsp/rbspice_lib/rbsp_load_rbspice_read.py +++ b/pyspedas/rbsp/rbspice_lib/rbsp_load_rbspice_read.py @@ -10,13 +10,23 @@ def rbsp_load_rbspice_read(level='l3', probe='a', datatype='TOFxEH'): Parameters ---------- - level : str - data level ['l1','l2','l3' (default),'l3pap'] - probe : str - RBSP spacecraft indicator [Options: 'a' (default), 'b'] - datatype : str - RBSPICE data type ['EBR','ESRHELT','ESRLEHT','IBR','ISBR','ISRHELT','TOFxEH' (default),'TOFxEIon','TOFxEnonH','TOFxPHHHELT','TOFxPHHLEHT'], + level : str, default='l3' + data level 'l1','l2','l3' + + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' + + datatype : str, default='TOFxEH' + RBSPICE data type: 'EBR','ESRHELT','ESRLEHT','IBR','ISBR','ISRHELT','TOFxEH' (default),'TOFxEIon','TOFxEnonH','TOFxPHHHELT','TOFxPHHLEHT' but change for different data levels. + + Returns + ------- + None + + Examples + -------- + This function is called within pyspedas.rbsp.rbspice """ if level != 'l1': units_label = '1/(cm^2-sr-s-keV)' diff --git a/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_omni.py b/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_omni.py index c7d89caf..f4f49b31 100644 --- a/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_omni.py +++ b/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_omni.py @@ -18,17 +18,24 @@ def rbsp_rbspice_omni(probe='a', datatype='TOFxEH', level='l3'): Parameters ---------- - probe : str - RBSP spacecraft indicator [Options: 'a' (default), 'b'] - datatype : str - RBSPICE data type ['EBR','ESRHELT','ESRLEHT','IBR','ISBR','ISRHELT','TOFxEH' (default),'TOFxEIon','TOFxEnonH','TOFxPHHHELT','TOFxPHHLEHT'], - but change for different data levels. - level : str - data level ['l1','l2','l3' (default),'l3pap'] + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' + + datatype: str, default='TOFxEH' + RBSPICE data type: 'EBR','ESRHELT','ESRLEHT','IBR','ISBR','ISRHELT','TOFxEH','TOFxEIon','TOFxEnonH','TOFxPHHHELT','TOFxPHHLEHT' + Values depends on different data levels. + + level : str, default='l3' + data level: 'l1','l2','l3' Returns ------- - Tplot variables created + out : list + Tplot variables created + + Examples + -------- + This function is called within pyspedas.rbsp.rbspice """ if probe is None: probe = 'a' diff --git a/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_pad.py b/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_pad.py index 527e4bce..3fea63b2 100644 --- a/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_pad.py +++ b/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_pad.py @@ -19,22 +19,38 @@ def rbsp_rbspice_pad(probe='a', datatype='TOFxEH', level='l3', energy=[0, 1000], Parameters ---------- - probe : str - RBSP spacecraft indicator [Options: 'a' (default), 'b'] - datatype : str - desired data type [Options: 'TOFxEH' (default), 'TOFxEnonH'] - level : str - data level ['l1','l2','l3' (default),'l3pap'] - energy : list - user-defined energy range to include in the calculation in keV [default = [0,1000]] - bin_size : float - desired size of the pitch angle bins in degrees [default = 15] - scopes : list + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' + + datatype: str, default='TOFxEH' + desired data type: 'TOFxEH', 'TOFxEnonH' + + level : str, default='l3' + data level: 'l1','l2','l3' + + energy : list, default=[0,1000] + user-defined energy range to include in the calculation in keV + + bin_size : float, default=15 + desired size of the pitch angle bins in degrees + + scopes : list, optional string array of telescopes to be included in PAD [0-5, default is all] - + Returns ------- - Tplot variables created + out : list + Tplot variables created + + Examples + -------- + >>> rbspice_vars = pyspedas.rbsp.rbspice(trange=['2018-11-5', '2018-11-6'], datatype='TOFxEH', level='l3') + >>> tplot('rbspa_rbspice_l3_TOFxEH_proton_omni_spin') + + # Calculate the pitch angle distributions + >>> from pyspedas.rbsp.rbspice_lib.rbsp_rbspice_pad import rbsp_rbspice_pad + >>> rbsp_rbspice_pad(probe='a', datatype='TOFxEH', level='l3') + >>> tplot('rbspa_rbspice_l3_TOFxEH_proton_omni_0-1000keV_pad') """ if datatype == 'TOFxEH': species = 'proton' diff --git a/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_pad_spinavg.py b/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_pad_spinavg.py index bddcd4a1..a1fd07a7 100644 --- a/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_pad_spinavg.py +++ b/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_pad_spinavg.py @@ -14,28 +14,47 @@ def rbsp_rbspice_pad_spinavg(probe='a', datatype='TOFxEH', level='l3', species=None, energy=[0, 1000], bin_size=15., scopes=None): """ - Calculates spin-averaged PADs for the RBSPICE instrument + Calculates spin-averaged pitch angle distributions using data from the + RBSP Radiation Belt Storm Probes Ion Composition Experiment (RBSPICE) - Parameters + Parameters ---------- - probe : str - RBSP spacecraft indicator [Options: 'a' (default), 'b'] - datatype : str - desired data type [Options: 'TOFxEH' (default), 'TOFxEnonH'] - level : str - data level ['l1','l2','l3' (default),'l3pap'] - species : str - desired ion species [Options: 'proton' (default), 'helium', 'oxygen'] - energy : list - user-defined energy range to include in the calculation in keV [default = [0,1000]] - bin_size : float - desired size of the pitch angle bins in degrees [default = 15] - scopes : list + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' + + datatype: str, default='TOFxEH' + desired data type: 'TOFxEH', 'TOFxEnonH' + + level : str, default='l3' + data level: 'l1','l2','l3' + + species : str, default='proton' + desired ion species: 'proton' , 'helium', 'oxygen' + + energy : list, default=[0,1000] + user-defined energy range to include in the calculation in keV + + bin_size : float, default = 15. + desired size of the pitch angle bins in degrees + + scopes : list, optional string array of telescopes to be included in PAD [0-5, default is all] + Returns -------- - Tplot variables created + out : list + Tplot variables created + + Examples + -------- + >>> rbspice_vars = pyspedas.rbsp.rbspice(trange=['2018-11-5', '2018-11-6'], datatype='TOFxEH', level='l3') + >>> tplot('rbspa_rbspice_l3_TOFxEH_proton_omni_spin') + + # Calculate the pitch angle distributions + >>> from pyspedas.rbsp.rbspice_lib.rbsp_rbspice_pad import rbsp_rbspice_pad_spinavg + >>> rbsp_rbspice_pad_spinavg(probe='a', datatype='TOFxEH', level='l3') + >>> tplot('rbspa_rbspice_l3_TOFxEH_proton_omni_0-1000keV_pad_spin') """ if level != 'l1': units_label = '1/(cm^2-sr-s-keV)' diff --git a/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_spin_avg.py b/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_spin_avg.py index 0f004622..7d73873d 100644 --- a/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_spin_avg.py +++ b/pyspedas/rbsp/rbspice_lib/rbsp_rbspice_spin_avg.py @@ -18,16 +18,23 @@ def rbsp_rbspice_spin_avg(probe='a', datatype='TOFxEH', level='l3'): Parameters ---------- - probe : str - RBSP spacecraft indicator [Options: 'a' (default), 'b'] - datatype : str - RBSPICE data type ['TOFxEH' (default),'TOFxEnonH'] - level : str - data level ['l1','l2','l3' (default),'l3pap'] + probe : str or list of str, default='a' + Spacecraft probe name: 'a' or 'b' + + datatype: str, default='TOFxEH' + desired data type: 'TOFxEH', 'TOFxEnonH' + + level : str, default='l3' + data level: 'l1','l2','l3' Returns -------- - Tplot variables created + out, list + Tplot variables created + + Examples + -------- + This function is called within pyspedas.rbsp.rbspice """ if probe is None: probe = 'a' diff --git a/pyspedas/utilities/datasets.py b/pyspedas/utilities/datasets.py index 841366b0..b787a3ce 100644 --- a/pyspedas/utilities/datasets.py +++ b/pyspedas/utilities/datasets.py @@ -2,6 +2,38 @@ def find_datasets(mission=None, instrument=None, label=False): + """ + Find datasets from the Coordinated Data Analysis System (CDAS) based on mission and/or instrument criteria. + + This function queries the CDAS for datasets, optionally filtering by mission and instrument. It can + also display labels for the datasets. + + Parameters + ---------- + mission : str, optional + The name of the mission to filter the datasets. If None, datasets are not filtered by mission. + instrument : str, optional + The name of the instrument to filter the datasets. If None, datasets are not filtered by instrument. + label : bool, default=False + If True, the function prints both the dataset ID and label. If False, only the dataset ID is printed. + + Returns + ------- + None + This function does not return any value. It prints the dataset IDs, and optionally labels, to the console. + + Examples + -------- + >>> find_datasets(mission='MMS', instrument='FGM') + MMS1_FGM_BRST_L2 + MMS1_FGM_SRVY_L2 + ... + + >>> find_datasets(mission='MMS', label=True) + MMS1_ASPOC_SRVY_L2: Level 2 Active Spacecraft Potential Control Survey Data - K. Torkar, R. Nakamura (IWF) + ... + """ + cdas = CdasWs() datasets = cdas.get_datasets(observatoryGroup=mission) for index, dataset in enumerate(datasets):