The format is line-oriented ASCII. It should be possible to easily
process it using standard Unix-like shell utils like grep, perl,
... Whitespace within lines is allowed, and empty lines are allowed.
Float numbers may written in any way like `10000', `10000.0',
`1.0E+5', `1.0e+5', `.1e+6', `1000000.e-2', `1e+5',
... as known from C and FORTRAN I/O.
Although not part of the standard, the authors suggest the GNU gzip format for handling compressed data.
A line should not exceed 255 characters. We suggest less then 80 characters for enhanced readability. If line is longer than maximum allowed length, it can be continued on the next non-comment line (see section Units and conventions).
All coordinates and times should be consistent within a file, e.g.:
If times need to be shifted it must be done such that all times in the event (trigger, hits, tracks) have to be shifted by the same amount.
Coordinates of spase, amanda_a, amanda_b must refer to the same origin even after some transformation.
All kinds of AMANDA events are to be included: muon, snmp/GRB, housekeeping, ...
The format is "basically" the same for all steps of analysis
for both, MC and data. Most parts of format are optional. Raw data
won't have a calibration or geometry block, while event generator programs
(e.g. airshow) won't produces hits.
The basic structure for data file is as follows:
V 2000.X.Y ! Header line including version, must be present ARRAY ... ! Detector type and common geometry information, must be present (History information) (Calibration and geometry constants) (Other definitions, e.g. trigger or user blocks) ES ... ! Slow event header (Status information) EE ! End of event ... EM ... ! Muon event header (MC particle information) (OM hit information) (Fit track/shower information) (User and other information) EE ! End of event ... END ! End of file
Ellipses between events mean that event information repeats. Indentation above is only for clarity. Lines in parentheses () are optional, while muon and slow events can come in any order. A few examples can be seen below.
The format is whitespace-invariant within a line.
All units are considered to be in nanoseconds, meters, and GeV, except event times and event times corrections which are given in seconds. Planar angles are in degrees and solid angles are in steradians. Rates are in Hertz. Relative numbers are 0.0 to 1.0 (not percent). Calibrated amplitude is given in photoelectrons, while all uncalibrated values (including TDCs and TOTs) are given in raw data counts specific for that variable.
Data is stored in form of numbers and single word strings. If Required, numbers can be treated as strings. All numbers are considered to be float point numbers (unless explicitly stated otherwise in this document), but they don't require trailing point if not needed (e.g. `10' and `10.' are both valid).
Please note: No constraints are placed on how software processing F2000 data deals with numerical values. Value `10' can be treated as float, double, integer, or anything else.
All numbers should be in decimal format, i.e. binary, octal, and hexadecimal representations are not allowed.
NaN
?
*
inf and -inf
The coordinate system used is right-handed, with the Z direction upward and the X direction eastward (grid-east direction at the South and North poles). The origin of the AMANDA coordinate system is at module 10 on string 4 (OM 70) as defined by geometry files prior to 1998. Currently, AMANDA coordinate system places OM 70 at (1.80,-1.48,-25.90). All coordinates (including SPASE) should be written with respect to this origin.
The numbering used is 1..n. C-like numbering 0..(n-1) is
NOT allowed.
The channel naming convention is following:
channel number = OM.i where OM = OM number i = 1, 2, 3, ... for different readout channels of the same OM The backward compatibility is insured through definition channnel number = OM == OM.1
It should be noted that prior to version 1.4, the secondary channel redout was encoded by 10000+OM number. This was never an official convention, but user should be aware of existance of such numbering scheme.
No line should exceed 255 characters. If data line is too long, it can be
continued on the next line which should start with &.
STATUS spase word1 word2 ... word10 ! A very long line & word11 word12 ! Continuation of STATUS spase
A line can be broken only between words. Any number of comment lines and blank lines can appear between a line and its continuation. Comment lines can't be continued (they should be split into multiple comments).
Important: A continued line is logically considered to be only one line, irregardless of its actual length. Upper limit of 255 characters is imposed to prevent any incompatibilities with text processing software.
id
word1 .. wordn
value1 .. valuen
The very first line MUST be a version line indicating which format version is used in the file. Nothing (no comments) can preceed this line and this line should not be indented (i.e. `V' should be first character of data stream).
V 2000.x.y
int x
int y
Comments are all lines which start with a non-letter character, like
: ; # * ! % $ / , . " ', except &. There is no need for a space
after this first character, e.g. `/*' or `//' are also
valid.
Inline comments start with ! only, commenting out the rest of the line.
Lines can have blank spaces at the beginning, except for the first V header
line. Inline comments are not necessarily preserved by programs processing
data.
Blank lines are allowed after the version line. Similarly, comments are only allowed after the version line.
! comments
string comments
To enable the possibility of backtracing the analysis procedure, the usage of
history lines is strongly recomended. They indicate which programs
produced the current output file.
History information is specified with the HI tag.
HI program (version) parameters
string program
string version
string parameters
A program should add its history line after all existing history lines. That way the history reads from top to bottom.
Example:
V F2000.1.1 ! File created 10 Oct 1966 by RAVEN/genevent, user SERAP on ALIZARIN. ! Atmospheric neutrinos in this puppy... HI genevent (1.1) -atmos_nus -N1000 ! Reconstructed by wiebusch@ifh.de using recoos (SiEGMuND 1.666) HI recoos (1.19) -W -V -bxV -X w=tanze
All information relating to all events in the file is stored in the header. This includes OM positions, channel calibration data, user and other object definitions.
The detector block consists of the ARRAY line indicating the detector type and common geometry information. This line MUST appear in an F2000 data file.
ARRAY detector longitude lattitude depth nstrings nmodule
string detector
float longitude, lattitude
float depth
int nstrings
int nmodule
The calibration block starts with a line indicating which type of calibration has been performed, followed by one line per calibration of the different channel properties, and by an event time calibration line if there was such a calibration.
KH ADC TDC TOT UTC GEO
ADC
TDC
TOT
UTC
GEO
GEO option was not present.
Instead, the convention was that the presence of OM lines indicates the
performed geometry calibration.
OM number nr_str string x y z orientation type serial sensit thresh
int number
nmodule
nr_str
int string
nstr
float x y z
string orientation
up" for upward looking, "dn" for downward
looking and a string like "+0+180" for other orientations (e.g. this
OM is vertical, with phi equal to 180 degrees).
string type
string serial
? if not available.
float sensit
float thresh
KADC number pedestal beta linearity
int number
float pedestal
float beta
float linearity
KTDC number beta shift alpha
number
float beta
float shift
float alpha
KTOT number pedestal beta linearity
int number
float pedestal
float beta
float linearity
KUTC unit offset
string unit
GPS, UTC, DAQ indicating the
source of the event time (GPS clock, UTC module or DAQ system)
float offset
To give the largest flexibility for encoding different data in F2000 format definition mechanism provides ability to customize what information is stored with each event in the data file. The format currently provides four predefined information categories, plus catch-all `user' defined category. All "define-type" information lines used in any event in the data file have to be defined in the header.
Each definition consists of two lines. DEF line specifies exact
formating of corresponding line to be found in data events. The suggested use
is to provide variable names for values found in data events. PAR line
specifies certain fixed values associated with definition that hold true for
all events in the data file. PAR line can't preceed or appear without
accompanying DEF line.
Trigger lines are intended to represent conditions that certain event satisfies. They can be split into two categories;
In reality, the distinction is not that clear cut since MC code can simulate hardware triggers, etc.
TRIG_DEF id word1 word2 ...
TRIG_DEF id tag word1 word2 ..." up to version
1.2).
string id
string word1 word2 ...
TRIG line
TRIG_DEF spase1_coinc tdc-time spase-gps
TRIG_PAR id tag1=value tag2=value ...
string id
TRIG_DEF definition).
string tag=value
TRIG_PAR amab-4 type=majority window=2000 fold=8
Status lines are intended to represent state of detector and/or data gathering and processing system at the time when the data event was recorded. For example, this can be current temperature inside counting room, information on malfunction of certain data channels, or anything else.
STAT_DEF id word1 word2 ...
string id
string word1, word2, ...
STATUS line.
STAT_DEF hv channel crate hv_request hv_supply
STAT_PAR id tag1=value tag2=value ...
string id
STAT_DEF definition).
string tag=value
STAT_PAR hv crate1_model=1440 crate2_model=1458
Fit definitions declare which fits have been performed on data.
Important:
FIT_DEFdoesn't specify formating ofFITlines which is predefined by F2000 format (see section Event reconstruction results). It specifies formating ofFRESULTline associated with given fit.
FIT_DEF id word1 word2 ...
string id
string word1, word2, ...
FRESULT line.
FIT_DEF rdmc-jk_1 rchi2 prob chi2
FIT_PAR id tag1=value tag2=value ...
string id
FIT_DEF definition).
string tag=value
FIT_PAR rdmc-jk_1 fitter=recoos type=linefit
MC lines are intended to encode event specific MC information, e.g. various probabilities and weights associated with an event.
MC_DEF id word1 word2 ...
string id
string word1, word2 ...
MC line.
MC_DEF corsika_1 weight seed1
MC_PAR id tag1=value tag2=value ...
string id
MC_DEF definition).
string tag=value
MC_PAR corsika_1 generator=corsika rng_type=run3
If predefined categories don't satisfy users' needs, users are allowed to define user specific lines. All responsibility for properly identifying information on those lines is up to the users. To increase flexibility, user defined information is allowed for entire events and for specific hits. See section Event user information, for more details.
USER_DEF id word1 word2 ...
string id
string word1, word2 ...
US line.
USER_PAR id tag=value, ...
string id
USER_DEF definition).
string tag=value
Slow events are intended to store information about detector and/or data
gathering and processing system in continual fashion independent from
muon events. They can be also used to segment and
keep track of muon event data in non-file oriented chunks.
Each slow event starts with ES header line and it ends with an EE
line. Presently, slow events are only allowed to contain status lines.
Muon events are indended for recording data coming out of main experimental DAQ and for MC simulation of such data. All additional information produced by subsequent processing of such events is also stored inside events.
Please note: Muon event is a historical misnomer. Data contained in these events is allowed to be generated by any particle or calibration device emitting or simulating light inside of detector.
Each muon event starts with an EM header line and ends with an EE
line. Event can contain generated tracks and showers, hit information,
reconstruction results, all defined lines, and hit related info lines.
ES name year day seconds
string name
int year
int day
float seconds
EM enr run year day time tshift
int enr
int run
int year
int day
float time
float tshift
tshift here
TR nr parent type xstart ystart zstart zenith azimuth length energy time
int nr
int parent
string type
float xstart, ystart, zstart
float zenith, azimuth
zenith=0 is a vertical downward going
track.
float length
inf.
float energy
? if not available.
float time
xstart, ystart, zstart.
HT ch adc id parent le tot
int ch
float adc
* for repeated value)
int id
int parent
N for noise).
For real data this should always be ?.
float le
float tot
Under certain circumstances it is important to store information,
which hits had been used by a trigger or a fit. This is possible
by adding of USES lines after a TRIG or a FIT line.
A USES line relates to the closest preceeding TRIG or
FIT line in the event.
Please note: To insure backward version compatibility (line continuation was not allowed before version 1.4), multiple
USESline may be used to list all hits in the case when more than 255 characters are needed. However, this use is now discouraged and line continuation should be used instead.
USES word1 word2 ...
string word1, word2, ...
word can
be either a hit id (e.g. `19') or a hit id range (e.g. `21-31')
implying that all hits between 21 and 31 have been used, including 21 and 31
(i.e. range [21-31]).
TRIG id value1 value2 ...
string id
TRIG_DEF line in the header
float value1, value2, ...
TRIG_DEF line in the header
FIT id type xstart ystart zstart zenith azimuth time length energy
string id
FIT_DEF line in the header.
string type
float xstart, ystart, zstart
float zenith, azimuth
zenith=0 is a vertical downward going
fit.
float length
inf.
float energy
? if not available.
float time
xstart, ystart, zstart.
FRESULT id value1 value2 ...
int id
FIT_DEF line in the header.
float value1, value2, ...
FIT_DEF line in the header.
USES line, section Hit related information.
Please note:
FRESULTline can't appear without accompanyingFITline.
STATUS id value1 value2 ...
string id
STAT_DEF line in the header.
float value1, value2, ...
STAT_DEF line in the header.
User defined lines can refer to either entire event or only to a specific hit
in the event. If a US line immediately follows HT line (ignoring
any comment lines), that user defined line is associated with that specific
hit. Otherwise the user defined line refers to the entire event.
US id value1 value2 ...
string id
USER_DEF line in the header.
float value1, value2, ...
USER_DEF line in the header.
MC id value1 value2 ...
string id
MC_DEF line in the header.
float value1, valu2, ...
MC_DEF line in the header.
EE
Go to the first, previous, next, last section, table of contents.