Skip to content

Commit 6e0c736

Browse files
habighabig
authored
Merge pull request #164 from SNEWS2/habig_docsfix
Update the docs to match snews_pt v2.1.0
2 parents b588410 + 4ea36b5 commit 6e0c736

File tree

7 files changed

+244
-106
lines changed

7 files changed

+244
-106
lines changed

‎.github/workflows/firedrill.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -96,8 +96,8 @@ jobs:
9696
- name: Publish messages
9797
run: |
9898
echo "Publishing messages..."
99-
docker exec publishing_tools_publisher snews_pt publish /app/snews_pt/test/firedrill_combined_message.json --firedrill
100-
docker exec publishing_tools_publisher snews_pt publish /app/snews_pt/test/firedrill_combined_message2.json --firedrill
99+
docker exec publishing_tools_publisher snews_pt publish /app/snews_pt/test/firedrill_combined_message.json --firedrill --force
100+
docker exec publishing_tools_publisher snews_pt publish /app/snews_pt/test/firedrill_combined_message2.json --firedrill --force
101101
sleep 10
102102
103103
- name: Verify alert publishing from coincidence_system
@@ -180,4 +180,4 @@ jobs:
180180
fi
181181
echo "db_pipeline is still running and has not stopped or completed."
182182
echo "current db_pipeline docker logs:"
183-
docker logs db_pipeline
183+
docker logs db_pipeline

‎docs/user/command_line_interface.md‎

Lines changed: 115 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ All the commands have their short descriptions accessible via `--help` flag.
77
```
88
```bash
99
Usage: snews_pt [OPTIONS] COMMAND [ARGS]...
10+
1011
User interface for snews_pt tools
1112

1213
Options:
@@ -15,17 +16,19 @@ Options:
1516
--help Show this message and exit.
1617

