Introduction
Long View is a utility written in Python for generating timelines from CSV-formatted data. It's part of the Long Server project.
Requirements
- Python 2.3 or Higher
- Python GD module
Installation
Installing the GD Python Module
Ubuntu/Debian and other users of the apt-get system can install the GD Python Module with sudo apt-get install python-gd (Tested on Ubuntu 10.04 LTS (lucid)). Several dependencies will be installed along with it.
Installing Long View
Long View is packaged with the standard python Distutils. This means that the simplest way to install it is with the following command:
python setup.py install
Alternatively, you can run ./longviews.py directly from this directory.
How to use
The simplest thing to do is copy one of the examples. Find the "examples" directory in your install. If you did the simple installation, chances are good that this will be either /usr/longview/examples or /usr/share/longview/examples. Copy the biotech-* files somewhere where you can easily edit and modify them. You'll probably want to rename them to something more appropriate for your purpose.
Running the script
Execute
longview.py parameter-file-name
from a command-line prompt to generate the HTML for your timeline into
a subdirectory of the current directory named html. See the output
of
longview.py
for a listing of options that are supported.
Parameter File
The first thing to edit is the params file in a spreadsheet. Make
sure the TIMELINE.datafile and TIMELINE.templatefile parameters point
to the new names, if you've changed them.
In Long View, dates (and durations, unless otherwise noted) are
generally written as YYYYY/MM. However, for ease of data entry, they
can be abbreviated: leading 0s can be dropped, and it is not necessary
to specify the month (January is assumed). So the dates "01940/01"
and "1940" are considered equivalent. To specify a year before the
year 0, append "BCE" or "BC", as in "8000BCE".
Most parameters present in the examples are required.
Parameters
Many of the parameters are fairly self-explanatory, but some are not quite so obvious. Some notes:
All sizes (eg margins, widths, heights) are specified in pixels.
A color is specified as 3 hexadecimal numbers representing its red, green, and blue components.
TIMELINE.nowdate: if you specify this parameter (rather than letting
the script calculate the nowdate based on the current system clock),
it MUST be the first parameter specified in the file.
TIMELINE.5digityears: Set this to True if years in the HTML should
be zero-padded so that they are always five digits long.
TIMELINE.section: The set of section parameters describes all the
sections of the timeline. One section is needed for each chunk of
time that has a different number of years per horizontal interval of
TIMELINE.intervalsize pixels. This allows long spans of time where
not much happens to appear condensed down to a visually palatable
size. The three parameters for this are start-date, end-date, and
interval. Interval is the number of years per intervalsize pixels.
The end-date is normally given as a date, but, in the case of the
end-date of the last section on the graph, may also be specified as
the string "Ongoing". This indicates that the graph should end two
intervals past the now date.
The parameters with "diamond" in the name refer to the diamond that is drawn in an eventbar to represent a subitem.
TIMELINE.navcell: The set of navcell parameters define the pieces of
the navigation bar displayed above the timeline. Each cell takes
three parameters: the first is the name of the year in the timeline
that it should jump the viewer to. The second is whether it should
jump the viewer to the top or the bottom of the page. And the third
is for only the navcell that represents the chunk of time where
TIMELINE.nowdate is being rendered, as it is visually slightly
different from the other cells. Note that if no navcells are specified,
the script will generate them automatically.
TIMELINE.resolutioninmonths tells how much time a specific date is
intended to represent. Values usually will be either "1" for a month,
or "12" for a year. Note that this parameter does NOT apply to
notifications and interest data, both of which are always assumed to
have a resolution of 1 month.
TIMELINE.labelresolution can be either "months" or "years". It
dictates whether date labels on the timline are written as
"year/month" or just "year".
TIMELINE.staticimage allows extra images (such as might be used by
template HTML or CSS) to be placed in the generated tree. The first
parameter is the original filename, and the second is the name that
the file should have in the img-static sub-directory of the generated
tree.
Template File
The template file is actually a file containing Python code. The only two things that MUST be specified in the template file are the popupTemplate variable (which contains the templated HTML for the popup), and the stylesheets variable (which contains all the stylesheets used by the page). Most fonts and colors used in the HTML can be set by editing the stylesheets. Additionally, any of the variables or functions that are present in lvhtml.py can be overridden simply by supplying a new value or define here.
The popupTemplate can contain a number of "escape sequences" that have special meaning to the code that generates the HTML:
%n is the nodeId of a particular item. This must be used at least once in each popup to generate an HTML node with an id attribute so that the specific popup can be referenced from JavaScript.
%t is the title of the popup.
%d is a string representing the date or dates that this item covers.
The rest of the arguments (%1 through %9) are simply extra arguments that will be supplied for each item in the datafile, allowing for the HTML to be arbitrarily customized.
The notifyTemplate is used for popups over the diamonds used to display notifications. It can be customized in the same way that the popupTemplate can.
Data File
Like the parameter file, this file will typically be created or edited using a spreadsheet. Each line in the data file represents a single eventbar item or subitem.
The fields for an item are, in order:
item-number, start-date, end-date, clickthrough-link, title, template-argument, [...]
Note that the string "?" can be used as an end-date, and will cause the event bar to end at the "now date", and will render in popups as "?".
If the item-number is blank, this line is assumed to contain a subitem of the most recently specified item. Eventbar subitems are specific events that happen during (and as part of) a particular eventbar item. They are drawn as diamonds inside the eventbar of their parent item (which is assumed to be the most recently specified item). Their fields are, in order:
(empty), date, clickthrough-link, template-argument, [...]
The first template argument given as part of any item or sub-itemline is assigned the escape sequence %1. The next: %2, and so forth. Each template argument is substituted into the popup HTML template in place of the appropriate escape sequence.
Notifications File
Long View can optionally provide notifications about specific events. By providing several NOTIFY parameters in the param file (see the biotech example for the exact parameters), you can cause Long View to read through a data file each time it runs, and send out a notification for each line in the file that matches the current date.
Note that the data file itself and the directory the data file lives
in must be writable by the user running the longview.py script. The
script re-writes the file each time it runs to keep track of which
notifications have already been sent, so they don't get sent out
multiple times (since the date resolution for notification in Long
View is a month).
The notifications data file is a CSV file. Each line in the file has up to five fields. They are, in order:
item-id, date, email-addrs-to-notify, notification-text[, status]
item-id is the ID of the item in the timeline data file that this notification corresponds to ("None" is a valid value). Notifications will be displayed as diamonds with popups in the timeline bar of the corresponding item.
email-addrs-to-notify is a double-quoted, comma-separated list
notification text is sent in the body of the notification email
status begins with one of "Sent", "Unsent", or "Retrying". If an attempt to send a notification fails, a warning is printed to stdout, and "Retrying will be written to the status field so that the script tries again on the next run. If status is not specified, "Unsent" is assumed.
The notification classes can be overridden or inherited from by using
the NOTIFY.hookfile parameter to execute the given file in the lvnotify
module namespace. NOTIFY.notifierclass and NOTIFY.notificationclass
can be used to override those things.
Interest File
By providing TIMELINE.interestfile, EVENTBAR.nocolor,
EVENTBAR.yescolor, and EVENTBAR.saturation parameters in the parameter
file, Long View can be made to generate discussion data for Long Bets
timelines in visual form. It colors slices of the eventbar such that
height of the bottom part of each slice represents the number of NO
votes, the height of the top part represents the number of YES votes,
and the darkness of the entire slice represents the intensity of
discussion. The interest file is a CSV file. Each line represents a
single month's worth of discussion and votes, using the following fields:
item-Id, date, yes-vote-count, no-vote-count, discussion-post-count
The itemId assigns a given line to a specific event bar on the timeline.
The date is expected to be in year/month format and represents a single month.
The rest of the fields should be fairly self-explanatory.
Other Hooks
If you need to override one or more functions in longview.py, simply
specify a TIMELINE.hookfile in the param file. This is simply a
python file that will be read in near the beginning of execution, and
any symbols will override those with the same name in longview.py.
Licensing
These files can be redistributed and/or modified under a BSD-style license
(included in the accompanying LICENSE file).
Questions/Feedback
Questions and/or feedback should be posted on GitHub.