This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
PROCEDURE:
mms_add_cdf_versions
PURPOSE:
Adds MMS CDF version #s to plots (for version tracking)
INPUT:
instrument: name of the instrument that we're adding the version #s for
versions: [n, 3] array of CDF version #s - returned by 'versions' keyword
in load routines; where n is the number of CDF files loaded
KEYWORDS:
data_rate: include a data rate on the plot
right_align: start placing version #s strings to the bottom right of the
plot instead of the bottom left
top_align: start placing version #s strings on the top of the figure
instead of the bottom
charsize: character size; default is 1
reset: reset the position of the labels to the starting point
EXAMPLE:
MMS> mms_load_fpi, versions=fpi_versions
MMS> tplot, 'mms3_des_energyspectr_par_fast'
MMS> mms_add_cdf_versions, 'fpi', fpi_versions
NOTES:
1) Requires IDL 8.0+ to work
2) the default location of the version #s is the bottom left;
you can change this using the /right and /top keywords
3) does not include duplicate version #s for the same instrument
e.g., if you load FPI data from 7 v2.1.0 files, only one 'FPI v2.1.0'
will be included
$LastChangedBy: egrimes $
$LastChangedDate: 2018-06-27 09:18:53 -0700 (Wed, 27 Jun 2018) $
$LastChangedRevision: 25404 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/cdf/mms_add_cdf_versions.pro $
(See projects/mms/common/cdf/mms_add_cdf_versions.pro)
mms_cdf2tplot ,files,varformat=varformat
Keywords:
VARFORMAT = PATTERN ; PATTERN should be a string (wildcards accepted) that will match the CDF variable that should be made into tplot variables
PREFIX = STRING ; String that will be pre-pended to all tplot variable names.
SUFFIX = STRING ; String appended to end of each tplot variable created.
VARNAMES = named variable ; CDF variable names are returned in this variable
/GET_SUPPORT_DATA ; Often required to get support data if the CDF file does not have all the needed depend attributes
record=record if only one record and not full cdf-file is requested
load_labels=load_labels ;copy labels from labl_ptr_1 in attributes into dlimits
resolve labels implemented as keyword to preserve backwards compatibility
Author: Davin Larson - 20th century
Forked for MMS, 10/22/2015, egrimes@igpp
$LastChangedBy: egrimes $
$LastChangedDate: 2017-01-05 17:08:07 -0800 (Thu, 05 Jan 2017) $
$LastChangedRevision: 22512 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/cdf/mms_cdf2tplot.pro $
(See projects/mms/common/cdf/mms_cdf2tplot.pro)
This is a new routine that needs further testing, development, and enhancements. PROCEDURE: mms_cdf_info_to_tplot, cdfi Purpose: Creates TPLOT variables from a CDF structure (obtained from "CDF_LOAD_VAR") This routine will only work well if the underlying CDF file follows the SPDF standard. Written by Davin Larson Forked for MMS, 10/22/2015, egrimes@igpp $LastChangedBy: egrimes $ $LastChangedDate: 2018-06-01 11:45:12 -0700 (Fri, 01 Jun 2018) $ $LastChangedRevision: 25314 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/cdf/mms_cdf_info_to_tplot.pro $
(See projects/mms/common/cdf/mms_cdf_info_to_tplot.pro)
FUNCTION cdfi = mms_cdf_load_vars(file)
INPUT:
file = CDF filename(s)
OUTPUT:
CDFI = A structure containing pointers to the data and attributes
for the files, with tags:
CDFI.FILENAME = The filename(s)
CDFI.INQ = A structure with information about the file:
CDFI.INQ.NDIMS = CDF Dims attribute, for rVariables typically 0
(rVariables are rarely used anymore See http://cdf.gsfc.nasa.gov/html/FAQ.html#intro)
CDFI.INQ.DECODING = 'HOST_DECODING' (can be network or host)
CDFI.INQ.ENCODING = 'NETWORK_ENCODING' (can be network or host)
CDFI.INQ.MAJORITY = 'ROW_MAJOR' (can be row or column)
CDFI.INQ.MAXREC = Max number of records (Default is -1)
CDFI.INQ.NVARS = number of rVariables, usually 0
CDFI.INQ.NZVARS = number of zVariables, usually all of them
CDFI.INQ.NATTS = number of variable attributes
CDFI.INQ.DIM = dimensions of rVariables
CDFI.g_atttributes = CDF global attributes, structure varies
Here is a sample from THEMIS EFI:
PROJECT STRING 'THEMIS'
SOURCE_NAME STRING 'THA>Themis Probe A'
DISCIPLINE STRING 'Space Physics>Magnetospheric Science'
DATA_TYPE STRING 'EFI'
DESCRIPTOR STRING 'L2>L2 DATA'
DATA_VERSION STRING '1'
PI_NAME STRING 'V. Angelopoulos, J. Bonnell & F. Mozer'
PI_AFFILIATION STRING 'UCB, NASA NAS5-02099'
TITLE STRING 'Electric Field Instrument (EFI) Measurements'
TEXT STRING 'THEMIS-A: Electric Field Instrument (EFI) Electric field measurements. The L2 product is a 3D estimate of'...
INSTRUMENT_TYPE STRING 'Electric Fields (space)'
MISSION_GROUP STRING 'THEMIS'
LOGICAL_SOURCE STRING 'tha_l2_efi'
LOGICAL_FILE_ID STRING 'tha_l2_efi_20131001_v01'
LOGICAL_SOURCE_DESCRIPTION
STRING 'Spacecraft-collected (EFI) Electric field'
TIME_RESOLUTION STRING '3-1/8s'
RULES_OF_USE STRING 'Open Data for Scientific Use'
GENERATED_BY STRING 'THEMIS SOC'
GENERATION_DATE STRING 'Sun Oct 6 03:11:38 2013'
ACKNOWLEDGEMENT STRING 'NASA Contract NAS5-02099'
MODS STRING 'Rev- 2009-09-16'
ADID_REF STRING 'NSSD0110'
LINK_TEXT STRING Array[3]
LINK_TITLE STRING Array[3]
HTTP_LINK STRING Array[3]
FILE_NAMING_CONVENTION
STRING 'source_descriptor_datatype'
CAVEATS STRING 'See THEMIS website for caveats'
VALIDITY STRING 'to be validated'
VALIDATOR STRING 'tbd'
VALIDATE STRING 'Compatible with the ISTP CDF Standards'
INST_MOD STRING 'THM>xxxx'
PARENTS STRING 'xxxx'
INST_SETTINGS STRING 'Not used'
SOFTWARE_VERSION
STRING '13273'
CDFI.NV = Number of variables
CDFI.VARS = AN array of CDFI.NV structures, one for each zvariable:
CDFI.VARS.NAME = The variable name
CDFI.VARS.NUM = The index of the given variable in the cdfi.vars array
CDFI.VARS.IS_ZVAR = 1 for a zVariable
CDFI.VARS.DATATYPE = The data type, e.g.'CDF_FLOAT'
CDFI.VARS.TYPE = The numerical IDL data type (float is 4, etc...)
CDFI.VARS.NUMATTR = -1, Not sure about this one, returned from CDF_VARGET
CDFI.VARS.NUMELEM = Number of elements in a record, returned from CDF_VARGET
CDFI.VARS.RECVARY = Set to 1 if variable varies from record to record
CDFI.VARS.NUMREC = the number of records input.
CDFI.VARS.NDIMEN = the number dimensions in the data
CDFI.VARS.D = A six-element array with the number of dimensions for
each index
CDFI.VARS.DATAPTR = A pointer to the data array:
CDFI.VARS.ATTRPTR = A pointer to the variable attributes
structure for each variable. Content varies,
here is a sample from THEMIS EFI Electric
field data:
CATDESC STRING 'EFF_DOT0 (fast-survey, 1/8 sec time resolution, using E dot B=0) electric field vector in GSM coordinates'...
FIELDNAM STRING 'EFF_DOT0 (fast-survey, 1/8 sec time resolution, using E dot B=0) electric field vector in GSM coordinates'...
FILLVAL FLOAT NaN
VALIDMIN FLOAT Array[3]
VALIDMAX FLOAT Array[3]
VAR_TYPE STRING 'data'
DISPLAY_TYPE STRING 'time_series'
FORMAT STRING 'E13.6'
LABL_PTR_1 STRING 'tha_eff_dot0_gsm_labl'
UNITS STRING 'mV/m'
DEPEND_TIME STRING 'tha_eff_dot0_time'
DEPEND_EPOCH0 STRING 'tha_eff_dot0_epoch0'
DEPEND_0 STRING 'tha_eff_dot0_epoch'
DEPEND_1 STRING 'tha_eff_dot0_gsm_compno'
VAR_NOTES STRING 'Units are in mV/m'
COORDINATE_SYSTEM
STRING 'GSM'
REPRESENTATION_1
STRING 'Rep_xyz_gsm'
TENSOR_ORDER STRING '1'
AVG_TYPE STRING 'standard'
PROPERTY STRING 'vector'
SC_ID STRING 'a'
SCALE_TYP STRING 'linear'
DICT_KEY STRING 'electric_field>vector_GSM'
SI_CONVERSION STRING '1e-3>V/m'
LABEL_1 STRING 'tha_eff_dot0_gsm_labl'
Each variable may have a different set of attributes, but this
example is a minimal structure that will be ISTP compliant.
KEYWORDS:
VARFORMAT = string or string array: a string or string array (which may contain wildcard
characters) that specifies the CDF variable names to load. Use
'VARFORMAT='*' to load all variables. NOTE
THAT VARFORMAT MUST BE SET IF YOU ACTUALLY
WANT TO READ DATA.
VARNAMES = named variable ;output variable for variable names that were loaded.
SPDF_DEPENDENCIES : Set to 1 to have SPDF defined dependent variables also loaded.
VAR_TYPE = string or string array; Variables that have a VAR_TYPE matching these strings will
be loaded.
CONVERT_INT1_TO_INT2 Set this keyword to convert signed one byte to signed 2 byte integers.
This is useful because IDL does not have the equivalent of INT1 (bytes are unsigned)
RECORD: Specify the record index where you want to start reading. By default, this option will read one record.
NUMBER_RECORDS: Specify the number of records that you want to read. By default, this option will begin at record zero.
Note: Record & Number_Records can be used together to specify a range of records to be read.
Author: Davin Larson - 2006
Forked for MMS, 10/22/2015, egrimes@igpp
Side Effects:
Data is returned in pointer variables. Calling routine is responsible for freeing up heap memory - otherwise a memory leak will occur.
$LastChangedBy: egrimes $
$LastChangedDate: 2018-11-19 16:12:09 -0800 (Mon, 19 Nov 2018) $
$LastChangedRevision: 26155 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/cdf/mms_cdf_load_vars.pro $
(See projects/mms/common/cdf/mms_cdf_load_vars.pro)
Filter MMS file names by time and version. File names are assumed to be identical
except in the TSTART and VERSION fields.
:Params:
FILENAMES: in, required, type=string/strarr
Names of files to be filtered.
:Keywords:
COUNT: out, optional, type=integer
Number of output files that passed filter.
TRANGE: in, optional, type=strarr(2), default=time_string(timerange())
Time interval over which to select files.
MAJOR_VERSION: in, optional, type=boolean, default=0
If set, only the latest major version of each file is returned. Cannot
be used with `MIN_VERSION`, LATEST_VERSION or `VERSION`
LATEST_VERSION: in, optional, type=boolean, default=0
If set, only the latest version of each file is returned. Cannot
be used with `MIN_VERSION` or `VERSION`
MIN_VERSION: in, optional, type=string
Minimum file version to accept, formatted as 'X.Y.Z', where
X, Y, and Z are integers. Cannot be used with `LATEST_VERSION`
or `VERSION`.
VERSION: in, optional, type=string
Version of files to accept, formatted as 'X.Y.Z', where
X, Y, and Z are integers. Cannot be used with `LATEST_VERSION`
or `MIN_VERSION`.
:Returns:
FILES_OUT: Those files within `FILENAMES` that pass the filter criterion.
LOADED_VERSIONS: The CDF version #s
$LastChangedBy: egrimes $
$LastChangedDate: 2017-09-26 12:18:29 -0700 (Tue, 26 Sep 2017) $
$LastChangedRevision: 24031 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/mms/common/cdf/unh_mms_file_filter.pro $
(See projects/mms/common/cdf/unh_mms_file_filter.pro)