From 9df56d0991f5de58d6370c30c53440bb99f811ad Mon Sep 17 00:00:00 2001 From: Brais Palmeiro Pazos Date: Tue, 6 Dec 2022 19:27:41 +0000 Subject: [PATCH 1/4] Add the innitial version of dorothea's documentation --- docs/source/dorothea.rst | 206 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 203 insertions(+), 3 deletions(-) diff --git a/docs/source/dorothea.rst b/docs/source/dorothea.rst index 9da3f83..8dfef3e 100644 --- a/docs/source/dorothea.rst +++ b/docs/source/dorothea.rst @@ -1,5 +1,205 @@ Dorothea -========== +======== -.. caution:: - This page is currently not created, we are working on it. If you would like to contribute on this documentation, reach `me `_! +*From ancient Greek, Δωροθέα: gift of God.* + +The purpose of *Dorothea* is to process the **PMaps** (outcome of *Irene*) and +reconstruct point-like events. Therefore, all the information included in the S2 peaks +is collapsed into a single x, y, and z deposition with a given E (the area under the S2 peak). +Additionally, some parameters regarding the S1 and S2 peaks are provided as a tool for further selections. +Last, it is worth noting that for events where more than S1 or S2 (or both) are +present in the event, a point is reconstructed for each possible combination. + + +.. _Dorothea input: + +Input +----- + +* ``/Run/events`` +* ``/Run/runInfo`` +* ``/PMAPS/S1`` +* ``/PMAPS/S1Pmt`` +* ``/PMAPS/S2`` +* ``/PMAPS/S2Pmt`` +* ``/PMAPS/S2Si`` + +.. _Dorothea output: + +Output +------ + + * ``/DST/Events``: summary of the reconstructed events and their main properties. Each row represents one combination of an S1 and a S2 identified under the same ``event`` but with its corresponding ``s1_peak`` and ``s2_peak`` identifier. The full list and description of the parameters in the table may be found later. + * ``/Filters/s12_selector``: flag for whether an event passed the S1 and S2 selections + + +.. _Irene config: + +Config +------ + +Besides the :ref:`Common arguments to every city`, *Dorothea* has the following arguments: + +.. list-table:: + :widths: 50 40 120 + :header-rows: 1 + + * - **Parameter** + - **Type** + - **Description** + + * - ``drift_v`` + - ``float`` + - Drift velocity of the secondary electrons towards the anode. + + * - ``s1|s2_nmin|nmax`` + - ``int`` + - Lower/upper limits to the number of S1/S2 peaks per event. + + * - ``s1|s2_emin|emax`` + - ``float`` + - Lower/upper limits to the energy (integral under the peak) of each S1/S2 peak (pes). + + * - ``s1|s2_wmin|wmax`` + - ``float`` + - Lower/upper limits to the with (time over threshold) of each S1/S2 peak (ns). + + * - ``s1|s2_hmin|hmax`` + - ``float`` + - Lower/upper limits to the height (maximum amplitude) of each S1/S2 peak (pes). + + * - ``s1|s2_ethr`` + - ``float`` + - Threshold for each bin within each S1/S2 to be considered for the energy computation (pes). + + * - ``s2_nsipmmin|nsipmminax`` + - ``int`` + - Lower/upper limits to the number of SiPM sensors with a recorded signal. + + * - ``global_reco_params`` + - ``dict`` + - Set of parameters for the corona algorithm. Since the desired one is the barycenter reconstruction, the only mandatory elements in the dictionary are: + + * ``Qthr``: charge threshold, ignore all SiPMs with less than Qthr pes. + * ``lm_radius=-1``: sets the algorithm to be the barycenter. + + +.. _Dorothea workflow: + +Workflow +-------- + +The workflow for *Dorothea* is straightforward. After a filter removing all the peaks and events not satisfying the limits provided. Then, it proceeds to perform the point-like reconstruction. Basically, this algorithm collapses the whole S2 information into a single point: + + * The *x* and *y* position are determined via a charge-weighted average. This makes use of the so-called ``corona`` `algorithm `_, with the proper configuration to apply the barycenter computation. + * The *z* coordinate is derived from the time difference between the maximum amplitude of the S1 and S2 considered, corrected by the drift velocity. + * The energy is the integral under the S2 of those bins above the threshold. + + Besides, the reconstruction yields a set of useful values regarding the peaks that are also provided in the final table: + + .. list-table:: + :widths: 50 40 120 + :header-rows: 1 + + * - **Parameter** + - **Type** + - **Description** + + * - ``event`` + - ``int`` + - Event ID. As an event can have several S1 and S2 combinations, each one representing one row, this number identifies all the reconstructed points within the same original waveform. + + * - ``time`` + - ``float`` + - Timestamp of the event. + + * - ``s1_peak`` + - ``int`` + - S1 ID. It identifies the S1 within an event. + + * - ``s2_peak`` + - ``int`` + - S2 ID. It identifies the S2 within an event. + + * - ``nS1`` + - ``int`` + - Number of S1 present in the event. + * - ``nS2`` + - ``int`` + - Number of S2 present in the event. + + * - ``S1w`` + - ``float`` + - S1 time over threshold (ns). + + * - ``s1h`` + - ``float`` + - S1 maximum amplitude (pes). + + * - ``S1e`` + - ``float`` + - S1 PMT- and time-summed amplitude over threshold (pes). + + * - ``S1t`` + - ``float`` + - Waveform time at maximum S1 amplitude (ns). + + * - ``S2w`` + - ``float`` + - S2 time over threshold (ns). + + * - ``s2h`` + - ``float`` + - S2 maximum amplitude (pes). + + * - ``S2e`` + - ``float`` + - S2 PMT- and time-summed amplitude over threshold (pes). + + * - ``S2t`` + - ``float`` + - Waveform time at maximum S2 amplitude (ns). + + * - ``S2q`` + - ``float`` + - S2 SiPM- and time-summed amplitude over threshold (pes). + + * - ``Nsipm`` + - ``int`` + - Number of SiPMs with signal over threshold. + + * - ``DT`` + - ``float`` + - Drift Time —i.e., time difference between the corresponding S1 and S2— (:math:`\mu s`). + + * - ``Z`` + - ``float`` + - Reconstructed z position coordinate —i.e., the DT times the drift velocity— (mm). + + * - ``Zrms`` + - ``float`` + - Standard deviation of the PMT signal in the z coordinate (mm). + + * - ``X`` + - ``float`` + - Reconstructed x position coordinate using the barycenter algorithm (mm). + + * - ``Y`` + - ``float`` + - Reconstructed y position coordinate using the barycenter algorithm (mm). + + * - ``R`` + - ``float`` + - Reconstructed radial coordinate, :math:`r^2=x^2+y^2` (mm). + + * - ``Phi`` + - ``float`` + - Reconstructed azimuthal coordinate, :math:`\phi=\arctan(y/x)` (rad). + + * - ``Xrms`` + - ``float`` + - Standard deviation of the PMT signal in the x coordinate (mm). + + * - ``Yrms`` + - ``float`` + - Standard deviation of the PMT signal in the y coordinate (mm). From 03288b25d79e0d5ef16678df14a03956e23e0bcf Mon Sep 17 00:00:00 2001 From: Paola Ferrario Date: Tue, 13 Feb 2024 18:23:36 +0100 Subject: [PATCH 2/4] Improve description following reviewer's comments --- docs/source/dorothea.rst | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/source/dorothea.rst b/docs/source/dorothea.rst index 8dfef3e..e1cb3fb 100644 --- a/docs/source/dorothea.rst +++ b/docs/source/dorothea.rst @@ -3,11 +3,11 @@ Dorothea *From ancient Greek, Δωροθέα: gift of God.* -The purpose of *Dorothea* is to process the **PMaps** (outcome of *Irene*) and +The purpose of *Dorothea* is to process the **PMaps** (output of *Irene*) and reconstruct point-like events. Therefore, all the information included in the S2 peaks -is collapsed into a single x, y, and z deposition with a given E (the area under the S2 peak). +is collapsed into a single x, y, z point with summarized S1 and S2 properties. Additionally, some parameters regarding the S1 and S2 peaks are provided as a tool for further selections. -Last, it is worth noting that for events where more than S1 or S2 (or both) are +Last, it is worth noting that for events where more than one S1 or S2 (or both) are present in the event, a point is reconstructed for each possible combination. @@ -33,7 +33,7 @@ Output * ``/Filters/s12_selector``: flag for whether an event passed the S1 and S2 selections -.. _Irene config: +.. _Dorothea config: Config ------ @@ -62,7 +62,7 @@ Besides the :ref:`Common arguments to every city`, *Dorothea* has the following * - ``s1|s2_wmin|wmax`` - ``float`` - - Lower/upper limits to the with (time over threshold) of each S1/S2 peak (ns). + - Lower/upper limits to the width (time over threshold) of each S1/S2 peak. * - ``s1|s2_hmin|hmax`` - ``float`` @@ -72,15 +72,15 @@ Besides the :ref:`Common arguments to every city`, *Dorothea* has the following - ``float`` - Threshold for each bin within each S1/S2 to be considered for the energy computation (pes). - * - ``s2_nsipmmin|nsipmminax`` + * - ``s2_nsipmmin|nsipmmax`` - ``int`` - Lower/upper limits to the number of SiPM sensors with a recorded signal. * - ``global_reco_params`` - ``dict`` - - Set of parameters for the corona algorithm. Since the desired one is the barycenter reconstruction, the only mandatory elements in the dictionary are: + - Set of parameters for the corona algorithm. Since the desired one is the barycenter reconstruction, the only required elements in the dictionary are: - * ``Qthr``: charge threshold, ignore all SiPMs with less than Qthr pes. + * ``Qthr``: time-integrated charge threshold, ignore all SiPMs with less than Qthr pes. * ``lm_radius=-1``: sets the algorithm to be the barycenter. @@ -89,13 +89,19 @@ Besides the :ref:`Common arguments to every city`, *Dorothea* has the following Workflow -------- -The workflow for *Dorothea* is straightforward. After a filter removing all the peaks and events not satisfying the limits provided. Then, it proceeds to perform the point-like reconstruction. Basically, this algorithm collapses the whole S2 information into a single point: +The workflow for *Dorothea* starts with a filter that removes all the peaks and events not satisfying the limits provided via configuration file. Then, it proceeds to perform the point-like reconstruction. This algorithm collapses the whole S2 information into a single point, which has summarized information about S1 and S2, such as: - * The *x* and *y* position are determined via a charge-weighted average. This makes use of the so-called ``corona`` `algorithm `_, with the proper configuration to apply the barycenter computation. + * The *x* and *y* position are determined via a charge-weighted average (a.k.a. center of gravity or barycenter). This makes use of the so-called ``corona`` `algorithm `_, with the proper configuration to apply the barycenter computation. * The *z* coordinate is derived from the time difference between the maximum amplitude of the S1 and S2 considered, corrected by the drift velocity. - * The energy is the integral under the S2 of those bins above the threshold. + * The energy is the integral under the PMT S2 peak using the bins above the threshold. + * The charge is the integral under the SiPM S2 peak. - Besides, the reconstruction yields a set of useful values regarding the peaks that are also provided in the final table: + +.. _output: + +Output table +------------ + The output table contains a set of peak features: .. list-table:: :widths: 50 40 120 @@ -130,7 +136,7 @@ The workflow for *Dorothea* is straightforward. After a filter removing all the * - ``S1w`` - ``float`` - - S1 time over threshold (ns). + - S1 time over threshold (mus). * - ``s1h`` - ``float`` @@ -203,3 +209,5 @@ The workflow for *Dorothea* is straightforward. After a filter removing all the * - ``Yrms`` - ``float`` - Standard deviation of the PMT signal in the y coordinate (mm). + + As a final remark, notice that the peak height, width, time and energy come from the PMTs, while the charge (S2q) and the xy position come from the SiPMs. From 7ec3ef78fcca73b9e86476f3d1d7b6f67d94c8ab Mon Sep 17 00:00:00 2001 From: Paola Ferrario Date: Wed, 14 Feb 2024 10:27:05 +0100 Subject: [PATCH 3/4] Add internal link and clarifications --- docs/source/dorothea.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/dorothea.rst b/docs/source/dorothea.rst index e1cb3fb..6a1c7da 100644 --- a/docs/source/dorothea.rst +++ b/docs/source/dorothea.rst @@ -29,7 +29,7 @@ Input Output ------ - * ``/DST/Events``: summary of the reconstructed events and their main properties. Each row represents one combination of an S1 and a S2 identified under the same ``event`` but with its corresponding ``s1_peak`` and ``s2_peak`` identifier. The full list and description of the parameters in the table may be found later. + * ``/DST/Events``: summary of the reconstructed events and their main properties. Each row represents one combination of an S1 and a S2 identified under the same ``event`` but with its corresponding ``s1_peak`` and ``s2_peak`` identifier. The full list and description of the parameters in the table can be found :ref:`here `. * ``/Filters/s12_selector``: flag for whether an event passed the S1 and S2 selections @@ -89,12 +89,12 @@ Besides the :ref:`Common arguments to every city`, *Dorothea* has the following Workflow -------- -The workflow for *Dorothea* starts with a filter that removes all the peaks and events not satisfying the limits provided via configuration file. Then, it proceeds to perform the point-like reconstruction. This algorithm collapses the whole S2 information into a single point, which has summarized information about S1 and S2, such as: +The workflow for *Dorothea* starts with a filter that removes the peaks not satisfying the limits provided via configuration file. The event is selected if and only if the number of remaining peaks falls in the range [s1_nmin, s1_nmax] and [s2_nmin, s2_nmax]. Then, it proceeds to perform the point-like reconstruction. This algorithm collapses the whole S2 information into a single point, which has summarized information about S1 and S2, such as: * The *x* and *y* position are determined via a charge-weighted average (a.k.a. center of gravity or barycenter). This makes use of the so-called ``corona`` `algorithm `_, with the proper configuration to apply the barycenter computation. * The *z* coordinate is derived from the time difference between the maximum amplitude of the S1 and S2 considered, corrected by the drift velocity. * The energy is the integral under the PMT S2 peak using the bins above the threshold. - * The charge is the integral under the SiPM S2 peak. + * The charge is the integral under the SiPM S2 peak. A previous threshold has already been applied in the Irene city. .. _output: From b86153b56e1cf53408ffabfe06a3584105ac1ce2 Mon Sep 17 00:00:00 2001 From: Paola Ferrario Date: Thu, 16 May 2024 09:51:28 +0200 Subject: [PATCH 4/4] Fix unit of measure --- docs/source/dorothea.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/dorothea.rst b/docs/source/dorothea.rst index 6a1c7da..00e50cd 100644 --- a/docs/source/dorothea.rst +++ b/docs/source/dorothea.rst @@ -136,7 +136,7 @@ Output table * - ``S1w`` - ``float`` - - S1 time over threshold (mus). + - S1 time over threshold (ns). * - ``s1h`` - ``float`` @@ -152,7 +152,7 @@ Output table * - ``S2w`` - ``float`` - - S2 time over threshold (ns). + - S2 time over threshold (mus). * - ``s2h`` - ``float``