1718
Commands:
18-
get-feedback Get an e-mail feedback on your heartbeats
19-
heartbeat Publish heartbeat messages.
20-
message-schema Display the message format for `tier`, default 'all'
21-
publish Publish a message using snews_pub
22-
retract Retract N latest message
23-
subscribe Subscribe to Alert topic
24-
set-name Set your detectors name
25-
reset-cache Development purposes only, requires admin pass
26-
run-scenarios Test different coincidence scenarios
27-
test-connection Test the server connection
28-
write-hb-logs Development purposes only, requires admin pass
19+
change-broker REQUIRES AUTHORIZATION | If authorized, server changes the broker
20+
get-feedback REQUIRES AUTHORIZATION | Get heartbeat feedback by email
21+
heartbeat Send Heartbeats
22+
message-schema Display the message format for each `tier`
23+
publish Publish a message using snews_pub, multiple files are allowed
24+
reset-cache REQUIRES AUTHORIZATION | Drop the current cache at the server
25+
run-scenarios Test different coincidence scenarios
26+
set-name Set your detectors name
27+
subscribe Subscribe to Alert topic
28+
test-connection Test the connection to the server
29+
write-hb-logs REQUIRES AUTHORIZATION | Print the HB logs on the server standard output
30+
31+
See https://snews-publishing-tools.readthedocs.io/en/latest/ for more details
2932
```
3033

3134
The main command `snews_pt` serves an entry point. It is also possible to set an _environment_ by passing it to this with any other command.
@@ -53,37 +56,54 @@ The subscription command can be called without any arguments.
5356
---
5457
## Sending Heartbeats
5558
```bash
56-
(venv) User$: snews_pt heartbeat -s ON -t "2023-06-02T09:27:40.882808" --firedrill
57-
Message Generated for Heartbeat
58-
----------------------------------------------------------------
59-
Sending message to Heartbeat on kafka://kafka.scimma.org/snews.experiments-firedrill
60-
_id :19_Heartbeat_2023-06-02T09:27:40.882808
61-
detector_name :XENONnT
62-
machine_time :2023-06-02T09:27:40.882808
63-
detector_status :ON
64-
meta :
65-
schema_version :1.3.0
66-
sent_time :2023-06-02T09:48:13.393969
59+
(venv) User$: snews_pt heartbeat -s ON -t "2025-06-02T09:27:40.882808" --firedrill
6760
```
6861

6962
Here the machine time refers to the time your experiment reads the data that sets ON or OFF status. There can be
7063
instances where this data has been read but could not be send to server right away, therefore, the `sent_time` is stamped at the execution.
7164

65+
The level of verbosity can be controlled with the `--verbose` (or `-v`) flag.
66+
```bash
67+
(venv) User$: snews_pt heartbeat -s ON -t "2025-06-02T09:27:40.882808" --firedrill --verbose 2
68+
Sent message to kafka://kafka.scimma.org/snews.experiments-firedrill
69+
--------------------------------
70+
id: XENONnT_Heartbeat_None
71+
uuid: 416dba19-ed18-432e-b731-25d6dd87c8d6
72+
tier: Tier.HEART_BEAT
73+
sent_time_utc: 2025-11-05T17:20:49.202042000Z
74+
machine_time_utc: None
75+
is_pre_sn: False
76+
is_test: False
77+
is_firedrill: True
78+
meta: None
79+
schema_version: 0.2
80+
detector_name: XENONnT
81+
detector_status: ON
82+
--------------------------------
83+
```
84+
7285
## Message Schemas
7386
`snews_pt message-schema` can tell you the required contents for each tiers. You can display the contents of a single tier by calling e.g.
7487
```bash
75-
(venv) User$: snews_pt message-schema time
88+
(venv) User$: snews_pt message-schema CoincidenceTier
7689
```
7790
In which case it displays the following
7891
```bash
79-
> Message schema for SNEWSTimingTierMessage
80-
_id : (SET AUTOMATICALLY)
81-
schema_version : (SET AUTOMATICALLY)
82-
detector_name : (SET AUTOMATICALLY)
83-
timing_series : (REQUIRED USER INPUT)
84-
machine_time : (USER INPUT)
85-
p_val : (USER INPUT)
92+
> Message schema for CoincidenceTier
93+
id : (USER INPUT)
94+
uuid : (USER INPUT)
95+
tier : (REQUIRED USER INPUT)
96+
sent_time_utc : (USER INPUT)
97+
machine_time_utc : (USER INPUT)
98+
is_pre_sn : (USER INPUT)
8699
is_test : (USER INPUT)
100+
is_firedrill : (USER INPUT)
101+
meta : (USER INPUT)
102+
schema_version : (USER INPUT)
103+
detector_name : (REQUIRED USER INPUT)
104+
p_val : (USER INPUT)
105+
neutrino_time_utc : (REQUIRED USER INPUT)
106+
**kwargs : (GROUPED AS META)
87107
```
88108
or you can simply call `snews_pt message-schema all` to display all the message schemes. <br>
89109

@@ -96,28 +116,40 @@ The simplest JSON file that you can publish using the CLI would contain the foll
96116
```json
97117
# in my_message.json
98118
{
99-
"neutrino_time" : "2023-06-02T09:48:13.393969"
119+
"detector_name":
120+
"DUNE",
121+
"neutrino_time_utc":
122+
"2025-10-30T15:44:12.345275"
100123
}
101124
```
102-
assuming you set your detector name already. In which case, only the `"neutrino_time"` argument is parsed and `SNEWSTierPublisher` is invoked.
125+
In which case, only the `"neutrino_time_utc"` argument is parsed and the CoincidenceTierPublisher is invoked.
103126

104127
**Publish using the CLI**
105128
```bash
106129
(venv) User$: snews_pt publish my_message.json --firedrill
107-
108-
Message Generated for CoincidenceTier
109-
----------------------------------------------------------------
110-
Sending message to CoincidenceTier on kafka://kafka.scimma.org/snews.experiments-firedrill
111-
_id :19_CoincidenceTier_2023-06-02T10:04:27.400593
112-
detector_name :XENONnT
113-
machine_time :2023-06-02T10:04:27.400593
114-
neutrino_time :2023-06-02T09:48:13.393969
115-
p_val :None
116-
meta :
117-
is_test :False
118-
schema_version :1.3.0
119-
sent_time :2023-06-02T10:04:27.461761
120130
```
131+
The level of verbosity can be controlled with the `--verbose` (or `-v`) flag.
132+
```bash
133+
(venv) User$: snews_pt publish my_message.json --firedrill --verbose 2
134+
Sent message to kafka://kafka.scimma.org/snews.experiments-firedrill
135+
--------------------------------
136+
id: DUNE_CoincidenceTier_None
137+
uuid: 0a2124c0-5069-4e31-ac03-cb3e8ba45f08
138+
tier: Tier.COINCIDENCE_TIER
139+
sent_time_utc: 2025-11-05T17:43:04.865601000Z
140+
machine_time_utc: None
141+
is_pre_sn: False
142+
is_test: False
143+
is_firedrill: False
144+
meta: None
145+
schema_version: 0.2
146+
detector_name: DUNE
147+
p_val: None
148+
neutrino_time_utc: 2025-11-05T10:52:13.345275000Z
149+
--------------------------------
150+
```
151+
152+
**Note**: For authentication purposes, the detector name is read from the environment file. If the detector name in the JSON file does not match the detector name in the environment file, a warning is printed and the detector name from the environment file is used.
121153

122154
## Retraction Messages
123155

@@ -126,37 +158,50 @@ These are also messages created by `SNEWSTierPublisher` with some specific keys.
126158
Let's first check what arguments belong to retraction message.
127159

128160
```bash
129-
(snews) kara-unix@iap-nb-034:~$ snews_pt message-schema retract
130-
> The Message Schema for FalseOBS
131-
_id :(SNEWS SETS)
132-
schema_version :(SNEWS SETS)
133-
detector_name :(FETCHED FROM ENV XENONnT)
134-
machine_time :(User Input)
135-
retract_latest :(User Input*)
136-
retraction_reason :(User Input)
137-
**kwargs :(APPENDED AS 'META')
161+
$ snews_pt message-schema Retraction
162+
Message schema for Retraction
163+
id : (USER INPUT)
164+
uuid : (USER INPUT)
165+
tier : (REQUIRED USER INPUT)
166+
sent_time_utc : (USER INPUT)
167+
machine_time_utc : (USER INPUT)
168+
is_pre_sn : (USER INPUT)
169+
is_test : (USER INPUT)
170+
is_firedrill : (USER INPUT)
171+
meta : (USER INPUT)
172+
schema_version : (USER INPUT)
173+
detector_name : (REQUIRED USER INPUT)
174+
retract_message_uuid : (USER INPUT)
175+
retract_latest_n : (USER INPUT)
176+
retraction_reason : (USER INPUT)
177+
**kwargs : (GROUPED AS META)
138178
```
139-
The fields with the asterisk `*` is the keyword that is needed to select this tier. In this case, input should have `retract_latest` key in order to create a retraction message.
179+
The fields with REQUIRED USER INPUT are the keywords that are needed to select this tier. In this case, input should have `retract_latest_n` key in order to create a retraction message for the last two messages from the detector named `DUNE`
140180
```json
141181
# in retract_message.json
142182
{
143-
"retract_latest" : 2
183+
"detector_name": "DUNE",
184+
"retract_latest_n" : 2
144185
}
145186
```
146187

147188
```bash
148-
(venv) User$: snews_pt publish retract_message.json --firedrill
149-
Message Generated for Retraction
150-
----------------------------------------------------------------
151-
Sending message to Retraction on kafka://kafka.scimma.org/snews.experiments-firedrill
152-
IT'S OKAY, WE ALL MAKE MISTAKES
153-
_id :19_Retraction_2023-06-02T10:12:01.001552
154-
detector_name :XENONnT
155-
machine_time :2023-06-02T10:12:01.001552
156-
retract_latest :2
157-
retraction_reason :None
158-
meta :
159-
is_test :False
160-
schema_version :1.3.0
161-
sent_time :2023-06-02T10:12:01.049846
189+
(venv) User$: snews_pt publish retract_message.json --firedrill --verbose 2
190+
Sent message to kafka://kafka.scimma.org/snews.experiments-test
191+
--------------------------------
192+
id: XENONnT_Retraction_None
193+
uuid: ad822786-9644-462a-8740-c7f9884de7ec
194+
tier: Tier.RETRACTION
195+
sent_time_utc: 2025-11-06T20:20:14.548049000Z
196+
machine_time_utc: None
197+
is_pre_sn: False
198+
is_test: False
199+
is_firedrill: False
200+
meta: None
201+
schema_version: 0.2
202+
detector_name: XENONnT
203+
retract_message_uuid: None
204+
retract_latest_n: 1
205+
retraction_reason: None
206+
--------------------------------
162207
```

‎docs/user/firedrills.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,9 @@ We would like to test two main interactions; **subscribing** & **publishing** t
4646
```python
4747
from snews_pt.messages import SNEWSMessageBuilder
4848
SNEWSMessageBuilder(detector_name='KamLAND',
49-
neutrino_time="2022-02-28T04:31:08.678999",
49+
neutrino_time_utc="2022-02-28T04:31:08.678999",
5050
p_val=0.000007,
51-
machine_time="2022-02-28T04:31:09.778859",
51+
machine_time_utc="2022-02-28T04:31:09.778859",
5252
firedrill_mode=True,
5353
is_test=True,
5454
).send_messages()

