Add Trude documentation #12

MiryamMV · 2022-10-24T10:12:41Z

This PR adds the documentation for the city Trude.

All this info will eventually be here: https://pr012-sw-docs.readthedocs.io/en/latest/trude.html

docs/source/trude.rst

carmenromo · 2022-10-28T10:33:31Z

docs/source/trude.rst

+Baseline subtraction of SiPM waveforms
+::::::::::::::::::::::::::::::::::::::
+
+Same procedure as described in :ref:`Baseline subtraction of SiPM waveforms` section of the *Irene* documentation with the option of using the mean instead of the mode of the waveform for the baseline subtraction.


This link does not go to Irene's section. It is connected with the title of this part.

And also Irene must be referenced using :doc:name_city.

I think I managed to fix this, let me know.

carmenromo · 2022-10-28T10:36:49Z

docs/source/trude.rst

+
+Same procedure as described in :ref:`Baseline subtraction of SiPM waveforms` section of the *Irene* documentation with the option of using the mean instead of the mode of the waveform for the baseline subtraction.
+
+Spectrum histogram


This section does not have a link associated, like the other two. Is this on purpose?

docs/source/trude.rst

carmenromo · 2022-10-28T11:16:40Z

docs/source/trude.rst

+Baseline subtraction of SiPM waveforms
+::::::::::::::::::::::::::::::::::::::
+
+Same procedure as described in :ref:`Baseline subtraction of SiPM waveforms` section of the *Irene* documentation with the option of using the mean instead of the mode of the waveform for the baseline subtraction.


And also Irene must be referenced using :doc:name_city.

joshgrocott

Overall, I could understand everything well, most of my comments are just suggestions that may improve clarity :)

joshgrocott · 2023-01-17T16:35:41Z

docs/source/trude.rst

-  This page is currently not created, we are working on it. If you would like to contribute on this documentation, reach `me <helena.almamol@gmail.com>`_!
+*From Germanic, Gertrud, hypocorism: female friend.*
+
+This city produces the light and dark spectrum of SiPMs for dedicated calibration runs. This is achieved by selecting regions in the SiPM waveforms where LED pulses are expected and regions which end 2 microseconds before, respectively and integrating the content within each region. The regions before LED pulses should only contain electronics noise and dark counts giving the zero external light approximation whereas those in time with the pulses will contain one or more detected photoelectrons. The waveform integrals are split into two groups: those with expected photoelectrons (light) and those without expected photoelectrons (dark). Each group produces a different spectrum.


Is there any reason why 2 microseconds was the chosen time before the expected region? I understand this guarantees that the two types of region don't overlap, but why was 2 microseconds chosen instead of 3 microseconds for example? If this is unimportant then you can ignore this comment

My guess is it is just to avoid the overlapping of both regions. @carmenromo is more experienced in using this code, perhaps she knows a better reason for this.

I think due to the pulse length 2 microseconds were enough to get the dark spectrum. But Andrew took the decision before we got into calibration :).

Maybe it could be included on the text that this value is hardcoded and chosen to avoid overlap of both spectrums. I think it's not explained and it's a fair question.

docs/source/trude.rst

joshgrocott · 2023-01-17T16:38:34Z

docs/source/trude.rst

+
+   * - ``min|max_bin``
+     - ``float``
+     - Lower/upper limit of the number of :math:`ADCs` of the waveform to be considered for the spectrum.


Could specify whether this applies to light spectrum or dark spectrum or both

Maybe I didn't understand this comment, but Trude is used to compute the spectrum (light and dark) of a given pulsed waveform. Additionally, it can be used to compute just the dark spectrum if the input is a dark waveform, but it's not the main purpose. I don't find it necessary to include this clarification here.

No worries Miryam, I think it was me who read this part wrong!

docs/source/trude.rst

carmenromo · 2023-02-16T11:15:57Z

docs/source/trude.rst

