Skip to content

Commit d2ea178

Browse files
linyan-wlinyan-w
authored
Merge pull request #31 from mrguzzo/master
Merging the calibration database instruction back to SBNSoftware
2 parents d71d02b + 87cf2e9 commit d2ea178

2 files changed

Lines changed: 674 additions & 0 deletions

File tree

‎sbnd_calibration_database.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# SBND Calibration Database
2+
3+
Author: Marina Reggiani-Guzzo, PDRA at University of Edinburgh, mguzzo@ed.ac.uk
4+
5+
Last update: 23 May 2024
6+
7+
Hi there, this document contains all the information you need to know about the SBND calibration database. Please contact the author if you find any wrong/outdated information on this page.
8+
9+
**General comments**
10+
- This page is under construction, this message will be removed when the displayed information is definite!
11+
- If you are working on the SBND calibration, please check if the information for your calibration is listed below, otherwise please update [SBND Calibration Database Spreadsheet](https://docs.google.com/spreadsheets/d/1xbAhb6WnmxbwKxFc-4nnInjHdH8A50S6Zgh0mfZrSF4/edit#gid=217643219)
12+
13+
# Databases
14+
15+
There are two databases for SBND: **development database** and **production database**. The "development database" is an intermediate stage used to validate the values that will later on be uploaded to the "production database", which is the one accessed by analyser modules and simulations. That means that, every time the database needs to be updated (whether it is a value changing, or including/removing variables) it will be implemented in the "development database" first. The change should be validated by the person requesting the change, and once confirmed that everything looks ok, the changes will be pushed to the "production database".
16+
17+
# Folders
18+
19+
Each database is a set of multiple folders. Each folder contain the following 4 tables:
20+
- **table_data**: contains information about channel number and all the desired columns
21+
- **__iov_id**: automatically created. integer representing the number of uploads was done, starting from 1, it matches with iov_id in table_tag_iovs
22+
- **channel**: automatically created.
23+
- **variables**: list of variables included manually by us (find the list of these variables below)
24+
- **table_iovs**: contains information about the moment when the table was filled via the bin/write_data.py script
25+
- **iov_id**: integer representing the number of uploads was done, starting from 1
26+
- **begin_time**: automatically filled when a table it uploaded to the database (format: YYYY-MM-DD HH:MM:SS)
27+
- **active**: boolean variable indicating if table is active (flag=t) or deactive (flag=f) in the database
28+
- **table_tags**: contains a description of the uploaded data, automatically filled via the bin/tag_data.py script
29+
- **tag**: tag chosen by the user to refer to this entry, usually vXrY (eg. v1r1, v1r2)
30+
- **created**: format YYYY-MM-DD HH:MM:SS
31+
- **comments**: analougos to “commit” on GitHub, contains a brief description of the content in current version
32+
- **table_tag_iovs**: contains information linking the tag variable in table_tags to the iov_id one in table_iovs
33+
34+
This section displays a list of the variables in the database, as well as their description and unit.
35+
36+
### tpc_channelstatus
37+
- Folder description: This folder contains wire-channel specific variable information
38+
- Channel number: Represents "wire channel"
39+
- Number of rows: 11,264 (one for each wire channel)
40+
- URL with current values in Production Database:
41+
42+
| Variable Name | Type | Description | Unit |
43+
| ------------- | ---- | ----------- | ---- |
44+
| status | integer | 0=Dead, 1=Alive, 2=Abnormal | N/A |
45+
| eresponse_gain | real | Pre-amplifier response parameter (voltage ←→ charge) * | mV/fC |
46+
| eresponse_timing | real | Pre-amplifier shaping time * | us |
47+
| eresponse_k3 | real | 1st pole term in numerator * | N/A |
48+
| eresponse_k4 | real | 2nd pole term in numerator * | N/A |
49+
| eresponse_k5 | real | 1st pole term in denominator * | N/A |
50+
| eresponse_k6 | real | 2nd pole term in denominator * | N/A |
51+
52+
53+
\* More information on DocDB 35489 (slide 13).
54+
55+
### tpc_globalconstants
56+
- Folder description: This folder contains non-channel specific information
57+
- Channel number: No meaning
58+
- Number of rows: 1
59+
- URL with current values in Production Database:
60+
61+
| Variable Name | Type | Description | Unit |
62+
| ------------- | ---- | ----------- | ---- |
63+
| field_response | text | | |
64+
| sce | text | | |
65+
| e_lifetime_cosmic_etpc | real | Electron lifetime measured with muons, East TPC | ms |
66+
| e_lifetime_cosmic_etpc_err | real | Electron lifetime error measured with muons, East TPC | ms |
67+
| e_lifetime_cosmic_wtpc | real | Electron lifetime measured with muons, West TPC | ms |
68+
| e_lifetime_cosmic_wtpc_err | real | Electron lifetime error measured with muons, West TPC | ms |
69+
| e_lifetime_prm_inline | real | Electron lifetime measured with long inline purity monitor * | ms |
70+
| e_lifetime_prm_inline_err | real | Electron lifetime error measured with long inline purity monitor * | ms |
71+
| e_lifetime_prm_short | real | Electron lifetime measured with cryostat short internal purity monitor * | ms |
72+
| e_lifetime_prm_short_err | real | Electron lifetime error measured with cryostat short internal purity monitors * | ms |
73+
| e_lifetime_prm_long | real | Electron lifetime measured with cryostat long internal purity monitors * | ms |
74+
| e_lifetime_prm_long_err | real | Electron lifetime error measured with cryostat long internal purity monitors * | ms |
75+
| egain_i1_wtpc | real | Electronics gain measured with cosmic muons (assumes recombination value) for Induction 1 plane, West TPC | ADC/e- |
76+
| egain_i2_wtpc | real | Electronics gain measured with cosmic muons (assumes recombination value) for Induction 2 plane, West TPC | ADC/e- |
77+
| egain_c_wtpc | real | Electronics gain measured with cosmic muons (assumes recombination value) for Collection plane, West TPC | ADC/e- |
78+
| egain_i1_etpc | real | Electronics gain measured with cosmic muons (assumes recombination value) for Induction 1 plane, East TPC | ADC/e- |
79+
| egain_i2_etpc | real | Electronics gain measured with cosmic muons (assumes recombination value) for Induction 2 plane, East TPC | ACD/e- |
80+
| egain_c_etpc | real | Electronics gain measured with cosmic muons (assumes recombination value) for Collection plane, East TPC | ADC/e- |
81+
| diffusion_l | real | Longitudinal diffusion constant | cm2/s |
82+
| diffusion_t | real | Transverse diffusion constant | cm2/s |
83+
84+
\* More information on DocDB 33432.
85+
86+
### tpc_yz_correction
87+
- Folder description: This folder contains the non-uniformity map for the YZ plane. The map is a 2D histogram of Y=4m and Z=5m with a bin width of 5 cm on both directions. Therefore 400/5=80 bins along Y direction, and 500/5=100 bins along Z direction
88+
- Channel number: The channel number has no physical meaning. This table is better described by the bin number/edges for each entry
89+
- Number of rows: 2 (2 TPCs) x 80 (bins along Y) x 100 (bins along Z) = 16,000
90+
- URL with current values in Production Database:
91+
92+
| Variable Name | Type | Description | Unit |
93+
| ------------- | ---- | ----------- | ---- |
94+
| tpc | text | W = west TPC, E = east TPC | N/A |
95+
| ybin | integer | Bin number in Y direction, from 0 to 79 | N/A |
96+
| zbin | integer | Bin number in Z direction, from 0 to 99 | N/A |
97+
| ylow | real | Low-edge bin position in Y direction | cm |
98+
| yhigh | real | High-edge bin position in Y direction | cm |
99+
| zlow | real | Low-edge bin position in Z direction | cm |
100+
| zhigh | real | High-edge bin position in Z direction | cm |
101+
| scale | real | Non-uniformity scale for a point on the YZ plane | N/A |
102+
103+
### tpc_x_correction
104+
- Folder description: This folder contains the non-uniformity map for the X direction. The map is a 1D histogram of X=4m with a bin width of 10 cm. Therefore 400/10=40 bins along X direction
105+
- Channel number: The channel number has no physical meaning. This table is better described by the bin number/edges for each entry
106+
- Number of rows: 2 (2 TPCs) x 40 (bins along X) = 80
107+
- URL with current values in Production Database:
108+
109+
| Variable Name | Type | Description | Unit |
110+
| ------------- | ---- | ----------- | ---- |
111+
| tpc | text | W = west TPC, E = east TPC | N/A |
112+
| xbin | integer | Bin number in X direction, from 0 to 79 | N/A |
113+
| xlow | real | Low-edge bin position in X direction | cm |
114+
| xhigh | real | High-edge bin position in X direction | cm |
115+
| scale | real | Non-uniformity scale along X direction | N/A |
116+
117+
### pds_calibration
118+
- Folder description: This folder contains general information about the PDS system (reco, timing, decoding...)
119+
- Channel number: PMT channels
120+
- Number of rows: 120
121+
- URL with current values in Production Database:
122+
123+
| Variable Name | Type | Description | Unit |
124+
| ------------- | ---- | ----------- | ---- |
125+
| breakout_box | integer | Breakout box to which the PMT is connected | N/A |
126+
| caen_digitizer | integer | CAEN digitizer to which the PMT is connected | N/A |
127+
| caen_digitizer_channel | integer | CAEN digitizer channel to which the PMT is connected | N/A |
128+
| total_transit_time | real | Total transit time | ns |
129+
| reconstruct_channel | bool | Whether the channel is used for reconstruction | N/A |
130+
| cosmic_timing_correction | real | Timing correction derived from cosmic muon calibration | ns |
131+
| spe_amp | real | Mean amplitude of SPE | ADC |
132+
| spe_amp_std | real | Std of the SPE amplitude | ADC |
133+
| gauss_w_wc_power | real | Power parameter for Gauss noise filter | N/A |
134+
| gauss_wc | real | WC parameter for Gauss noise filter | GHz |
135+
| ser_vec_0 → ser_vec_550 | real | ADC count per bin (550 in total) for the Single Electron Response (SER) pulse (More info: [DocDB 38059](https://sbn-docdb.fnal.gov/cgi-bin/sso/ShowDocument?docid=38059)) | ADC |
136+
137+
138+
### crt_feb_calibration
139+
- Folder description: This folder contains CRT calibration information at a readout board level (group of 32 channels)
140+
- Channel number: FEB MAC5 address
141+
- Number of rows: 142 (140 Bern, 2 MINOS)
142+
- URL with current values in Production Database:
143+
144+
| Variable Name | Type | Description | Unit |
145+
| ------------- | ---- | ----------- | ---- |
146+
| channel (feb_mac5_address) | integer | Hardware address of physical readout board | N/A |
147+
| type | integer | 0 Bern / 1 MINOS | N/A |
148+
| t0_timing_offset_cable_length | real | Cable delay for T0 clock reset delivery | ns |
149+
| t0_timing_offset_calibrated | real | Calibrated 'other' delays for T0 clock reset delivery | ns |
150+
| t1_timing_offset_cable_length | real | Cable delay for T1 clock reset delivery | ns |
151+
| t1_timing_offset_calibrated | real | Calibrated 'other' delays for T1 clock reset delivery | ns |
152+
153+
Note the types of different numbering schemes are enumerated in this spreadsheet: https://docs.google.com/spreadsheets/d/1ReXP3Q2DuU-mO_vaQXZWj1h8NVdt6r13sBigYDvihXo/edit?usp=sharing
154+
155+
### crt_channel_calibration
156+
- Folder description: This folder contains CRT calibration information at a single channel level
157+
- Channel number: Online channel ID (100 * MAC5 + Channel #) N.B. this is different to the offline channel ID (32 * GDML ID + Channel #)
158+
- Number of rows: 4544 (4480 Bern, 64 MINOS)
159+
- URL with current values in Production Database:
160+
161+
| Variable Name | Type | Description | Unit |
162+
| ------------- | ---- | ----------- | ---- |
163+
| channel | integer | Online channel ID | N/A |
164+
| feb_mac5_address | integer | Hardware address of physical readout board | N/A |
165+
| type | integer | 0 Bern / 1 MINOS | N/A |
166+
| raw_channel_number | integer | Board readout channel 0 - 31 | N/A |
167+
| status | integer | Channel status (good, bad, quiet etc) | N/A |
168+
| pedestal | integer | Value of baseline in absence of signal | ADC |
169+
| gainfactor | real | Electronics amplification amount | PE/ADC |
170+
171+
Note the types of different numbering schemes are enumerated in this spreadsheet: https://docs.google.com/spreadsheets/d/1ReXP3Q2DuU-mO_vaQXZWj1h8NVdt6r13sBigYDvihXo/edit?usp=sharing
172+
The enumeration for the channel status is defined in this header file: https://github.com/SBNSoftware/sbnobj/blob/develop/sbnobj/SBND/CRT/CRTEnums.hh#L48-L54
173+
174+
### What happens when a variable does not exist in an older version of the database?
175+
176+
In a scenario where a variable has to be added to the database later on, it has been decided that this variable will assume the value of `-999` for older version, and therefore should be defined manually by the user when doing analysis. For example, imagine that the first version of the database contains the variables `version1=['field_response','sce']`, but then a few months we learn that we should also include `diffusion`, so the second version of the database will contain the variables `version2=['field_response','sce','diffusion']`. So what happens when someone wants to perform an analysis with an older version of the database? It will lack the information about `diffusion` in this simple example. There are two possible solutions for this situation:
177+
1. Either the latest value is assumed automatically, or
178+
2. An "error/non-physical" value (such as `-999`) is set to the variable for older versions to indicate that the variable was not measured back then.
179+
Option (1) is not ideal because the latest value might not be valid/true for an older version of the database, so we'd be risking making automated wrong assumptions. Option (2) is the one used for the SBND calibration database, which means that the analyser should make a decision of which value to use, and make sure that the assumptions taken are valid.
180+
181+
# Managing the database
182+
183+
Please find a detailed tutorial on how to manage the database here: [How to manage your database?](sbnd_calibration_database_instructions_how_to_manage.md)

0 commit comments

Comments
 (0)