Welcome to Philadelphia’s documentation!

Philadelphia is a shift report system designed for the SNO+ neutrino experiment. It is inspired by Manhattan, the shift report system used for the SNO (Sudbury Neutrino Observatory) experiment, but makes several improvements.

The Philadelphia software itself contains nothing SNO+-specific, and so is easily portable to other sites.

Requirements: Philadelphia requires JavaScript to be enabled in your browser. Internet Explorer is not supported.

Source code: Philadelphia is free software. Source is available on github.

Bug reports: Please report any bugs through the Issue Tracker.

Motivation

The major strength and weakness of Manhattan was the flexibility of its input. The shift report was built by pasting templates into a large text box and filling in or modifying as needed. This is good, because it allows the shift operator to enter any relevant data in any format. It is bad, because this data is extremely difficult to query, plot, etc.

Philadelphia’s interface aims to preserve the flexibility of Manhattan while introducing just enough structure to make queries possible. As in Manhattan, the report is composed by instantiating templates. Philadelphia’s templates consist of form fields, but they can be removed and new ones can be added as the user sees fit. Additionally, free text-entry template gives the user a canvas to enter large amounts of uncategorized data, as was possible in Manhattan.

All fields in Philadelphia are queryable and plottable, even those added by users.

User’s Guide

The Index Page

_images/index.png

The index page provides a list of all past shift reports. By default, it is sorted by date (newest first), but clicking on the column headers allows sorting by anything.

Clicking on a report ID will take you to that shift report.

There are two buttons in the upper right of the report list: “Make a Plot” and “New.” Clicking “New” takes you to the report composition page.

The Report View Page

_images/view.png

The report view page shows the contents of a shift report.

The Report Composition Page

_images/compose.png

Composing a Report

To compose a report, click and drag templates from the right into the report area (“Drag templates here...”). Once dropped, the templates can be re-arranged by dragging and dropping.

_images/compose_drag_drop.png

Fields marked as required by the shift report administrator appear with a red background when empty and cannot be removed.

Removing Fields

To remove a field or attachment, click the X to the left of the field name.

Adding New Fields

To add a new field, click “Add” at the bottom of the list of fields. Enter a field name and a value, then click “Add” or press Enter.

_images/add_field.png

Adding Attachments

To attach a file to your shift report, click “Attach” at the bottom of the list of fields. Choose a file, then click “Upload.”

Saving

The report is automatically saved after every change and when you leave the page. You may also save at any time by clicking the “Save” button in the upper right corner of the report area.

Collaborative Editing

Shift reports can be edited by multiple users simultaneously. However, due to network latency editing the same block from multiple locations can lead to “choppy” behavior. Currently, newly-added blocks will not appear in others’ browsers until the page is reloaded.

The report view page also updates in real time if the report is being edited.

Removing a Block

To remove a block from your report, click the trash can icon in the upper right corner of the block. Note that this operation is irreversible.

Remote Assistance

If you need help with a shift report, ask an expert. Send them the link at the top of the page, and they can see your report in real time as you modify it.

_images/compose_link.png

The Plotting Page

_images/plot.png

Philadelphia includes a built-in interface for plotting the data stored in shift reports. Currently, it supports scatter plots, time series, and histograms of numerical fields. All fields are plottable, including any added by users. Since field names are arbitary, all fields for entry of a series name autocomplete with valid field names.

Scatter Plots

Enter an X series (e.g. “Run number”) and a Y series (e.g. “Temperature”) to create a scatter plot.

_images/scatter.png

Time Series

Enter a series name (e.g. “Temperature”) to plot the history of that value over time.

_images/time_series.png

Histograms

Enter a series name (e.g. “Temperature”) and the desired number of bins to create a histogram.

_images/histo.png

Administrator’s Guide

Installation

Philadelphia is a lightweight CouchDB application developed in the egret framework. egret is a pure Python couch app development tool, and is included with Philadelphia for convenience.

Requirements

Installing

Clone the Philadelphia repository from github:

$ git clone git://github.com/mastbaum/philadelphia.git

If you wish, customize application settings in settings.json and templates in templates.json.

Then, from within the philadelphia directory, run:

$ ./egret push http://your-server:port/database_name
$ ./egret pushdata http://your-server:port/database_name templates.json

