Project

General

Profile

Introduction to the nightsum » History » Version 11

Stephen Kent, 08/22/2014 03:09 PM

1 1 Marc testing Mengel
h1. Introduction to the nightsum
2 1 Marc testing Mengel
3 3 Eric Neilsen
The nightsum reports are automatically generated summaries taken from the electronic logbook and other sources at the end of every night. It is meant to provide an overview of the DES activities at the mountain top. Every morning, a report will be posted to the "nightsum web page":http://decam03.fnal.gov:8080/nightsum/ by the observers. The reports are archived by night. 
4 1 Marc testing Mengel
5 2 Marc testing Mengel
We encourage people in the collaboration to include the nightsum in their morning reading routine (username is "DES", password is the same as for docdb). In the nightsum you will find information about the observing team, the night's plan, accomplishments, and problems. There is also a list of all the exposures taken that night, and links to relevant logbook entries containing in-depth information. Here is one "example":http://decam03.fnal.gov:8080/nightsum/nightsum-56196/nightsum.html
6 1 Marc testing Mengel
7 1 Marc testing Mengel
h2. Electronic Logbook and nightsum
8 1 Marc testing Mengel
9 1 Marc testing Mengel
For the automatic nighsum tool to work properly, the logbook entries have to be a little bit organized. One observer has to take the role of the 'logger' and make sure that the entries that go into the nightsum are meaningful. There are 3 special logbook Categories (they are called @Synopsis_*@) and a special tag (summary) that the nightsum listen to.  Other observers and users of the logbook should not make entries in those categories without informing the 'logger'. Here is a description of the categories/tags:
10 1 Marc testing Mengel
11 6 Stephen Kent
* *Synopsis_Night:* Only one entry of this category can be included per night. The entry should include information about the observing team, the plan for the night and the accomplishments (here is an "example":http://system1.ctio.noao.edu:8080/ECL/decam/E/show?e=11586). Here is a template that observers have found useful. Login as DECamObserver on observer2 and see /usr/remote/user/DECamObserver/annis/log_template.txt.  We are now including Notes to Data Management on exposures to ignore, etc.
12 1 Marc testing Mengel
13 2 Marc testing Mengel
* *Synopsis_Engineering:* All entries in this category will be included. They should inform briefly about any planned engineering/debugging activity, saying what was done, and what results were obtained. (here is an "example":http://system1.ctio.noao.edu:8080/ECL/decam/E/show?e=11341)
14 1 Marc testing Mengel
15 2 Marc testing Mengel
* *Synopsis_Problem:* All entries in this category will be included. This should inform briefly about a problem that disturbed the night's progress in either engineering or science activity (here is an "example":http://system1.ctio.noao.edu:8080/ECL/decam/E/show?e=11602)
16 1 Marc testing Mengel
17 2 Marc testing Mengel
* *summary:* This is a tag to be attached to any other entry that doesn't fall in any of the above. Entries flagged with the summary tag will show up in a section called "Other Issues".
18 1 Marc testing Mengel
19 1 Marc testing Mengel
Detailed descriptions of problems and procedures taken during the night are better handled via links, ie, you make a short entry in the relevant Synopsis category with a link to a longer detailed entry in another category. 
20 1 Marc testing Mengel
21 2 Marc testing Mengel
The nightsum can handle html/wiki-like markups and attached images the same way as the logbook.   You must click the "Textile formatted" checkbox  on the new entries window for the logbook to recognize the wiki formatting. You should be able to preview the formatted entry using new entries window button.
22 1 Marc testing Mengel
23 1 Marc testing Mengel
h2. Instructions on how to create the nightsum (for observers)
24 1 Marc testing Mengel
25 6 Stephen Kent
The publishing step requires one be logged in as sispi, so it is easiest to do all preparation from the sispi account.
26 1 Marc testing Mengel
27 11 Stephen Kent
* log into observer2 (not any other machine) as user sispi
28 1 Marc testing Mengel
29 1 Marc testing Mengel
* set up the environment:
30 1 Marc testing Mengel
  @ $ setup nightsum @
31 1 Marc testing Mengel
32 1 Marc testing Mengel
* run the makesum script: 
33 1 Marc testing Mengel
  @ $ cd ~sispi/nightsum-reports @
34 5 Eric Neilsen
  @ $ makesum @
35 1 Marc testing Mengel
36 7 Stephen Kent
* The step above will create a dir named nightsum-<YYYY>-<MM>-<DD>. You can check the results by pointong your browser to 
37 1 Marc testing Mengel
  @ file:///usr/remote/user/sispi/nightsum-reports/nightsum-<YYYY>-<MM>-<DD>/nightsum.html @
38 5 Eric Neilsen
39 5 Eric Neilsen
Alternately, @makesum@ can open the newly generate summary automatically using the @-o@ option:
40 5 Eric Neilsen
41 5 Eric Neilsen
  @ $ makesum -o @  
42 1 Marc testing Mengel
43 1 Marc testing Mengel
* Go to the logbook and make changes as needed. Repeat the makesum step until you are happy with the results.
44 1 Marc testing Mengel
45 1 Marc testing Mengel
* Then, publish the results so it shows up on the web server on decam03.fnal.gov:
46 1 Marc testing Mengel
47 1 Marc testing Mengel
  @ $ cd ~sispi/nightsum-reports @
48 1 Marc testing Mengel
  @ $ pubsum @
49 1 Marc testing Mengel
50 6 Stephen Kent
* If you need to edit or republish an old nightsum-report,
51 6 Stephen Kent
  @ makesum -D yyyy-mm-dd @
52 6 Stephen Kent
  @ pubsum -D yyyy-mm-dd @
53 6 Stephen Kent
54 1 Marc testing Mengel
h2. Monitoring a draft of the night summary
55 1 Marc testing Mengel
56 1 Marc testing Mengel
A web server can be started that shows a current draft of the night summary, as follows:
57 1 Marc testing Mengel
58 1 Marc testing Mengel
* log into observer2 as user DECamObserver
59 1 Marc testing Mengel
60 1 Marc testing Mengel
* set up the environment:
61 1 Marc testing Mengel
  @ $ setup nightsum @
62 1 Marc testing Mengel
63 1 Marc testing Mengel
* start the server:
64 1 Marc testing Mengel
  @ $ NightSummarizer ~DECamObserver/nightsum-config @
65 1 Marc testing Mengel
66 3 Eric Neilsen
The draft will appear (slowly) in [[http://observer2.ctio.noao.edu:8899/nightsum]]
67 1 Marc testing Mengel
68 1 Marc testing Mengel
If you want to change the port number or host on which it is run, you can edit @ ~DECamObserver/nightsum-config/NightSummarizerServer.config @
69 1 Marc testing Mengel
The host name in this configuration file must match the name of the host on which the server is being started.
70 1 Marc testing Mengel
71 1 Marc testing Mengel
72 1 Marc testing Mengel
h2. Advice on level of detail
73 1 Marc testing Mengel
74 1 Marc testing Mengel
The best way to understand what content should be included in the summary is to consider the purpose and audience of the summary as a whole, and of each section.
75 1 Marc testing Mengel
76 1 Marc testing Mengel
The following are some primary uses of the log:
77 1 Marc testing Mengel
* Any collaborator might follow the summary to see how DES data collection is going.
78 1 Marc testing Mengel
* DES observers might monitor the summary for observing procedure changes, problems to look out for, and other things they might need to know to prepare them for their next observing run.
79 1 Marc testing Mengel
* Data processing staff will read the summary to see if there is anything they need to be aware of in processing that night's data. For example, if there are images with bad headers that need to be fixed by hand before processing, there should be some indication of it in the summary.
80 1 Marc testing Mengel
* DES developers, engineers, and managment will read the summary to see what tests and other requested non-science activities were done. 
81 1 Marc testing Mengel
* If anomalies in the data are discovered by anyone (scientists, data processing staff, et al.), the night summary should tell them if the observers knew anything that might be a likely cause. 
82 1 Marc testing Mengel
83 2 Marc testing Mengel
In each case, the summary is not expected to contain all information needed to explore any given issue. It should, however, contain enough information to let anyone reading the summary know what issues were relevant to that night, and links and other references to any additional resources. A typical "test" entry might include two sentences describing the test, a link to a document in docdb that describes the test, links to any electronic logbook entries related with more details, and a list of related exposure IDs.
84 1 Marc testing Mengel
85 2 Marc testing Mengel
Remember, the summary is intended to be quickly scanned by many people who might be checking for specific things. Too much detail is almost as bad as too little. It should, however, contain enough information that "absence of evidence" can be taken as "evidence of absence." If someone looks in the summary and doesn't see any mention of a given test, he or she should be confident that the test was not performed. If someone looks in the summary and doesn't see any problems related to a given system, he or she should be confident that the observers didn't notice any problems with that system.
86 1 Marc testing Mengel
87 1 Marc testing Mengel
h2. Questions asked (if not frequently, at least once)
88 1 Marc testing Mengel
89 1 Marc testing Mengel
h3. What is the difference between category and tags? 
90 1 Marc testing Mengel
91 2 Marc testing Mengel
Each entry has at most one (and perhaps exactly one) category, but any entry can have any number of tags, and it doesn't mater what category they are in. So, from nightsum's point of view, entries in a nightsum-related category were written with the specific purpose of going into a specific section of a night summary. The summary tag is a way the observer can label any other entry, written for whatever purpose, "hay, this is something I think everyone should see- put this in the summary!" I expect it will also be used a bit like an "other" category from the night summary point of view; it's a way to add stuff that doesn't fit anywhere else.
92 1 Marc testing Mengel
93 1 Marc testing Mengel
h3. What is the difference between problems and engineering?
94 1 Marc testing Mengel
95 1 Marc testing Mengel
An engineering task or test is an activity that is not routine science observing, but which is planned. It probably gets done because someone wanted it done. 
96 1 Marc testing Mengel
97 1 Marc testing Mengel
A problem is an unexpected occurrence that prevents you from following your plan.
98 1 Marc testing Mengel
99 1 Marc testing Mengel
So, testing a planned new obstac tactician would be engineering. On the night when it is tested, finding and dealing with bugs in it is engineering. If some other system breaks while you are doing the tests, that's a problem.
100 1 Marc testing Mengel
101 1 Marc testing Mengel
Three days later, when you were planning to science, if bugs in that code prevent you from observing, that's a problem.
102 1 Marc testing Mengel
103 1 Marc testing Mengel
Again, the easiest way to clarify things is to take the readers perspective. If I've requested that you do something unusual, I will keep an eye on the engineering section to see if you did it, and what the results were. If I'm just following the logs to see if you ran into problems with my software that I expect to be running smoothly, I will look for it in the problems section.
104 1 Marc testing Mengel
105 1 Marc testing Mengel
If this is too confusing, perhaps we should merge the sections.
106 1 Marc testing Mengel
107 1 Marc testing Mengel
h2. Known issues
108 1 Marc testing Mengel
109 6 Stephen Kent
h3. Formatting of plain text entries comes out corrupted.
110 1 Marc testing Mengel
111 2 Marc testing Mengel
The XML interface the nightsum tool uses doesn't provide the flag whether the entry uses the "textile" wiki-like markup, so the summary tool has to guess. The latest version of the electronic logbook includes a fix for this, but this version is not yet installed on the mountain. When it is, modifying nightsum to honor the flag should be straightforward.
112 1 Marc testing Mengel
113 2 Marc testing Mengel
h3. Nightsum sometimes fails when comments have special characters in them (particularly "#" and "&amp;")
114 1 Marc testing Mengel
115 1 Marc testing Mengel
This is another electronic logbook bug. I believe this is also fixed in the latest version of the logbook (not yet installed on at the observatory), but this needs to be verified.
116 1 Marc testing Mengel
117 2 Marc testing Mengel
h3. Observers currently must run the tool from the "sispi" account
118 1 Marc testing Mengel
119 1 Marc testing Mengel
Publishing the summary requires access to files only sispi should be able to read. This functionality can eventually be made part of a web interface to the draft, which can be run by the sispi account.
120 1 Marc testing Mengel
121 1 Marc testing Mengel
h3. Documentation and procedures need expansion
122 1 Marc testing Mengel
123 8 Eric Neilsen
h2. Additional plots and tables
124 8 Eric Neilsen
125 9 Eric Neilsen
The @nightsum@ product can produce several plots and tables not routinely made for the nightly summary. Instructions for generating them can be found [[summary tools]] page.