‎docs/user/installation.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,14 +24,14 @@ or from the source using ssh-key,
2424
```bash
2525
git clone git@github.com:SNEWS2/SNEWS_Publishing_Tools.git
2626
cd SNEWS_Publishing_Tools
27-
pip install ./ --user
27+
pip install ./
2828
```
2929

3030
or using https
3131
```bash
3232
git clone https://github.com/SNEWS2/SNEWS_Publishing_Tools.git
3333
cd SNEWS_Publishing_Tools
34-
pip install ./ --user
34+
pip install ./
3535
```
3636

3737
# Test the install

‎docs/user/publishing_protocols.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,11 @@ As an example, the following code creates a message for the Coincidence Tier and
2727
```python
2828
from snews_pt.messages import SNEWSMessageBuilder
2929

30-
messages = SNEWSMessageBuilder(neutrino_time="2022-02-28T04:31:08.678999")
30+
messages = SNEWSMessageBuilder(neutrino_time_utc="2022-02-28T04:31:08.678999")
3131
messages.send_messages()
3232
```
3333

34-
Since in this example, only the `neutrino_time` is passed, the message is created for the Coincidence Tier. This also assumes that the detector name has already been set by `snews_pt.snews_pt_utils.set_name()` function.
34+
Since in this example, only the `neutrino_time_utc` is passed, the message is created for the Coincidence Tier. This also assumes that the detector name has already been set by `snews_pt.snews_pt_utils.set_name()` function.
3535

3636
The messages are validated upon creation and if the required fields are not passed, or the format is wrong the software raises an error.
3737
Furthermore, the `messages` objects can be inspected before sending them to the SNEWS server. It contains information about the selected tiers and the generated messages.
@@ -47,7 +47,7 @@ messages.send_messages()
4747
Where the `myjsonfile.json` contains the following information;
4848
```json
4949
{
50-
"neutrino_time" : "2022-02-28T04:31:08.678999"
50+
"neutrino_time_utc" : "2022-02-28T04:31:08.678999"
5151
}
5252
```
5353

@@ -63,4 +63,4 @@ Where the `firedrill_mode` argument is used to select the firedrill topic from t
6363
The same functionalities can be achieved using the command line interface. The following command sends the message in the file `myjsonfile.json` to the SNEWS server.
6464
```bash
6565
snews_pt publish myjsonfile.json --firedrill
66-
```
66+
```

0 commit comments

Comments
 (0)