From e2440b575166ac1a2b40f420a0cc7716a92beb9b Mon Sep 17 00:00:00 2001 From: Gonzalo Martinez Lema Date: Fri, 9 Feb 2024 16:58:48 +0100 Subject: [PATCH 01/12] Add Sophronia documentation --- docs/source/IC.rst | 1 + docs/source/sophronia.rst | 251 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 252 insertions(+) create mode 100644 docs/source/sophronia.rst diff --git a/docs/source/IC.rst b/docs/source/IC.rst index 80779da..80cc968 100644 --- a/docs/source/IC.rst +++ b/docs/source/IC.rst @@ -137,6 +137,7 @@ MAIN PRODUCTION: Irene Penthesilea + Sophronia Dorothea Esmeralda Beersheba diff --git a/docs/source/sophronia.rst b/docs/source/sophronia.rst new file mode 100644 index 0000000..17e7fd5 --- /dev/null +++ b/docs/source/sophronia.rst @@ -0,0 +1,251 @@ +Sophronia +========= + +*From ancient Greek: sensible, prudent.* + + +This city processes each S2 signal previously selected as pmaps in +irene assuming a unique S1 within an event to produce a set of +reconstructed energy depositions (**Hits**). Hits consist of three +dimensional coordinates with an associated energy (PMT signal) and +charge (SiPM signal). The city contains a peak/event filter, which can +be configured to find events with a certain number of S1/S2 signals +that satisfy certain properties. Currently, the city is designed to +accept only 1 S1 signal and will take the first S1 signal even if the +filter is configured to take more than 1 S1. Furthermore, hits can be +optionally corrected for geometrical and lifetime effects. Besides +hits, the city also stores the global (x, y) position of each S2 +signal. The tasks performed are: + - Classify peaks according to the filter. + - Filter out events that do not satisfy the selector conditions. + - Resample S2 signals. + - Compute a set of hits for each slice in the resampled S2 signal. + - If there are more than one hit per slice, share the energy + according to the charge recorded in the tracking plane. + - If correction maps are provided, applies corrections to hits. + +.. _Sophronia input: + +Input +----- + + * ``/Run/events`` + * ``/Run/runInfo`` + * ``/PMAPS/S1`` + * ``/PMAPS/S2`` + * ``/PMAPS/S2Si`` + +.. _Sophronia output: + +Output +------ + + * ``/DST/Events``: summary of the S1 and S2 information of the reconstructed events. See :doc:`dorothea` for more details. + * ``/RECO/Events``: list of hit data for each event. + * ``/Filters/s12_selector``: flag for whether an event passed the S1 and S2 selections + * ``/Filters/valid_hit``: flag for whether an event passed the empty pmap filter + +.. _Sophronia config: + +Config +------ + +Besides the :ref:`Common arguments to every city`, *Sophronia* has the following arguments: + +.. list-table:: + :widths: 50 40 120 + :header-rows: 1 + + * - **Parameter** + - **Type** + - **Description** + + * - ``drift_v`` + - ``float`` + - Drift velocity. Used to make the correspondence between drift time and z position + + * - ``s1_params`` + - ``dict`` + - Selection criteria for S1 signals (see `Peak filtering`_) + + * - ``s2_params`` + - ``dict`` + - Selection criteria for S2 signals (see `Peak filtering`_) + + * - ``global_reco_algo`` + - ``XYReco`` + - Reconstruction algorithm applied to entire peaks (kDST) + + * - ``global_reco_params`` + - ``dict`` + - Configuration parameters for the global recontruction algorithm + + * - ``rebin`` + - ``int`` + - Specifies the level of resampling or grouping of consecutive samples for reconstruction. Must be :math:`\geq` 1 + + * - ``rebin_method`` + - ``RebinMethod`` + - Which resampling method to use (usually stride) + + * - ``q_thr`` + - ``float`` + - Charge threshold to be applied to the SiPMs + + * - ``sipm_charge_type`` + - ``SiPMCharge`` + - Type of SiPM charge to use (usually raw) + + * - ``same_peak`` + - ``bool`` + - Controls whether invalid hits can only be merged with other hits from the same peak + + * - ``corrections_file`` + - ``str`` + - Path to the file holding the correction maps + + * - ``apply_temp`` + - ``bool`` + - Whether to apply temporal corrections (in general, False in MC, True in data) + +.. _Sophronia workflow: + +Workflow +-------- + +Sophronia performs the following data transformations: + + * :ref:`Peak filtering ` + * :ref:`Build event summary ` + * :ref:`Resampling and hit creation ` + * :ref:`Hit merging ` + * :ref:`Hit correction ` + + +.. _Peak filtering: + +Peak filtering +:::::::::::::: + +:doc:`irene` finds peaks in the waveform with general characteristics, +but does not impose strong requirements on them. *Sophronia*, however, +can be more specific and select S1 and S2 signals based on the +following peak properties: width, height, and integral. These +quantities are calculated based on a (low) threshold applied to the +PMT waveform of the peak. For S2 signals, the number of SiPMs with +some signal is also taken into account [1]_. The variables that +control this filtering are provided in the parameters +``{s1,s2}_params`` and are defined as follows: + +- ``{s1,s2}_w{min,max}``: minimum/maximum width of S1/S2 peaks +- ``{s1,s2}_h{min,max}``: minimum/maximum height of S1/S2 peaks in a 1-:math:`\mu`\ s sample +- ``{s1,s2}_e{min,max}``: minimum/maximum integral of S1/S2 peaks +- ``{s1,s2}_ethr``: threshold applied to the PMT-summed waveform to compute the quantities above +- ``{s1,s2}_n{min,max}``: minimum/maximum number of S1/S2 peaks that satisfy *all* of the criteria above for given event +- ``s2_nsipm{min,max}``: minimum/maximum number of SiPMs with signal in an S2 peak + +.. [1] Bear in mind that :doc:`irene` requires a minimum amount of + charge per peak and per slice for the SiPM to be considered. + + +.. _Build event summary: + +Build event summary +::::::::::::::::::: + +This part of the processing is equivalent to :doc:`dorothea` using +``global_reco_algo`` and ``global_reco_params``. See that city's +documentation for more details. + +.. _Resampling and hit creation: + +Resampling and hit creation +::::::::::::::::::::::::::: + +In numerous ocasions, the energy deposition in a 1-:math:`\mu`\ s +sample is not enough to produce a significant signal in the SiPMs, +which results in poor reconstruction. It is therefore useful to be +able to resample the waveforms and increase the sampling period (lower +sampling rate). The variable that controls this resampling is +``rebin`` and it specifies how many consecutive 1-:math:`\mu`\ s +slices are added up together. A value of ``rebin = 1`` means no +resampling is performed. Only integer values greater than or equal to +1 are accepted. + +Unlike *Penthesilea*, *Sophronia* considers the response of a SiPM in +a single (resampled) slice a *Hit*. Hits are defined as the +aggregation of the absolute position of the SiPM, the time difference +between the slice and the S1 peak time [2]_, the amplitude of the SiPM +waveform (charge) and the energy corresponding to said charge. The +corresponding energy is defined as + +.. math:: + + E_i = \frac{Q_i}{\sum_{k=0}^{N} Q_{k}} E_{slice} + +where :math:`Q_i` and :math:`E_i` are the charge and corresponding +energy of SiPM :math:`i`, respectivly; :math:`N` is the number of +SiPMs with signal in the slice and :math:`E_{slice}` is the energy of +the slice, given by the amplitude of the PMT-summed waveform in the +slice. + +.. [2] This information is used to obtain the z position of the hit by + dividing the time difference by the drift velocity + (``drift_v``). + + +.. _Hit merging: + +Hit merging +::::::::::: + +In some occasions, a time slice might have no SiPMs recorded. This +means that all SiPM waveforms have been disregarded in :doc:`irene` or +that no SiPM has a charge above ``q_thr`` in such slice. However, +because the slice is considered part of a peak, there is some energy +associated to it, which should not be discarded. In these cases, +*Sophronia* generates a fake hit (a.k.a. *NN-hits*) with no charge and +no position associated [3]_. + +After all hits are generated, a second step is performed, in which the +fake hits are merged with existing valid hits. This operation searches +for the hits that are closest (in z) to the fake one. Each fake hit's +energy is shared among its neighbours and added to the neighbouring +slice energy. The energy is not share homogeneously, but +proportionally to the charge of each hit. The parameter ``same_peak`` +controls whether only slices from the same peak are taken into account +or if other peaks might also be taken into consideration. + +.. [3] Actually, the algorithm associates an unphysical number to the + position (0) and the charge (NN = -99999). + +.. _Hit correction: + +Hit correction +:::::::::::::: + +If a correction map is provided (``corrections_file``), the +geometrical and lifetime corrections are applied. These corrections +are composed of three factors: + +- geometrical: accounts for different light collection efficiencies in + x,y +- lifetime: accounts for the loss of electrons (and therefore signal) + due to electron attachment during the drift +- temporal: chages in the previous two corrections over time. This is + applied only in data, as MC has no temporal dependence. + +The geometrical correction is a 2d-function: given the hit position in +x,y, we obtain a factor that normalizes the response to the center of +the chamber. It may also scale the response to different units +(pes-to-keV, for instance). + +The lifetime correction is a 3d-function: given the hit position in +x,y,z we obtain the correction factor that normalizes the response to +that of z=0. + +The temporal correction is a 1d-function: given the time since the +start of the run, we estimate variations in the geometrical and +lifetime corrections that normalize the responso to that of the +beginning of the run. This correction is only applied if +``apply_temp`` is set to ``True``. From c38890edaf2a9512fd386b7645aa79f01e228a48 Mon Sep 17 00:00:00 2001 From: Gonzalo Martinez Lema Date: Tue, 13 Feb 2024 10:42:25 +0100 Subject: [PATCH 02/12] Reword explanation about S1 selection --- docs/source/sophronia.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/sophronia.rst b/docs/source/sophronia.rst index 17e7fd5..24c7889 100644 --- a/docs/source/sophronia.rst +++ b/docs/source/sophronia.rst @@ -11,8 +11,8 @@ dimensional coordinates with an associated energy (PMT signal) and charge (SiPM signal). The city contains a peak/event filter, which can be configured to find events with a certain number of S1/S2 signals that satisfy certain properties. Currently, the city is designed to -accept only 1 S1 signal and will take the first S1 signal even if the -filter is configured to take more than 1 S1. Furthermore, hits can be +accept only 1 S1 signal. If the configuration allows for more than one +S1, the first one will be used to estimate z. Furthermore, hits can be optionally corrected for geometrical and lifetime effects. Besides hits, the city also stores the global (x, y) position of each S2 signal. The tasks performed are: From d3412e81d550d4da3b6bf828599bb411f198b02b Mon Sep 17 00:00:00 2001 From: Gonzalo Martinez Lema Date: Tue, 13 Feb 2024 10:42:49 +0100 Subject: [PATCH 03/12] Reword `drift_v` doc --- docs/source/sophronia.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/sophronia.rst b/docs/source/sophronia.rst index 24c7889..4a2d6cb 100644 --- a/docs/source/sophronia.rst +++ b/docs/source/sophronia.rst @@ -62,7 +62,7 @@ Besides the :ref:`Common arguments to every city`, *Sophronia* has the following * - ``drift_v`` - ``float`` - - Drift velocity. Used to make the correspondence between drift time and z position + - Drift velocity. Used to make calculate the z poisition from the drift time. * - ``s1_params`` - ``dict`` From 8789ae2616584f4a00b59245d8f04a2770899978 Mon Sep 17 00:00:00 2001 From: Gonzalo Martinez Lema Date: Tue, 13 Feb 2024 10:43:23 +0100 Subject: [PATCH 04/12] Fix incorrect footnote --- docs/source/sophronia.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/sophronia.rst b/docs/source/sophronia.rst index 4a2d6cb..7605665 100644 --- a/docs/source/sophronia.rst +++ b/docs/source/sophronia.rst @@ -216,8 +216,8 @@ proportionally to the charge of each hit. The parameter ``same_peak`` controls whether only slices from the same peak are taken into account or if other peaks might also be taken into consideration. -.. [3] Actually, the algorithm associates an unphysical number to the - position (0) and the charge (NN = -99999). +.. [3] Actually, the algorithm associates an unphysical charge (NN = + -999999) and a position :math:`x = y = 0`. .. _Hit correction: From 3eedab4fec2f3b82bf38325b2cabcf90f3ef3550 Mon Sep 17 00:00:00 2001 From: Gonzalo Martinez Lema Date: Tue, 13 Feb 2024 10:43:34 +0100 Subject: [PATCH 05/12] Fix typos --- docs/source/sophronia.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/sophronia.rst b/docs/source/sophronia.rst index 7605665..77263d9 100644 --- a/docs/source/sophronia.rst +++ b/docs/source/sophronia.rst @@ -232,7 +232,7 @@ are composed of three factors: x,y - lifetime: accounts for the loss of electrons (and therefore signal) due to electron attachment during the drift -- temporal: chages in the previous two corrections over time. This is +- temporal: changes in the previous two corrections over time. This is applied only in data, as MC has no temporal dependence. The geometrical correction is a 2d-function: given the hit position in @@ -246,6 +246,6 @@ that of z=0. The temporal correction is a 1d-function: given the time since the start of the run, we estimate variations in the geometrical and -lifetime corrections that normalize the responso to that of the +lifetime corrections that normalize the response to that of the beginning of the run. This correction is only applied if ``apply_temp`` is set to ``True``. From 87c65c24339825872175660f70205e2febe0bbf2 Mon Sep 17 00:00:00 2001 From: Gonzalo Martinez Lema Date: Tue, 13 Feb 2024 10:52:23 +0100 Subject: [PATCH 06/12] More typo fixing --- docs/source/sophronia.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/sophronia.rst b/docs/source/sophronia.rst index 77263d9..57f6d04 100644 --- a/docs/source/sophronia.rst +++ b/docs/source/sophronia.rst @@ -62,7 +62,7 @@ Besides the :ref:`Common arguments to every city`, *Sophronia* has the following * - ``drift_v`` - ``float`` - - Drift velocity. Used to make calculate the z poisition from the drift time. + - Drift velocity. Used to calculate the z position from the drift time. * - ``s1_params`` - ``dict`` From 317d8d763c345aa0524ac280406a55f88aaea4ba Mon Sep 17 00:00:00 2001 From: Gonzalo Martinez Lema Date: Wed, 14 Feb 2024 14:05:25 +0100 Subject: [PATCH 07/12] applies -> apply --- docs/source/sophronia.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/sophronia.rst b/docs/source/sophronia.rst index 57f6d04..351c0ea 100644 --- a/docs/source/sophronia.rst +++ b/docs/source/sophronia.rst @@ -22,7 +22,7 @@ signal. The tasks performed are: - Compute a set of hits for each slice in the resampled S2 signal. - If there are more than one hit per slice, share the energy according to the charge recorded in the tracking plane. - - If correction maps are provided, applies corrections to hits. + - If correction maps are provided, apply corrections to hits. .. _Sophronia input: From e5f8a4e2acfd31642da12d259c084ad4696e31d7 Mon Sep 17 00:00:00 2001 From: Gonzalo Martinez Lema Date: Wed, 14 Feb 2024 14:05:40 +0100 Subject: [PATCH 08/12] Describe input --- docs/source/sophronia.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/sophronia.rst b/docs/source/sophronia.rst index 351c0ea..d832bb6 100644 --- a/docs/source/sophronia.rst +++ b/docs/source/sophronia.rst @@ -29,11 +29,11 @@ signal. The tasks performed are: Input ----- - * ``/Run/events`` - * ``/Run/runInfo`` - * ``/PMAPS/S1`` - * ``/PMAPS/S2`` - * ``/PMAPS/S2Si`` + * ``/Run/events``: Table containing the event number and timestamps + * ``/Run/runInfo``: Table containing the run number for each event + * ``/PMAPS/S1``: Table containing S1 pmt-summed peak information + * ``/PMAPS/S2``: Table containing the S2 pmt-summed peak information + * ``/PMAPS/S2Si``: Table containing the S2 sipm peak information .. _Sophronia output: From b85c00350e27ba29938a7384362e918840204428 Mon Sep 17 00:00:00 2001 From: Gonzalo Martinez Lema Date: Wed, 14 Feb 2024 14:05:50 +0100 Subject: [PATCH 09/12] Remove full stop at the end of bullet points --- docs/source/sophronia.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/sophronia.rst b/docs/source/sophronia.rst index d832bb6..69be74d 100644 --- a/docs/source/sophronia.rst +++ b/docs/source/sophronia.rst @@ -40,8 +40,8 @@ Input Output ------ - * ``/DST/Events``: summary of the S1 and S2 information of the reconstructed events. See :doc:`dorothea` for more details. - * ``/RECO/Events``: list of hit data for each event. + * ``/DST/Events``: summary of the S1 and S2 information of the reconstructed events. See :doc:`dorothea` for more details + * ``/RECO/Events``: list of hit data for each event * ``/Filters/s12_selector``: flag for whether an event passed the S1 and S2 selections * ``/Filters/valid_hit``: flag for whether an event passed the empty pmap filter @@ -62,7 +62,7 @@ Besides the :ref:`Common arguments to every city`, *Sophronia* has the following * - ``drift_v`` - ``float`` - - Drift velocity. Used to calculate the z position from the drift time. + - Drift velocity. Used to calculate the z position from the drift time * - ``s1_params`` - ``dict`` From e65cf870079ebb39abda982285a2f5ac6ebab31d Mon Sep 17 00:00:00 2001 From: Gonzalo Martinez Lema Date: Wed, 14 Feb 2024 14:06:28 +0100 Subject: [PATCH 10/12] Minor rewording --- docs/source/sophronia.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/sophronia.rst b/docs/source/sophronia.rst index 69be74d..baaffa8 100644 --- a/docs/source/sophronia.rst +++ b/docs/source/sophronia.rst @@ -82,11 +82,11 @@ Besides the :ref:`Common arguments to every city`, *Sophronia* has the following * - ``rebin`` - ``int`` - - Specifies the level of resampling or grouping of consecutive samples for reconstruction. Must be :math:`\geq` 1 + - Level of resampling or grouping of consecutive samples for reconstruction. Must be :math:`\geq` 1 * - ``rebin_method`` - ``RebinMethod`` - - Which resampling method to use (usually stride) + - Resampling method (usually stride) * - ``q_thr`` - ``float`` From 417e33fb86099a26ab96a98037ee09d90822a117 Mon Sep 17 00:00:00 2001 From: Gonzalo Martinez Lema Date: Wed, 14 Feb 2024 14:08:27 +0100 Subject: [PATCH 11/12] Fix order of pmap filtering parameters --- docs/source/sophronia.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/sophronia.rst b/docs/source/sophronia.rst index baaffa8..6ad73b3 100644 --- a/docs/source/sophronia.rst +++ b/docs/source/sophronia.rst @@ -141,8 +141,8 @@ control this filtering are provided in the parameters - ``{s1,s2}_h{min,max}``: minimum/maximum height of S1/S2 peaks in a 1-:math:`\mu`\ s sample - ``{s1,s2}_e{min,max}``: minimum/maximum integral of S1/S2 peaks - ``{s1,s2}_ethr``: threshold applied to the PMT-summed waveform to compute the quantities above -- ``{s1,s2}_n{min,max}``: minimum/maximum number of S1/S2 peaks that satisfy *all* of the criteria above for given event - ``s2_nsipm{min,max}``: minimum/maximum number of SiPMs with signal in an S2 peak +- ``{s1,s2}_n{min,max}``: minimum/maximum number of S1/S2 peaks that satisfy *all* of the criteria above for given event .. [1] Bear in mind that :doc:`irene` requires a minimum amount of charge per peak and per slice for the SiPM to be considered. From 9a9e1d3b91b3ceb1bf65677e20d175ea55098590 Mon Sep 17 00:00:00 2001 From: Gonzalo Martinez Lema Date: Wed, 14 Feb 2024 14:08:52 +0100 Subject: [PATCH 12/12] Fix typos --- docs/source/sophronia.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/sophronia.rst b/docs/source/sophronia.rst index 6ad73b3..f79d2cd 100644 --- a/docs/source/sophronia.rst +++ b/docs/source/sophronia.rst @@ -129,7 +129,7 @@ Peak filtering :doc:`irene` finds peaks in the waveform with general characteristics, but does not impose strong requirements on them. *Sophronia*, however, -can be more specific and select S1 and S2 signals based on the +can be more specific and selects S1 and S2 signals based on the following peak properties: width, height, and integral. These quantities are calculated based on a (low) threshold applied to the PMT waveform of the peak. For S2 signals, the number of SiPMs with @@ -162,7 +162,7 @@ documentation for more details. Resampling and hit creation ::::::::::::::::::::::::::: -In numerous ocasions, the energy deposition in a 1-:math:`\mu`\ s +In numerous occasions, the energy deposition in a 1-:math:`\mu`\ s sample is not enough to produce a significant signal in the SiPMs, which results in poor reconstruction. It is therefore useful to be able to resample the waveforms and increase the sampling period (lower