- * ``/Run/runInfo``
- * ``/RD/sipmrwf``
+ * ``/Run/events``: list of the ``evt_number`` and the correspondent ``timestamp`.
+ * ``/Run/runInfo``: stores de ``run_number``.


I think here de is a typo.

joshgrocott

Clear and concise. All my comments have also been addressed. Well done Miryam!

halmamol

I've checked the PR, since @carmenromo is already out. Just few comments that could help on the documentation, and some beautification suggestions.

halmamol · 2023-05-05T11:14:45Z

docs/source/trude.rst

-  This page is currently not created, we are working on it. If you would like to contribute on this documentation, reach `me <helena.almamol@gmail.com>`_!
+*From Germanic, Gertrud, hypocorism: female friend.*
+
+This city produces the light and dark spectrum of SiPMs for dedicated calibration runs. This is achieved by selecting regions in the SiPM waveforms where LED pulses are expected and regions which end 2 microseconds before, respectively and integrating the content within each region. The regions before LED pulses should only contain electronics noise and dark counts giving the zero external light approximation whereas those in time with the pulses will contain one or more detected photoelectrons. The waveform integrals are split into two groups: those with expected photoelectrons (light) and those without expected photoelectrons (dark). Each group produces a different spectrum.


Maybe it could be included on the text that this value is hardcoded and chosen to avoid overlap of both spectrums. I think it's not explained and it's a fair question.

halmamol · 2023-05-05T11:16:23Z

docs/source/trude.rst

+     - ``int``
+     - Number of bins to be considered for the integral starting at ``integral_start``. With ``integral_start`` these values are ideally chosen to select the whole pulse of the LED.
+
+   * - ``integrals_period``


Does this have units? If so, I would add them.

It is time units, the exact unit depends on the pulse.

docs/source/trude.rst

halmamol · 2023-05-05T11:20:17Z

docs/source/trude.rst

+
+The light bins will be centered in the light pulse(s) and the dark bins are chosen as an interval of ``integral_width`` bins which ends 2 microseconds before the light pulse begins, as shown here:
+
+ .. image:: images/trude/wf_intervals.png


I think it will help when reading the documentation to have a better explanation of the parameters defined before and to which range, etc on the spectra correspond. You can check Buffy documentation as a reference.

halmamol · 2023-05-05T11:20:53Z

docs/source/trude.rst

+Spectrum histogram
+:::::::::::::::::::
+
+The last step would be the integration of the dark and light bins in order to obtain the respective spectrum histograms.


Same comment as the one before. It would be good to mention which configuration parameters are used when creating the spectrum histogram.

I think I don't understand this comment. We use all of the config parameters listed above.

MiryamMV · 2024-02-13T14:26:45Z

I added a couple more things to the documentation (including plots and changes in already existing plots). @joshgrocott feel free to take a general look to it and see if it makes sense. Any suggestions will be welcomed :)

joshgrocott · 2024-02-13T15:42:33Z

docs/source/trude.rst

+
+   * - ``integral_start``
+     - ``int``
+     - Bin where the integrals start.


We found that in Phyllis that integral_start and integral_width need to be given in microseconds, but the waveforms used were in (25 I think?) nanosecond time bins. I guess this would also be the case for trude? So would be worth mentioning in the documentation

Right, integral_start should be given in microseconds, but it's not the case for integral_width.

joshgrocott

See comment regarding time bins for integral limits

carmenromo reviewed Oct 28, 2022

View reviewed changes

halmamol requested a review from joshgrocott December 1, 2022 13:25

joshgrocott reviewed Jan 17, 2023

View reviewed changes

carmenromo reviewed Feb 16, 2023

View reviewed changes

MiryamMV force-pushed the trude branch from 7d09611 to d09ba4b Compare May 3, 2023 15:56

joshgrocott approved these changes May 4, 2023

View reviewed changes

halmamol reviewed May 5, 2023

View reviewed changes

MiryamMV added 17 commits February 12, 2024 18:16

Update Trude documentation parameters.

8736308

Add TRude information and images.

ed952c8

Add missing subtitle.

b097d93

Changes in integral_start parameter explanation.

544bd30

Add link to Spectrum histogram section.

8b3307d

Correct syntax for ADC units.

39d1bec

Correct Irene reference.

1e33385

Fix link to Irene subsection.

70b8be9

Modify subsection link.

13de094

Cosmetics.

eae0389

Add info for input.

0e10a81

Add example for the number of integrals.

80ff385

Fix typo.

703439d

Fix typo.

f626031

Fix typos.

329c377

Add hardcoded comment.

1842856

Write microseconds in math mode.

981f4a6

MiryamMV force-pushed the trude branch from 70dfd7f to 981f4a6 Compare February 12, 2024 17:17

MiryamMV added 2 commits February 13, 2024 12:35

Update image.

112ead3

Add a new image.

92b4738

Add explanation on certain parameters.

4184dfa

Correct image.

f18e0d9

joshgrocott reviewed Feb 13, 2024

View reviewed changes

Add units to parameter.

4be3c53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Trude documentation #12

Add Trude documentation #12

MiryamMV commented Oct 24, 2022 •

edited

carmenromo Oct 28, 2022

carmenromo Oct 28, 2022

MiryamMV Nov 7, 2022

carmenromo Oct 28, 2022

MiryamMV Nov 7, 2022

carmenromo Oct 28, 2022

joshgrocott left a comment

joshgrocott Jan 17, 2023

MiryamMV Feb 15, 2023

carmenromo Feb 16, 2023

halmamol May 5, 2023

joshgrocott Jan 17, 2023

MiryamMV Feb 15, 2023 •

edited

joshgrocott Feb 15, 2023

carmenromo Feb 16, 2023

MiryamMV Feb 16, 2023

joshgrocott left a comment

halmamol left a comment

halmamol May 5, 2023

halmamol May 5, 2023

MiryamMV Feb 8, 2024

halmamol May 5, 2023

halmamol May 5, 2023

MiryamMV Feb 12, 2024

MiryamMV commented Feb 13, 2024

joshgrocott Feb 13, 2024

MiryamMV Feb 14, 2024

joshgrocott left a comment


		Same procedure as described in :ref:`Baseline subtraction of SiPM waveforms` section of the Irene documentation with the option of using the mean instead of the mode of the waveform for the baseline subtraction.

		Spectrum histogram


		The light bins will be centered in the light pulse(s) and the dark bins are chosen as an interval of ``integral_width`` bins which ends 2 microseconds before the light pulse begins, as shown here:

		.. image:: images/trude/wf_intervals.png

Add Trude documentation #12

Are you sure you want to change the base?

Add Trude documentation #12

Conversation

MiryamMV commented Oct 24, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joshgrocott left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MiryamMV Feb 15, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joshgrocott left a comment

Choose a reason for hiding this comment

halmamol left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MiryamMV commented Feb 13, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joshgrocott left a comment

Choose a reason for hiding this comment

MiryamMV commented Oct 24, 2022 •

edited

MiryamMV Feb 15, 2023 •

edited