Project

General

Profile

Introduction to the nightsum » History » Version 6

Stephen Kent, 09/06/2013 02:38 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 1 Marc testing Mengel
* log into observer2 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 3 Eric Neilsen
* The step above will create a dir named nightsum-<YYYY>-<MM>-<DD>. Check the results by pointong your browser to 
37 3 Eric Neilsen
  @ file:///usr/remote/user/DECamObserver/nightsum-reports/nightsum-<YYYY>-<MM>-<DD>/nightsum.html @ 
38 1 Marc testing Mengel
  @ file:///usr/remote/user/sispi/nightsum-reports/nightsum-<YYYY>-<MM>-<DD>/nightsum.html @
39 5 Eric Neilsen
40 5 Eric Neilsen
Alternately, @makesum@ can open the newly generate summary automatically using the @-o@ option:
41 5 Eric Neilsen
42 5 Eric Neilsen
  @ $ makesum -o @  
43 1 Marc testing Mengel
44 1 Marc testing Mengel
* Go to the logbook and make changes as needed. Repeat the makesum step until you are happy with the results.
45 1 Marc testing Mengel
46 1 Marc testing Mengel
* Then, publish the results so it shows up on the web server on decam03.fnal.gov:
47 1 Marc testing Mengel
48 1 Marc testing Mengel
  @ $ cd ~sispi/nightsum-reports @
49 1 Marc testing Mengel
  @ $ pubsum @
50 1 Marc testing Mengel
51 6 Stephen Kent
* If you need to edit or republish an old nightsum-report,
52 6 Stephen Kent
  @ makesum -D yyyy-mm-dd @
53 6 Stephen Kent
  @ pubsum -D yyyy-mm-dd @
54 6 Stephen Kent
55 1 Marc testing Mengel
h2. Monitoring a draft of the night summary
56 1 Marc testing Mengel
57 1 Marc testing Mengel
A web server can be started that shows a current draft of the night summary, as follows:
58 1 Marc testing Mengel
59 1 Marc testing Mengel
* log into observer2 as user DECamObserver
60 1 Marc testing Mengel
61 1 Marc testing Mengel
* set up the environment:
62 1 Marc testing Mengel
  @ $ setup nightsum @
63 1 Marc testing Mengel
64 1 Marc testing Mengel
* start the server:
65 1 Marc testing Mengel
  @ $ NightSummarizer ~DECamObserver/nightsum-config @
66 1 Marc testing Mengel
67 3 Eric Neilsen
The draft will appear (slowly) in [[http://observer2.ctio.noao.edu:8899/nightsum]]
68 1 Marc testing Mengel
69 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 @
70 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.
71 1 Marc testing Mengel
72 1 Marc testing Mengel
73 1 Marc testing Mengel
h2. Advice on level of detail
74 1 Marc testing Mengel
75 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.
76 1 Marc testing Mengel
77 1 Marc testing Mengel
The following are some primary uses of the log:
78 1 Marc testing Mengel
* Any collaborator might follow the summary to see how DES data collection is going.
79 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.
80 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.
81 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. 
82 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. 
83 1 Marc testing Mengel
84 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.
85 1 Marc testing Mengel
86 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.
87 1 Marc testing Mengel
88 1 Marc testing Mengel
h2. Questions asked (if not frequently, at least once)
89 1 Marc testing Mengel
90 1 Marc testing Mengel
h3. What is the difference between category and tags? 
91 1 Marc testing Mengel
92 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.
93 1 Marc testing Mengel
94 1 Marc testing Mengel
h3. What is the difference between problems and engineering?
95 1 Marc testing Mengel
96 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. 
97 1 Marc testing Mengel
98 1 Marc testing Mengel
A problem is an unexpected occurrence that prevents you from following your plan.
99 1 Marc testing Mengel
100 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.
101 1 Marc testing Mengel
102 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.
103 1 Marc testing Mengel
104 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.
105 1 Marc testing Mengel
106 1 Marc testing Mengel
If this is too confusing, perhaps we should merge the sections.
107 1 Marc testing Mengel
108 1 Marc testing Mengel
h2. Known issues
109 1 Marc testing Mengel
110 6 Stephen Kent
h3. Formatting of plain text entries comes out corrupted.
111 1 Marc testing Mengel
112 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.
113 1 Marc testing Mengel
114 2 Marc testing Mengel
h3. Nightsum sometimes fails when comments have special characters in them (particularly "#" and "&amp;")
115 1 Marc testing Mengel
116 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.
117 1 Marc testing Mengel
118 2 Marc testing Mengel
h3. Observers currently must run the tool from the "sispi" account
119 1 Marc testing Mengel
120 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.
121 1 Marc testing Mengel
122 1 Marc testing Mengel
h3. Documentation and procedures need expansion
123 1 Marc testing Mengel
124 1 Marc testing Mengel
h2. Planned feature enhancements
125 1 Marc testing Mengel
126 1 Marc testing Mengel
* The sectioning and formatting should better worked out.
127 1 Marc testing Mengel
* The TASCA all-sky movie should be included in the summary.
128 1 Marc testing Mengel
* The thumbnail images should be copied into the nightsum directory and thence to the webserver, so they can be seen form outside the observatory.
129 1 Marc testing Mengel
* Links to data files (of conveniently machine-readable format, such a tsv, json, or xml) should be included in the summary.
130 2 Marc testing Mengel
* The "live" draft of the nightsum should be started by the Architect as part of SISPI startup, and perhaps some screen space found for it.
131 2 Marc testing Mengel
* The "live" draft of the nightsum should have a "publish" button, which copies the summary to the appropriate web server (at Fermilab or, eventually, NCSA).
132 2 Marc testing Mengel
* The "comments" from the electronic logbook (or at least links to the comments) should be part of the summary.
133 1 Marc testing Mengel
* Automatically generated plots of exposure pointings on the survey footprint should be part of the summary.
134 1 Marc testing Mengel
* Automatically generated seeing statistics should be part of the summary.
135 1 Marc testing Mengel
* Automatically generated cloud statistics should be part of the summary.
136 1 Marc testing Mengel
* Automatically generated open-shutter-time, slew time, night duration, and other efficiency measures should be part of the summary.
137 1 Marc testing Mengel
* Automatically generated links (and/or summaries) connecting exposures to relavant weather information (DIMM, RASICAM, wind, etc.) should be added to the summary.
138 1 Marc testing Mengel
* The summary should be better integrated with Data Mangement's Quality Assessment tools.
139 1 Marc testing Mengel