GAMOS 5.1.0 User's Guide | ||
---|---|---|
<<< Previous | Analysis (extracting data) | Next >>> |
The data users are user actions that use the data to fill histograms or to dump them in text or binary files or dump them in the screen. There is one user action for each of the five types of information objects (step, track, event, run and secondary tracks), and one user action for each of the four actions, making in total twenty user actions. There is also a user action to dump data in a ROOT Tree; its behaviour is explained in a dedicated section below. We will describe in this section the available data users and how they behave with the different data types mentioned above.
The data can also be used to filter on an interval of values, in classifiers to give a different classification index in different user-defined intervals and in scorers to score the data values. These three usages are explained in the corresponding sections.
The behaviour of each of the data users depends on one side on the type of information object they manage and on the other side on the type of output provided.
The behaviour of each of the data users for each of the information objects is the following:
The Step data users implement a UserSteppingAction method, which extracts the data at each track step, from the G4Step object.
The Track data users implement a PostUserTrackingAction method, which extracts the data at the end of the current track step, from the G4Track object (equal to the current track status). For the data of type Initial the data is extracted from the vertex information of the G4Track object. For the data of type Accumulated these data users implement a UserSteppingAction method, which accumulates the data at each track step, and a PreUserTrackingAction, which initializes the data to 0; the PostUserTrackingAction uses the accumulated data, instead of extracting the data from the G4Track object.
The SecondaryTrack data users implement a UserSteppingAction method, which extracts the data at each track step, from the G4Track object of all secondary tracks created in the step. When setting filters or classifiers to one of these data users you have to remember that they are applied by default to the primary tracks; if you want to applied them to the secondary tracks you have to explicitly do it (see sections on Filters and Classifiers)
The Stack data users implement a ClassifyNewTrack method, which extracts the data when the tracks are taken from the stack, from the G4Track object.
The Event data users implement a EndOfEventAction method, which extracts the data at the end of the event, from the G4Event object. For the data of type Initial the data is extracted from the information of the first primary particle of the first primary vertex. For the data of type Accumulated these data users implement a UserSteppingAction method, which accumulates the data at each track step, and a BeginOfEventAction, which initializes the data to 0; the EndOfEventAction uses the accumulated data, instead of extracting the data from the G4Event object.
The Run data users implement a EndOfRunAction method, which extracts the data at the end of the run, from the G4Run object. For the data of type Accumulated these data users implement a UserSteppingAction method, which accumulates the data at each track step, and a BeginOfRunAction, which initializes the data to 0; the EndOfRunAction uses the accumulated data, instead of extracting the data from the G4Run object.
Note: the data of type Initial is printed (or used to fill an histogram) at the end of track, event or run, with the aim of having together all the information relevant to an object. This behaviour can be changed, so that this data is print at the start with the parameter
/gamos/setParam DATA_USER_NAME:UseAtInitial 1
The behaviour of each of the data users for each of the output type provided is the following:
Histograms: the histogram data users (i.e. GmStepDataHistosUA, GmTrackDataHistosUA, GmSecondaryTrackDataHistosUA, GmStackDataHistosUA, GmEventDataHistosUA, GmRunDataHistosUA,) fill histograms with the data values. By default 1-dimensional histograms are filled but if several data are used at the same type other histogram types are possible: if a 2-dimensional histogram is required the names of the two data have to be separated by .vs.; if a 1-dimensional profile histogram is required the names of the two data have to be separated by .prof.; if a 2-dimensional profile histogram is required the names of the three data have to be separated by .vs. and .prof..
For example:
FinalKineticEnergy.vs.InitialKineticEnergy will fill a 2D histogram.
FinalKineticEnergy.prof.InitialKineticEnergy will fill a 1D profile histogram.
FinalKineticEnergy.vs.InitialKineticEnergy.prof.InitialPositionZ will fill a 2D profile histogram.
The name of the histogram file is given by the name of the data user plus the filters and classifiers plus the histogram type (i.e. .root or .csv. It can be changed with the parameter:
/gamos/setParam DATA_USER_NAME:FileName NEW_FILE_NAME
For example:
/gamos/userAction GmStepDataHistosUA GmGammaFilter
will produce a file named GmStepDataHistosUA_GmGammaFilter.root, whose name can be changed with the command:
/gamos/setParam GmStepDataHistosUA_GmGammaFilter:FileName NEW_FILE_NAME
to produce a file named NEW_FILE_NAME.root
Text files: These data users (i.e. GmStepDataTextFileUA, GmTrackDataTextFileUA, GmSecondaryTrackDataTextFileUA, GmStackDataTextFileUA, GmEventDataTextFileUA, GmRunDataTextFileUA) dump the data values into text files. A line is written for each call to the data user object (i.e. each G4Step, G4Track, ...). The text file is indeed a CSV (Comma Separated Value) file; this means that values are separated by commas and string values are surrounded by double quotes.
Optionally a header line can be written containing the names and order of the data to be written. With the aim of clearly distinguishing it, the first word of the header is always HEADER:. The second word is the number of words, and then the data names. To select this option the following parameter has to be used:
/gamos/setParam FILE_NAME:WriteHeaderData 1
The name of the text file is given by the name of the data user plus the filters and classifiers plus (i.e. .out. It can be changed with the parameter:
/gamos/setParam DATA_USER_NAME:FileName NEW_FILE_NAME
For example:
/gamos/userAction GmStepDataTextFileUA GmGammaFilter
will produce a file named GmStepDataTextFileUA_GmGammaFilter.out, whose name can be changed with the command:
/gamos/setParam GmStepDataTextFileUA_GmGammaFilter:FileName NEW_FILE_NAME
to produce a file named NEW_FILE_NAME.out
Binary files: These data users (i.e. GmStepDataBinFileUA, GmTrackDataBinFileUA, GmSecondaryTrackDataBinFileUA, GmStackDataBinFileUA, GmEventDataBinFileUA, GmRunDataBinFileUA,) dump the data values into binary files. Data of integer type are written as int, occupying four bytes. Data of double type are written as float (for space savings), occupying four bytes (NOTE: in case you want to write all your data as double, you just have to replace float by double in the four WriteBin(...) methods in the file GamosCore/GamosData/Data/src/GmVData.cc, and recompile GAMOS). Data of string type are written as a list of char; each string data has a default number of characters, that can be overridden with the parameter:
/gamos/setParam DATA_NAME:NumberOfChars NCHARS
To allow checking the format when the file is read back, specially useful if the file is read in a different computer system than the one where it was written, or by another program than GAMOS, a check line is read. This check line consists on first an L or B character, depending on whether the computer system uses little endian or big endian; second the integer 1234567890 is written, occupying four bytes; third the float 3.40282e+38 is written, occupying four bytes, last the double 1.79769e+308 is written, occupying eight bytes.
Optionally four other headers can be written after the first check line. If any header is being written before then four integer numbers are always written, whose values are 0 or 1 depending if the corresponding header is written.
The first optional header serves to check that your software system is able to read the file, which you may have written using another system. It writes first a char equal to L or B depending if the system uses little endian or big endian convention. Then it writes as an int the nubmer 1234567890, as a float the number 3.40282e+38 and as a double the number 1.79769e+308. You should check that you read back those numbers when reading your file. To write this header the following parameter has to be used:
/gamos/setParam FILE_NAME:WriteHeaderCheck 1
The second optional header contains the names and order of the data to be written; the first word is an integer with the number of data; then for each data it is written an integer with the number of characters of the data name, the data name itself with this number of characters, the number of characters of the data C++ type, and finally the C++ type itself with this number of characters (which can be int, float or char). To write this header the following parameter has to be used:
/gamos/setParam FILE_NAME:WriteHeaderData 1
The third optional header is a float containing the number of events used in the job (see for example the section on Radiotherapy phase space reading or using files as generator for the exact meaning of the number of events in these cases). To write this header the following parameter has to be used:
/gamos/setParam FILE_NAME:WriteHeaderNEvents 1
The fourth optional header is an integer containing the number of calls to the data user object. To write this header the following parameter has to be used:
/gamos/setParam FILE_NAME:WriteHeaderNCalls 1
The name of the binary file is given by the name of the data user plus the filters and classifiers plus (i.e. .out. It can be changed with the parameter:
/gamos/setParam DATA_USER_NAME:FileName NEW_FILE_NAME
For example:
/gamos/userAction GmStepDataBinFileUA GmGammaFilter
will produce a file named GmStepDataBinFileUA_GmGammaFilter.out, whose name can be changed with the command:
/gamos/setParam GmStepDataBinFileUA_GmGammaFilter:FileName NEW_FILE_NAME
to produce a file named NEW_FILE_NAME.out
Cout: These data users (i.e. GmStepDataCoutUA, GmTrackDataCoutUA, GmSecondaryTrackDataCoutUA, GmStackDataCoutUA, GmEventDataCoutUA, GmRunDataCoutUA) dump the data values into the standard output (they may be helpful to debug an application, together with the command /tracking/verbose 1 . Similarly to the text file data users, a line is written for each call to the data user object (i.e. each G4Step, G4Track, ...). The text file is indeed a CSV (Comma Separated Value) file; this means that values are separated by commas and string values are surrounded by double quotes.
Each data user has a default list of data, that we will enumerate below. This list can be changed with the parameter:
/gamos/setParam DATA_USER_NAME:DataList DATA_1 DATA_2 ...
For example, if we use:
/gamos/userAction GmStepDataBinFileUA GmGammaFilter
the data list may be changed with the parameter:
/gamos/setParam GmStepDataBinFileUA_GmGammaFilter:DataList TrackID FinalPosX sqrt(2*FinalPosX*FinalPosY) InitialKineticEnergy
The default data list of each of the fifteen data users are:
FinalPosX
FinalPosY
FinalPosZ
FinalMomX
FinalMomY
FinalMomZ
AccumulatedEnergyLost
AccumulatedEnergyDeposited
EventID
TrackID
Particle
FinalPosX
FinalPosY
FinalPosZ
FinalMomX
FinalMomY
FinalMomZ
AccumulateEnergyLost
AccumulateEnergyDeposited
EventID
TrackID
Particle
FinalPosX
FinalPosY
FinalPosZ
FinalMomX
FinalMomY
FinalMomZ
AccumulateEnergyLost
AccumulateEnergyDeposited
FinalPosX
FinalPosY
FinalPosZ
FinalMomX
FinalMomY
FinalMomZ
AccumulatedEnergyLost
AccumulatedEnergyDeposited
EventID
TrackID
Particle
FinalPosX
FinalPosY
FinalPosZ
FinalMomX
FinalMomY
FinalMomZ
AccumulateEnergyLost
AccumulateEnergyDeposited
EventID
TrackID
Particle
FinalPosX
FinalPosY
FinalPosZ
FinalMomX
FinalMomY
FinalMomZ
AccumulateEnergyLost
AccumulateEnergyDeposited
AccumulateEnergyLost
AccumulatedEnergyDeposited
EventID
AccumulateEnergyLost
AccumulatedEnergyDeposited
EventID
AccumulateEnergyLost
AccumulatedEnergyDeposited
AccumulateEnergyLost
AccumulatedEnergyDeposited
RunID
AccumulateEnergyLost
AccumulatedEnergyDeposited
RunID
AccumulateEnergyLost
AccumulatedEnergyDeposited
TrackID
InitialPrimMinusSecoKineticEnergy
FinalPrimMinusSecoKineticEnergy
SecoDividedInitialPrimKineticEnergy
SecoKineticEnergy
PrimSecoAngleChange
InitialPrimKineticEnergy
FinalPrimKineticEnergy
EventID
TrackID
InitialPrimMinusSecoKineticEnergy
FinalPrimMinusSecoKineticEnergy
SecoDividedInitialPrimKineticEnergy
SecoKineticEnergy
PrimSecoAngleChange
InitialPrimKineticEnergy
FinalPrimKineticEnergy
TrackID
InitialPrimMinusSecoKineticEnergy
FinalPrimMinusSecoKineticEnergy
SecoDividedInitialPrimKineticEnergy
SecoKineticEnergy
PrimSecoAngleChange
InitialPrimKineticEnergy
FinalPrimKineticEnergy
The GmDataTTreeUA data user sorts GAMOS data in a ROOT TTree structure and save the new TTree in a ROOT TFile. The GmDataTTreeUA is invoked with the usual command:
/gamos/userAction GmDataTTreeUA
By default the TTree is created with the GmDataTTree name and saved in the GmDat aTTree.root file. The following command can be used to modify both both TFile and TTree names:
/gamos/setParam DATA_USER_NAME:TreeFileName NEW_NAME
Four categories of GAMOS data can be saved in the TTree: Event data, Track data, Secondary Track data, and Step data. GAMOS users can s elect one list of data for each one of the four categories. If data with no meaning for a given category are included in the correspondent list (e.g. adding trackID data to the Event data list), an exception will be returned. By default, the four data lists are empty and nothi ng is saved in the TTree unless otherwise specified. The four data lists are selected as follows:
/gamos/setParam DATA_USER_NAME:EventDataList EVENT_DATA_1 EVENT_DATA_2 ...
/gamos/setParam DATA_USER_NAME:TrackDataList TRACK_DATA_1 TRACK_DATA_2 ...
/gamos/setParam DATA_USER_NAME:SecondaryTrackDataList SECO_DATA_1 SECO_DATA_2 ...
/gamos/setParam DATA_USER_NAME:StepDataList STEP_DATA_1 STEP_DATA_2 ...
DATA_USER_NAME is the name of the user action, i.e. the word GmDataTreeUA plus the name of filters and classifier
The TTree is filled at the end of each GAMOS event and contains a number of entries equal to the number of simulated events. Each of the selected GAMOS data is stored in an independent TBranch inside the TTree.
Data are saved as integers, doubles, or strings. For each TTree entry, each of the selected GAMOS data is stored in a std::vector, apart from Event data that correspond to single values. The size of a std::vector varies in accordance with the corresponding category: track data vectors contain a number of elements equal to the number of tracks for a given event; step and secondary track data vectors equal to the number of steps for the same event.
It is possible to use any GAMOS data to filter on its value (see chapter on Filters). To use it you have to use the command to define a filter, using the filter named GmNumericDataFilter if the data is of numeric type (int or float) and GmStringDataFilter if the data is of string type and passing the following arguments:
GmNumericDataFilter: In this case after the filter name you have to give the the minimum and maximum value of the data. For example:
/gamos/filter dataF GmNumericDataFilter InitialKineticEnergy 0. 0.3
GmStringDataFilter: In this case after the filter name, you have to give the list of accepted values. For example:
/gamos/filter dataF GmStringDataFilter InitialLogicalVolume detector world
It is possible to use any GAMOS data to classify on its value (see chapter on Classifiers). To use it you have to use the command to define a classiifier, using the classifier named GmClassifierByNumericData if the data is of numeric type (int or float) and GmClassifierByStringData if the data is of string type and passing the following arguments:
Data is integer or float: In this case after the classifier name you have to give the number of intervals, the minimum data limit and the maximum data limit. For example to define 20 energy intervals between 0 and 10 :
/gamos/classifier dataC GmClassifierByData InitialKineticEnergy 20 0. 10.
GAMOS will check if the data value is inside the interval defined by the minimum and maximum. If it is smaller, it will assign an index 0, if it is bigger it will assign an index INT_MAX (2^32). In both cases a warning will be printed. If you do not want to allow this behaviour, but you want that the job is stopped if the datais out of limits, you have to set the parameter:
/gamos/setParam CLASSIFIER_NAME:AllowOutOfLimits 0
Data is string: In this case no argument is needed after the classifier name. For example:
/gamos/classifier dataC GmClassifierByData InitialLogicalVolume
If you want to assign different indices than 0 to N, you may use the command :
/gamos/classifier/setIndices VALUE_1 INDEX_1 VALUE_2 INDEX_2
See section on Setting indices to classifiers for further details on this feature.
It is possible to use any GAMOS data, if its type is interger of float, to build an scorer on its value (see chapter on Scorers). To use it you have to use the command to define a scorer, using the scorer named GmG4PSData and passing to it the data name and the minimum and maximum value of the data. For example:
/gamos/scoring/createMFDetector contDet container
/gamos/scoring/addScorer2MFD dataScorer GmG4PSData contDet InitialKineticEnergy
<<< Previous | Home | Next >>> |
Analysis (extracting data) | Up | List of available data |