Document detector signal classes

inc/TRestDetectorSignal.h

@@ -7,7 +7,7 @@
 ///
 ///             TRestDetectorSignal.h
 ///
-///             Event class to store signals fromm simulation and acquisition
+///             Event class to store signals from simulation and acquisition
 ///             events
 ///
 ///             sept 2015:   First concept

src/TRestDetectorSignal.cxx

@@ -1,27 +1,68 @@
-///______________________________________________________________________________
-///______________________________________________________________________________
-///______________________________________________________________________________
+//////////////////////////////////////////////////////////////////////////
+/// TRestDetectorSignal stores one detector-channel signal as time-charge
+/// points.
 ///
+/// A TRestDetectorSignal represents the response of one detector readout
+/// channel after the signal has been expressed in physical coordinates. Unlike
+/// TRestRawSignal, which stores a fixed array of ADC samples indexed by bin,
+/// TRestDetectorSignal stores two parallel vectors: one with the time of each
+/// point and one with the corresponding charge or amplitude. The signal is
+/// identified by its signal ID, which is the channel identifier used by the
+/// readout and by TRestDetectorSignalEvent.
 ///
-///             RESTSoft : Software for Rare Event Searches with TPCs
+/// This class is commonly produced by detector simulation or reconstruction
+/// processes. For example, TRestDetectorHitsToSignalProcess converts energy
+/// deposits in a TRestDetectorHitsEvent into detector signals using the readout
+/// geometry, drift velocity, and electronics sampling. The resulting
+/// TRestDetectorSignal objects can then be converted to hits again, analyzed
+/// channel by channel, or inspected visually through their TGraph
+/// representation.
 ///
-///             TRestDetectorSignal.cxx
+/// A signal can be filled point by point:
 ///
-///             Event class to store signals from simulation and acquisition
-///             events
+/// \code
+/// TRestDetectorSignal signal;
+/// signal.SetSignalID(12);
+/// signal.NewPoint(0.0, 0.0);
+/// signal.NewPoint(0.1, 4.2);
+/// signal.NewPoint(0.2, 12.8);
 ///
-///             sept 2015:   First concept
-///                 Created as part of the conceptualization of existing REST
-///                 software.
+/// std::cout << "Integral: " << signal.GetIntegral() << std::endl;
+/// std::cout << "Peak time: " << signal.GetMaxPeakTime() << std::endl;
+/// signal.GetGraph()->Draw("AL");
+/// \endcode
+///
+/// Use NewPoint() when appending a sampled point, SetPoint() when replacing or
+/// inserting a point at a given time, and IncreaseAmplitude() when several
+/// contributions should be accumulated at the same time. If the points are not
+/// added in chronological order, Sort() can be used before time-dependent
+/// operations.
+///
+/// The class provides basic signal observables such as GetIntegral(),
+/// GetIntegralWithTime(), GetMaxPeakValue(), GetMaxPeakTime(), GetMinTime(),
+/// and GetMaxTime(). It also includes utilities for normalization, baseline
+/// subtraction, smoothing, noise generation, delayed copies, and simple peak
+/// fits.
+///
+///--------------------------------------------------------------------------
+///
+/// RESTsoft - Software for Rare Event Searches with TPCs
+///
+/// History of developments:
+///
+/// 2015-September: First concept.
 ///                 JuanAn Garcia/Javier Galan
-///		nov 2015:
-///		    Changed vectors fSignalTime and fSignalCharge from <Int_t>
-/// to
-///< Float_t> 	            JuanAn Garcia
-//      dec 2015:
-//
-//              Javier Galan
-///_______________________________________________________________________________
+///
+/// 2015-November: Changed vectors fSignalTime and fSignalCharge from Int_t
+///                to Float_t.
+///                JuanAn Garcia
+///
+/// \class      TRestDetectorSignal
+/// \author     JuanAn Garcia
+/// \author     Javier Galan
+///
+/// <hr>
+///
 
 #include "TRestDetectorSignal.h"
 

src/TRestDetectorSignalEvent.cxx