Your Philadelphia installation should now be live at http://your-server:port/database_name/_design/designname/index.html, where designname is that in settings.json (default: phila).

Search Functionality

The search feature of Philadelphia relies on couchdb-lucene, an external Java indexer.

To set up lucene:

  1. Follow the instructions in the couchdb-lucene readme

    1. Download or git clone the couchdb-lucene source
    2. Build with mvn. This will create a tarball in target/
    3. Untar the tarball where the lucene server binary should live

  2. If you are using CouchDB’s HTTP authentication (i.e. you set require_valid_user=true in your CouchDB configuration), change the last lines of config/couchdb-lucene.ini to something like:

    [local]
url = http://USERNAME:PASSWORD@localhost:5984

  3. Start the lucene server with /PATH/TO/LUCENE/bin/run. For production, this should be run as a daemon.

  4. Add the following to the [httpd_global_handlers] section in CouchDB’s local.ini and restart the CouchDB server:

    _fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}

  5. Push the lucene indexing design document to the Philadelphia database:

    $ egret pushdata http://localhost:5984/phila /PATH/TO/PHILA/lucene/lucene.json

Nice URLs

URLs can easily be rewritten to be more user-friendly. For example, in Apache:

ProxyRequests Off
<Proxy *>
       Order Allow,Deny
       Allow from all
</Proxy>

 RewriteEngine On
 RewriteOptions Inherit

 RewriteRule ^/_fti/(.+)$ http://127.0.0.1:5984/_fti/$1 [QSA,P]
 RewriteRule ^/_uuids(.*) http://127.0.0.1:5984/_uuids [QSA,P]
 RewriteRule ^/_utils/script/(.*) http://127.0.0.1:5984/_utils/script/$1 [QSA,P]

 RewriteRule ^/philadelphia$ /philadelphia/ [R]
 RewriteRule ^/philadelphia/$ http://[INSERT YOUR FQDN]/philadelphia/index.html?user=%{LA-U:REMOTE_USER} [QSA,P]

 RewriteRule ^/philadelphia/(.+)$ http://127.0.0.1:5984/phila/_design/phila/$1?user=%{LA-U:REMOTE_USER} [QSA,P]

 RewriteRule ^/phila/(.+)$ http://127.0.0.1:5984/phila/$1?user=%{LA-U:REMOTE_USER} [QSA,P]
 RewriteRule ^/phila/_changes(.+)$ http://127.0.0.1:5984/phila/_changes/$1?user=%{LA-U:REMOTE_USER} [QSA,P]
 RewriteRule ^/phila/(.*) http://127.0.0.1:5984/phila?user=%{LA-U:REMOTE_USER} [QSA,P]

This will put everything at http://server/philadelphia.

There are only a few parameters that get passed around and it all happens via the query string, so even prettier URLs with no .html are possible too. Specifically, if edit.html receives an id it will open the report for editing (without an id it starts a new report), and results.html expects a search query q=key:value.

Report Templates

Although users may add and remove fields as they wish, all “standard” fields should be defined in a template. These are the fields the user sees when they first drop a template into their report.

Templates are defined in JSON in templates.json, in the root directory of your Philadelphia installation, with the following structure:

[
    {
        "_id": "template_name",
        "type": "template",
        "default": boolean,
        "fields": [
            {
                "name": "field 1 name",
                "type": "field 1 type",
                "attrib": "field 1 attributes",
                "required": boolean
            },
            {
                "name": "field 2 name",
                "type": "field 2 type",
                "attrib": "field 2 attributes",
                "required": boolean
            }
        ]
    }
]

After modifying templates.json, you must push the changes to the server with ./egret pushdata as shown in the installation guide.

Field Types

The value of “type” must be an HTML form input type. Currently, Philadelphia supports text, textarea, and checkbox.

Field Attributes

Attributes are optional, and any provided will be passed along directly to the HTML input element. This is useful, for example, in fixing the size of a textarea:

{
    "name": "terminal contents",
    "type": "textarea",
    "attrib": "rows=80 cols=25"
}

Default Templates

If a template has the optional key “default” set to true, an instance of the template is automatically placed at the top of new shift reports.

Required Fields

Fields with the optional key “required” set to true cannot be deleted from the template. They also appear red if null.

Indices and tables