.. _output_processors: Output Processors ````````````````` .. _outroot: outroot ======= The ``OutROOT`` processor writes events to disk in the ROOT format. The events are stored in a TTree object called "T" and the branch holding the events is called "ds". The full RAT data structure is described in :ref:`ratds`. Command: :: /rat/proc outroot Parameters: :: /rat/procset file "filename" * filename (required, string) Sets output filename. File will be deleted if it already exists. .. _outntuple: outntuple ========= The ``OutNtuple`` processor writes events to disk as a flat ``ROOT`` Tree, and are thus much smaller and easier to work with than the files output by the outroot processor. There is also significant flexibility in what information is stored to the file, as detailed below. To run this processor and write the ntuple files out: Command: :: /rat/proc outntuple Parameters: :: /rat/procset file "filename" /rat/procset include_mcparticles 1 /rat/procset include_tracking 1 /rat/procset include_pmthits 1 /rat/procset include_nestedtubehits 1 /rat/procset include_untriggered_events 1 /rat/procset include_mchits 1 /rat/procset include_digitizerwaveforms 1 /rat/procset include_digitizerhits 1 /rat/procset include_digitizerfits 1 /rat/procset waveform_fitters ["Lognormal","Gaussian","Sinc","LucyDDM","RAVEN"] /rat/procset waveform_fitter_FOM_FITTERNAME ["FOM1","FOM2"] /rat/procset event_fitters ["quadfitter","fitcentroid","fitdirectioncenter","mimir"] /rat/procset event_fitter_FOM_FITTERNAME ["FOM1","FOM2"] * ``filename`` (required, string) Sets output filename. File will be deleted if it already exists. * ``include_*`` (optional, int) Sets whether the ntuple structure will be extended to include more variables, as detailed below. By default the following, based on the entries in IO.ratdb, the following are set to 0 by default: ``include_tracking``, ``include_mcparticles``, and ``include_digitizerwaveforms`` and the rest are set to 1 by default (i.e., the associated variables aare included in the ntuple file, as detailed below). * ``waveform_fitters`` (optional, vector) Waveform analysis algorithm results to include in the ntuple. See below for naming of the specific variables. * ``waveform_fitter_FOM_FITTERNAME`` (optional, vector) The figure of merit to include for each waveform fitter. See below for naming of the specific variables. * ``event_fitters`` (optional, vector) Event reconstruction algorithm results to include in the ntuple. See below for naming of the specific variables. * ``event_fitter_FOM_FITTERNAME`` (optional, vector) The figure of merit to include for each event fitter. See below for naming of the specific variables. FOM can be specified by the base name of the reconstruction algorithm (e.g., ``event_fitter_FOM_quadfitter``) or by the specific instances of each algorithm (e.g. ``event_fitter_FOM_fitdirectioncenter__0_quad``). Similarly to the outroot file, one can pass the filename using the "-o" flag by running the macro as:: rat example_macro.mac -o output.root The ntuple contains flat ``TTrees`` called ``meta`` and ``output``, and optionally a tree called ``waveform``. The ``output`` branch contains data for each event, and is structured to hold both the "true" simulated quantities as well as the "detector" quantities, that are filled after a data acquisition processor are run. As an example, we see in the below table that the ``output`` branch contains entries for ``mcx``, the true position of the simulated event, as well as ``triggerTime``, the time of the event trigger. This can lead to confusion because not all simulated events will trigger the detector. Importantly, if we do not run any DAQ simulation, none of the events will be saved unless ``include_untriggered_events`` is set to true. If you're entirely interested in studying variables generated prior to the data aquisition (e.g., particle position, number of Cherenkov photons produced, the true number of detected photoelectrons, etc.), be certain to set ``include_untriggered_events`` to true in the macro. If we do run the DAQ simulation, only information for the triggered events will be saved to the ``output`` branch, unless ``include_untriggered_events`` is set to true, in which case all events will be saved to the ``output`` branch. Furthermore, for triggered event we should expect to have differences between the simulated and detector quantities. For example, the ``mcPMTID`` (only filled when ``mchits`` is set true), the true set of PMTs that detected light, the ``hitPMTID`` (only filled when ``pmthits`` is set true), the set of PMTs that detected light after applying the data aquisition simulation, and the ``digitPMTID``, the set of PMTs that detected light after applying the data aquisition and waveform analysis simulations, can all be different length vectors (the ``hitPMTID`` and ``digitPMTID`` will always be a subset of ``mcPMTID``). The ``meta`` branch of the output file should only have a single entry and contains information relevant for all simulated events, such as the run-number, the run-time, the PMT positions, and the total number of simulated events. The data-structure for the "default" ``meta`` tree, that are always written to the file, are: ================================ =================== =================== **Name** **Type** **Description** ================================ =================== =================== ``runID`` int The run number, from the RUN table. ``runType`` ulong64 The run type, from the RUN table. ``runTime`` ulong64 The unix start time of the run. ``dsentries`` int The total number of simulated events. ``macro`` string The macro name. ``pmtType`` vector The list of PMT types. ``pmtID`` vector The list of PMT IDs. ``pmtChannel`` vector The list of PMT electronic channels. ``pmtIsOnline`` vector The list of whether each PMT is online. ``pmtCableOffset`` vector The list of calibration cable offsets per PMT. ``pmtChargeScale`` vector The list of calibration charge scales per PMT. ``pmtPulseWidthScale`` vector The list of calibration pulse width scales per PMT. ``pmtX`` vector The list of PMT x positions. ``pmtY`` vector The list of PMT y positions. ``pmtZ`` vector The list of PMT z positions. ``pmtU`` vector The list of PMT x directions. ``pmtV`` vector The list of PMT y directions. ``pmtW`` vector The list of PMT z directions. ``digitizerWindowSize`` uint32 The length of the digitizer window. ``digitizerSampleRate_GHz`` double The sampling rate of the digitizer, in GHz. ``digitizerDynamicRange_mV`` double The dynamic range of the digitizer, in mV. ``digitizerResolution_mVPerADC`` double The resolution of the digitizer, in mV/ADC. ================================ =================== =================== The data-structure for the ``output`` tree is as follows. First, the "default" variables that are always written to the ntuple are detailed below. Note the distinction between simulated event and detector event, described in :ref:`daq_processors`. The word "true" is used to indicate simulated quantities that are not affected by the detector response. =========================== =================== =================== **Name** **Type** **Description** =========================== =================== =================== ``mcpdg`` int Particle data code for highest energy particle. ``mcx`` double True x position of the highest energy particle. ``mcy`` double True y position of the highest energy particle. ``mcz`` double True z position of the highest energy particle. ``mcu`` double True x direction of the highest energy particle. ``mcv`` double True y direction of the highest energy particle. ``mcw`` double True z direction of the highest energy particle. ``mcke`` double True kinetic energy of the highest energy particle. ``mct`` double True time, relative to the start of the simulation, of the highest energy particle. ``scintEdep`` double True total energy deposited in the scintillator (0 if no scintillator). ``scintEdepQuenched`` double True total quenched energy deposited in the scintillator. ``scintPhotons`` int True total number of scintillation photons produced. ``remPhotons`` int True total number of re-emitted photons produced. ``cherPhotons`` int True total number of Cherenkov photons produced. ``mcid`` int The simulated event ID. ``mcparticlecount`` int The true total number of simulated particles. ``mcnhits`` int The true total number of PMTs that detected light. ``mcpecount`` int The true total number of detector photoelectrons. ``evid`` int The detector event ID. ``subev`` int The ID of the event within a single simulated event. ``nhits`` int The total number of PMTs that detected light in the detector event. ``triggerTime`` double The trigger time of the detector event, relative to the start of the simulation. ``timestamp`` double The UTC time of the detector event. ``timeSinceLastTrigger_us`` double The time since the last triggered event, in microseconds. ``event_cleaning_word`` ulong64 The list of event cleaning cuts that failed. =========================== =================== =================== If ``include_mcparticles`` is set then we additionally add the following information to the ``output`` branch of the ntuple. These are filled from the ``DS::MCParticle`` branch. This provides a method for looking at all simulated particles, rather than just the first. =========================== =================== =================== **Name** **Type** **Description** =========================== =================== =================== ``mcpdgs`` vector Particle data code for all particles. ``mcxs`` vector True x position of all particles. ``mcys`` vector True y position of all particles. ``mczs`` vector True z position of all particles. ``mcus`` vector True x direction of all particles. ``mcvs`` vector True y direction of all particles. ``mcws`` vector True z direction of all particles. ``mckes`` vector True kinetic energy of all particles. ``mcts`` vector True time of each particle, relative to the start of the simulation. =========================== =================== =================== If ``include_pmthits`` is set then we additionally add the following information to the ``output`` branch of the ntuple. Note that a DAQ system must also run in order for these variables to be filled, see :ref:`daq_processors` for more details. The ``hitPMT`` variables are filled from the ``RAT::DS::PMT``, described in :ref:`ratds`. =========================== =================== =================== **Name** **Type** **Description** =========================== =================== =================== ``hitPMTID`` vector The unique ID of each of the PMTs that detected light. ``hitPMTTime`` vector The hit-time of the first PE at each PMT. ``hitPMTCharge`` vector The charge for each PMT that detected light. =========================== =================== =================== If ``include_digitizerhits`` is set then we additionally add the following information to the ``output`` branch of the ntuple. Note that a DAQ system and waveform analysis processor must also run in order for these variables to be filled, see :ref:`daq_processors` and :ref:`waveform_analysis` for more details. The ``digitPMT`` variables are filled from the ``RAT::DS::DigitPMT``, described in :ref:`ratds`. ============================= =================== =================== **Name** **Type** **Description** ============================= =================== =================== ``digitPMTID`` vector The unique ID of each of the PMT waveform that crossed threshold. ``digitNhits`` int The total number of PMT waveforms that crossed threshold. ``digitNhitsCleaned`` int The total number of PMT waveforms that passed all enabled hit cleaning processors and crossed threshold. ``digitTime`` vector The hit-time extracted from each PMT waveform. ``digitCharge`` vector The charge extracted from each PMT waveform. ``digitNCrossings`` vector The total number of times each PMT waveform crossed threshold. ``digitTimeOverThreshold`` vector The total time each PMT waveform spent above threshold. ``digitVoltageOverThreshold`` vector The integrated voltage over threshold for each PMT. ``digitPeak`` vector The peak voltage of each PMT waveform. ``digitLocalTriggerTime`` vector Convenience variable to add per-PMT calibration timing. ``digitReconNPEs`` vector The total number of PEs per PMT, as estimated by a PE counting method. ============================= =================== =================== If ``include_digitizerfits`` is set then we additionally add the following information to the ``output`` branch of the ntuple. Note that a DAQ system and waveform analysis processor must also run in order for these variables to be filled, see :ref:`daq_processors` and :ref:`waveform_analysis` for more details. In particular, these are filled by a specific waveform analysis algorithm, such as the lognormal fits described in :ref:`lognormalfit`. The fitter will append its name to the variable name (e.g., ``fit_pmtid_lognormal``). These are filled from the ``DS::WaveformAnalysisResult`` branch. ====================================== =================== =================== **Name** **Type** **Description** ====================================== =================== =================== ``fit_pmtid_+{fitter_name}`` vector The unique ID of each of the PMT waveform that was fit. ``fit_time_+{fitter_name}`` vector The time extracted from each PMT waveform fit. ``fit_charge_+{fitter_name}`` vector The charge extracted from each PMT waveform fit. ``fit_FOM_+{fitter_name}_+{fom_name}`` vector The figure of merit extracted from each PMT waveform fit. ====================================== =================== =================== If ``include_nestedtubehits`` is set then we additionally add the following information to the ``output`` branch of the ntuple. These "nested tubes" are intended for use with liquid-O style fiber optics detectors. These are filled from the ``DS::MCNestedTube`` branch. ============================= =================== =================== **Name** **Type** **Description** ============================= =================== =================== ``mcnNTs`` int Total number of nested tubes that detected light. ``mcnNThits`` int Total number of PEs detector by nested tubes. ``mcNTid`` vector The unique ID of each true nested tube that detected light. ``mcNThittime`` vector The true time of each PE detected by a nested tube. ``mcNThitx`` vector The true x position for each PE detected by a nested tube. ``mcNThity`` vector The true y position for each PE detected by a nested tube. ``mcNThitz`` vector The true z position for each PE detected by a nested tube. ``ntId`` vector The unique ID for each detector nested tube that detected light. ============================= =================== =================== If ``include_nestedtubehits`` is set then we additionally add the following information to the ``meta`` branch of the ntuple. ============================= =================== =================== **Name** **Type** **Description** ============================= =================== =================== ``ntX`` vector The x position of the nested tubes. ``ntY`` vector The y position of the nested tubes. ``ntZ`` vector The z position of the nested tubes. ``ntU`` vector The x direction of the nested tubes. ``ntV`` vector The y direction of the nested tubes. ``ntW`` vector The z direction of the nested tubes. ============================= =================== =================== If ``include_mchits`` is set then we additionally add the following information to the ``output`` branch of the ntuple. The ``mcPMT`` variables are filled from the ``RAT::DS::MCPMT`` branch, whereas the ``mcPE`` variables are filled from the ``RAT::DS::MCPhoton`` branch. ============================= =================== =================== **Name** **Type** **Description** ============================= =================== =================== ``mcPMTID`` vector The unique IDs of the true hit PMTs. ``mcPMTNPE`` vector The true number of PEs for each hit PMT. ``mcPMTCharge`` vector The true charge deposited on each PMT. ``mcPEPMTID`` vector The unique ID of the PMT that detected each PE. ``mcPEHitTime`` vector The true detection time of each PE. ``mcPEFrontEndTime`` vector The true detection time, smeared by the sensor response, of each PE. ``mcPEProcess`` vector The process that created the photon that created the PE. ``mcPEx`` vector The true x position of the PE. ``mcPEy`` vector The true y position of the PE. ``mcPEz`` vector The true z position of the PE. ``mcPECharge`` vector The true charge of each PE. ============================= =================== =================== If ``include_tracking`` is set then we additionally add the following information to the ``output`` branch of the ntuple. These variables are filled from the ``RAT::DS::MCTrack`` and ``RAT::DS::MCTrackStep`` branches. The variables below are mostly 2D vectors. The inner vector is the set of steps along the particle track (``RAT::DS::MCTrackStep``) and the outer vector is the set of tracks along the particle trajectory (``RAT:DS::MCTrack``). In other words, each track can have many steps, each of which as an associated position, momentum, process, and volume. As a reminder, ``/tracking/storeTrajectory 1`` must also be set in the macro in order to save the tracking information. ============================= ====================== =================== **Name** **Type** **Description** ============================= ====================== =================== ``trackPDG`` vector The PDG code of the particle associated with this track. ``trackPosX`` vector> The starting x position of each of the steps along the particle track. ``trackPosY`` vector> The starting y position of each of the steps along the particle track. ``trackPosZ`` vector> The starting z position of each of the steps along the particle track. ``trackMomX`` vector> The starting x momentum of each of the steps along the particle track. ``trackMomY`` vector> The starting y momentum of each of the steps along the particle track. ``trackMomZ`` vector> The starting z momentum of each of the steps along the particle track. ``trackKE`` vector> The kinetic energy of each of the steps along the particle track. ``trackTime`` vector> The time, relative to the start of the simulation, of the particle steps. ``trackProcess`` vector> The ID of the process that created the step. ``trackVolume`` vector> The ID of the detector volume the step started in. ============================= ====================== =================== If ``include_tracking`` is set then we additionally add the following information to the ``meta`` branch of the ntuple. ============================= =================== =================== **Name** **Type** **Description** ============================= =================== =================== ``processCodeMap`` map A map from process name to process ID. ``volumeCodeMap`` map A map from volume name to volume ID. ============================= =================== =================== If ``include_digitizerwaveforms`` is set then we create a new branch in the ntuple called ``waveform`` that stores the full digitized waveforms. Note this will significantly increase the size of the files. The ``waveform`` branch will contain the following variables: ============================= =================== =================== **Name** **Type** **Description** ============================= =================== =================== ``evid`` int The event ID, repeated in the ``output`` tree. ``waveform_pmtid`` vector The unique PMT ID associated with the waveform. ``inWindowPulseTimes`` vector The list of MCPE front-end times that fall inside the waveform window. ``inWindowPulseCharges`` vector The list of MCPE charges that fall inside the waveform window. ``waveform`` vector The digitized waveform, per PMT. ============================= =================== =================== If ``event_fitters`` specify that event reconstruction algorithm results should be included in the ntuple, then we add the following variables to the ``output`` branch of the ntuple. These are filled from the ``DS::EventFitResult`` branch. All fitter instances are labeled by the "full name" of the fitter instance, which is the name of the fitter type + the instance name of the fitter separated by double underscores (e.g., ``quadfitter__instance1``). The variables are as follows: =================================== =================== =================== **Name** **Type** **Description** =================================== =================== =================== ``x_fitter__FULLNAME`` double X coordinate of the reconstructed event vertex. ``y_fitter__FULLNAME`` double Y coordinate of the reconstructed event vertex. ``z_fitter__FULLNAME`` double Z coordinate of the reconstructed event vertex. ``u_fitter__FULLNAME`` double X component of the reconstructed event direction. ``v_fitter__FULLNAME`` double Y component of the reconstructed event direction. ``w_fitter__FULLNAME`` double Z component of the reconstructed event direction. ``energy_fitter__FULLNAME`` double Reconstructed event energy. ``time_fitter__FULLNAME`` double Reconstructed event time. ``validposition_fitter__FULLNAME`` bool Whether the reconstructed event position is valid. ``validdirection_fitter__FULLNAME`` bool Whether the reconstructed event direction is valid. ``validenergy_fitter__FULLNAME`` bool Whether the reconstructed event energy is valid. ``validtime_fitter__FULLNAME`` bool Whether the reconstructed event time is valid. ``FOMNAME_fitter__FULLNAME`` double The figure of merit for the event fit. =================================== =================== =================== .. _outnet: OutNet ====== NOTE: This processor is not currently supported. The below documentation is outdated, but may provide some useful information. The !OutNet processor transmits events over the network to a listening copy of RAT which is running the [wiki:UserGuideInNet InNet] event producer. Multiple listener hostnames may be specified, and events will be distributed across them with very simplistic load-balancing algorithm. This allows an event loop to be split over multiple machines. I'll leave it to your imagination to think up a use for this... Command: :: /rat/proc outnet Parameters: :: /rat/procset host "hostname:port" * hostname:port (required) Network hostname (or IP address) and port number of listening RAT process. === Notes === The "load balancing" mentioned above distributes events by checking to see which sockets are available for writing and picking the first one that can be found. The assumption is that busy nodes will have a backlog of events, so their sockets will be full. In principle, this means that a few slow nodes won't hold up the rest of the group. This processor and its [wiki:UserGuideInNet sibling event producer] have no security whatsoever. Don't use your credit card number as a seed for the Monte Carlo.