@@ -1,23 +1,81 @@
-
-///______________________________________________________________________________
-///______________________________________________________________________________
+//////////////////////////////////////////////////////////////////////////
+/// TRestDetectorSignalEvent stores the detector-channel signals associated
+/// with one REST event.
+///
+/// A TRestDetectorSignalEvent is a collection of TRestDetectorSignal objects.
+/// Each TRestDetectorSignal corresponds to one readout channel, identified by
+/// its signal ID, and stores the signal as time-charge points in physical
+/// coordinates. The event object groups those channel signals and provides
+/// event-level operations such as signal lookup, drawing, sorting, integrals,
+/// and global time or amplitude limits.
+///
+/// This event type is usually found after the raw ADC representation has been
+/// converted into detector-level signals, or after simulated detector hits have
+/// been projected onto a readout. It sits between TRestRawSignalEvent, which
+/// keeps ADC samples, and TRestDetectorHitsEvent, which stores reconstructed or
+/// simulated spatial hits. Processes such as TRestDetectorHitsToSignalProcess,
+/// TRestRawToDetectorSignalProcess, and TRestDetectorSignalToHitsProcess use
+/// this class as the detector-signal representation.
+///
+/// A minimal inspection from a `restRoot` session or ROOT macro looks like:
+///
+/// \code
+/// TRestRun run("detectorSignals.root");
+/// run.GetEntry(0);
+///
+/// auto signalEvent = run.GetInputEvent<TRestDetectorSignalEvent>();
+/// std::cout << "Signals in event: " << signalEvent->GetNumberOfSignals()
+///           << std::endl;
+///
+/// auto signal = signalEvent->GetSignalById(12);
+/// if (signal != nullptr) {
+///     std::cout << "Signal 12 integral: " << signal->GetIntegral()
+///               << std::endl;
+/// }
+///
+/// signalEvent->DrawEvent();
+/// \endcode
 ///
+/// Signals can be accessed by collection index with GetSignal(), or by channel
+/// identifier with GetSignalById(). Analysis code should normally use
+/// GetSignalById() when referring to a physical readout channel, because the
+/// internal ordering of the signal collection is not the channel mapping.
 ///
-///             RESTSoft : Software for Rare Event Searches with TPCs
+/// AddChargeToSignal() is a convenient way to fill an event when several charge
+/// contributions may arrive at the same channel and time. It creates the
+/// corresponding TRestDetectorSignal if the signal ID is not yet present, and
+/// otherwise accumulates the charge in the existing signal.
 ///
-///             TRestDetectorSignalEvent.h
+/// DrawEvent() displays all contained TRestDetectorSignal objects in a
+/// TMultiGraph, with time on the horizontal axis and amplitude on the vertical
+/// axis.
 ///
-///             Event class to store DAQ events either from simulation and
-///             acquisition
+/// The following figure shows a detector signal event drawn with DrawEvent().
+/// Each trace corresponds to one TRestDetectorSignal in the event, with the
+/// horizontal axis expressed in physical time.
 ///
-///             sept 2015:   First concept
-///                 Created as part of the conceptualization of existing REST
-///                 software.
+/// \htmlonly <style>div.image img[src="detector_signal_event.png"]{width:650px;}</style> \endhtmlonly
+///
+/// ![Detector signal event drawn with DrawEvent](detector_signal_event.png)
+///
+///--------------------------------------------------------------------------
+///
+/// RESTsoft - Software for Rare Event Searches with TPCs
+///
+/// History of developments:
+///
+/// 2015-September: First concept.
 ///                 JuanAn Garcia/Javier Galan
 ///
-///	       feb 2016: Added titles to axis in DrawGraph using TMultiGraph
-///		  Javier Gracia
-///_______________________________________________________________________________
+/// 2016-February: Added titles to axis in DrawGraph using TMultiGraph.
+///                Javier Gracia
+///
+/// \class      TRestDetectorSignalEvent
+/// \author     JuanAn Garcia
+/// \author     Javier Galan
+///
+/// <hr>
+///
 
 #include "TRestDetectorSignalEvent.h"