Data format for time-series contributions to the PET/SIS/ULEIS H,He,e- dataset ------------------------------------------------------------------------------ Version 3: Fri Feb 20 2004 One goal of this format is to ensure that data records contain no letters, colons, slashes, etc. - just space-deliminated numbers. The data file format shall be ASCII text. Note that this leaves the EndOfLIne character(s) undefined, however I don't think it is worth forcing contributors to adhere to a single standard. File naming Convention ---------------------- Data filenames shall consist of the following hyphen-deliminated components, in the following order: EventDate, Spacecraft, Instrument, Intensity/Fluence indicator, and a ".txt" file extension. The EventDate shall be written in the following format: YYYY-MM-DD. Example: 2003-11-02-ACE-ULEIS-Fluence.txt If more than one event occurs on a given day, then the EventDate may be followed by "A", "B", etc. Example: 2003-11-02-SAMPEX-PET-Fluence.txt 2003-11-02-SAMPEX-PET-Fluence.txt This file naming convention facilitates ordering of data files by event in directory listings, etc. File Header ----------- Each data file shall begin with a variable length text header. The header shall contain, at a minimum, the following information: - Title/short description. - Version number. - Date/Time Processed. - A description of each field in the data, and their order. Data Records ------------ The words "BEGIN DATA" shall appear below the header, at the beginning of the line immediately preceding the first data record. Each data record shall occupy a single line in the data file. Fields in a data record shall be space-delimited. Fortran-like formatting where fields may sometimes butt up against each other shall be illegal. Time-stamp fields in data records shall be be in UT time. Each data record shall contain the following fields, in the following order: FieldName Style Units Description/Comments -------------------------------------------------------- SC/Inst int Spacecraft/instrument code StartYear int Years StartFPDayOfYear float Fractional Day-ofYear StartMonth int Months StartDayOfMonth int Days StartHour int Hours StartMin int Minutes StartSec int Seconds EndYear int Years EndFPDayOfYear float Fractional Years EndMonth int Months EndDayOfMonth int Days EndHour int Hours EndMin int Minutes EndSec int Seconds Charge float Species Charge MassNum float Species mass-number. EnergyLow sci MeV/nuc. Lower boundary of energy band EnergyHigh sci MeV/nuc. Upper boundary of energy band EnergyMid sci MeV/nuc. Mid-point of band on log-scale Intensity sci 1/(cm2 Sr sec MeV/nuc.) or Fluence or 1/(cm2 Sr MeV/nuc.) UncIntensity sci 1/(cm2 Sr sec MeV/nuc.) 1-sig inten/fluence uncertainty or UNcFluence or 1/(cm2 Sr MeV/nuc.) UncLo sci 1/(cm2 Sr sec MeV/nuc.) UncHi sci 1/(cm2 Sr sec MeV/nuc.) Counts int Raw counts (non-int values OK) QFlag int TBD quality flag The SC/Inst code shall be a two-or-more digit code. The least-significant digit (the rightmost digit) shall indicate the instrument on the spacecraft. The other digits shall indicate the spacecraft. The following spacecraft and instrument codes are currently defined: Spacecraft Instruments ---------- ----------- ACE 1 EPAM=0 SIS=1 ULEIS=2 IMP8 2 UC=0 GSFC=1 APL=2 SAMPEX 3 LICA=0 MAST=1 PET=2 WIND 4 STEP=0 GOES8 8 EPS=0 GOES9 9 EPS=0 GOES10 10 EPS=0 GOES11 11 EPS=0 GOES12 12 EPS=0 Thus, the SC/Inst code for ACE-ULEIS is 12, and SC/Inst code for GOES11-EPS is 110. Spacecraft codes 5-7 are reserved for future use. For protons and e-, energy and intensity/fluence fields shall have units of MeV and 1/(cm2 Sr sec MeV), respectively. If the intensity/fluence uncertainties are asymmetrical, then UncIntensity/UndFluence shall be set to -9999.9, and UncLo and UncHi shall indicate the lower and upper bounds of the intensity error-bar. If the intensity uncertainties are symmetrical, then UncLo = Intensity - (UncIntensity/2.0) UncHi = Intensity + (UncIntensity/2.0) The Qflag field shall be set to 1 for nominal data. For non-nominal data, the Qflag shall be any number other than 1, and the meaning of each value shall be described in the file header. Records with bad or missing data shall be indicated by -9999.9 in the Intensity, UncIntensity/UncFluence, UncLo, and UncHi fields. Note: the format does not prevent one from including a line at the end of the header to label the data columns, as long as it is before the "BEGIN DATA" line. A Short Example --------------- ACE/SIS 1-hour He Intensities SIS software version 1.0 Date/Time Processed: Wed Feb 18 16:47:40 PST 2004 Note: All timestamps are UT. FieldName Style Units Comments -------------------------------------------------------- SC/Inst int TBD spacecraft/instrument code StartYear int Years StartFPDayOfYear float Fractional Day-of-Year StartMonth int Months StartDayOfMonth int Days StartHour int Hours StartMin int Minutes StartSec int Seconds EndYear int Years EndFPDayOfYear float Fractional Years EndMonth int Months EndDayOfMonth int Days EndHour int Hours EndMin int Minutes EndSec int Seconds Charge int Species Charge MassNum int Species mass-number. 0 for e- EnergyLow sci MeV/nuc. Lower boundary of energy band EnergyHigh sci MeV/nuc. Upper boundary of energy band EnergyMid sci MeV/nuc. Mid-point of band on log-scale Intensity sci 1/(cm2 Sr sec MeV/nuc.) UncIntensity sci 1/(cm2 Sr sec MeV/nuc.) 1-sigma intensity uncertainty UncLo sci 1/(cm2 Sr sec MeV/nuc.) Unused (-9999.9) UncHi sci 1/(cm2 Sr sec MeV/nuc.) Unused (-9999.9) Counts sci Raw counts (non-integer values OK) QFlag int TBD quality flag ( The meaning of the quality flag would be described here. ) Records with bad or missing data shall be indicated by -9999.9 in the Intensity and UncIntensity fields. BEGIN DATA 0 2000 1.0 1 1 0 0 0 2000 1.5 1 1 12 0 0 2 4 1.3e+0 4.0e+00 2.28e+00 7.0e-07 1.0e-07 -9.9999e+03 -9.9999e+03 150 1