Introduction to the nightsum » History » Version 5
Eric Neilsen, 09/04/2013 01:34 PM
|1||1||Marc testing Mengel||
h1. Introduction to the nightsum
|2||1||Marc testing Mengel|
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||2||Marc testing Mengel||
* *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.
|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||1||Marc testing Mengel||
This currently requires having a FNAL kerberos account and permissions to log into decam03 as codemanager. This process is not automated yet, but the steps are simple:
|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 @
@ $ makesum @
|35||1||Marc testing Mengel|
* The step above will create a dir named nightsum-<YYYY>-<MM>-<DD>. Check the results by pointong your browser to
@ 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 @
Alternately, @makesum@ can open the newly generate summary automatically using the @-o@ option:
@ $ 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||1||Marc testing Mengel||
h2. Monitoring a draft of the night summary
|52||1||Marc testing Mengel|
|53||1||Marc testing Mengel||
A web server can be started that shows a current draft of the night summary, as follows:
|54||1||Marc testing Mengel|
|55||1||Marc testing Mengel||
* log into observer2 as user DECamObserver
|56||1||Marc testing Mengel|
|57||1||Marc testing Mengel||
* set up the environment:
|58||1||Marc testing Mengel||
@ $ setup nightsum @
|59||1||Marc testing Mengel|
|60||1||Marc testing Mengel||
* start the server:
|61||1||Marc testing Mengel||
@ $ NightSummarizer ~DECamObserver/nightsum-config @
|62||1||Marc testing Mengel|
The draft will appear (slowly) in [[http://observer2.ctio.noao.edu:8899/nightsum]]
|64||1||Marc testing Mengel|
|65||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 @
|66||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.
|67||1||Marc testing Mengel|
|68||1||Marc testing Mengel|
|69||1||Marc testing Mengel||
h2. Advice on level of detail
|70||1||Marc testing Mengel|
|71||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.
|72||1||Marc testing Mengel|
|73||1||Marc testing Mengel||
The following are some primary uses of the log:
|74||1||Marc testing Mengel||
* Any collaborator might follow the summary to see how DES data collection is going.
|75||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.
|76||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.
|77||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.
|78||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.
|79||1||Marc testing Mengel|
|80||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.
|81||1||Marc testing Mengel|
|82||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.
|83||1||Marc testing Mengel|
|84||1||Marc testing Mengel||
h2. Questions asked (if not frequently, at least once)
|85||1||Marc testing Mengel|
|86||1||Marc testing Mengel||
h3. What is the difference between category and tags?
|87||1||Marc testing Mengel|
|88||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.
|89||1||Marc testing Mengel|
|90||1||Marc testing Mengel||
h3. What is the difference between problems and engineering?
|91||1||Marc testing Mengel|
|92||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.
|93||1||Marc testing Mengel|
|94||1||Marc testing Mengel||
A problem is an unexpected occurrence that prevents you from following your plan.
|95||1||Marc testing Mengel|
|96||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.
|97||1||Marc testing Mengel|
|98||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.
|99||1||Marc testing Mengel|
|100||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.
|101||1||Marc testing Mengel|
|102||1||Marc testing Mengel||
If this is too confusing, perhaps we should merge the sections.
|103||1||Marc testing Mengel|
|104||1||Marc testing Mengel||
h2. Known issues
|105||1||Marc testing Mengel|
|106||1||Marc testing Mengel||
h3. Formatting of plain text entires comes out corrupted.
|107||1||Marc testing Mengel|
|108||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.
|109||1||Marc testing Mengel|
|110||2||Marc testing Mengel||
h3. Nightsum sometimes fails when comments have special characters in them (particularly "#" and "&")
|111||1||Marc testing Mengel|
|112||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.
|113||1||Marc testing Mengel|
|114||2||Marc testing Mengel||
h3. Observers currently must run the tool from the "sispi" account
|115||1||Marc testing Mengel|
|116||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.
|117||1||Marc testing Mengel|
|118||1||Marc testing Mengel||
h3. Documentation and procedures need expansion
|119||1||Marc testing Mengel|
|120||1||Marc testing Mengel||
h2. Planned feature enhancements
|121||1||Marc testing Mengel|
|122||1||Marc testing Mengel||
* The sectioning and formatting should better worked out.
|123||1||Marc testing Mengel||
* The TASCA all-sky movie should be included in the summary.
|124||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.
|125||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.
|126||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.
|127||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).
|128||2||Marc testing Mengel||
* The "comments" from the electronic logbook (or at least links to the comments) should be part of the summary.
|129||1||Marc testing Mengel||
* Automatically generated plots of exposure pointings on the survey footprint should be part of the summary.
|130||1||Marc testing Mengel||
* Automatically generated seeing statistics should be part of the summary.
|131||1||Marc testing Mengel||
* Automatically generated cloud statistics should be part of the summary.
|132||1||Marc testing Mengel||
* Automatically generated open-shutter-time, slew time, night duration, and other efficiency measures should be part of the summary.
|133||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.
|134||1||Marc testing Mengel||
* The summary should be better integrated with Data Mangement's Quality Assessment tools.
|135||1||Marc testing Mengel|