Hastie

A tool to extend Jekyll for use in report creation.

Assuming you have hastie installed, what are the steps to start using it? These steps also assume you have a compatible jekyll installed as well as a jekyll blog framework, such as bioreports. See below for more info on jekyll and bioreports.

First, setup your .hastie config file to point to your bioreports path

hastie config /path/to/bioreports/source -a jfv -t textile

This creates a .hastie file in your home directory. The -a flag indicates the analyst (your username) to set. The -t flag tells hastie to generate textile documents for your reports.

Now you are ready to generate a new report. Navigate to your base project directory, and create it with hastie create:

cd /path/to/report/base
hastie create -i cbio_101 -r ada -p hym

This will create a new directory called cbio_101 with a series of directories inside it. The flags set meta data about the report. -r for the researcher this report is for and -p for the PI or lead researcher of the researcher specified by -r.

The Project directory, cbio_101 will now contain these sub-directories:

 --cbio_101
  |
  |__ report
  |
  |__ data
  |   |
  |   |__ input
  |   |
  |   |__ output
  |
  |__ code
  |
  |__ notes

Inside your report directory will be a number of files and sub-directories to get your report started. Many of these files are copied directly from the server you supplied in your config file.

You can generate just the report directory by using the --only-report flag.

Now start editing your report. It will be inside your report directory, and be named date_report_name.textile. Watch changes to your report as you modify this file using hastie watch:

cd report
vim 2011-02-04_analysis_of_sample_x.textile
hastie watch

Hastie watch really just starts jekyll and builds your report locally. But this helps so that you don’t have to remember any new commands.

Now you have some info in your report, and you would like to publish it to the main server. That’s where hastie publish comes in:

# ctrl-c to kill hastie watch
hastie publish

This will copy your important files to the server in your .hastie file and then run jekyll there. It will also check in this change to your server’s git repository.

And that’s all there is to creating a new report! create, watch, and publish.

Users may get an error in read_yaml about an invalid byte sequence. To fix this, modify your .bashrc to include:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

This is documented in a jekyll issue

Hastie works with Jekyll to create a powerful and flexible system by which reports can be created by different individuals and uploaded to a central ‘server’.

Say you work in an office that generates data, and reports about that data, for clients (so, for example, a core Bioinformatics facility providing results to various research labs).

The reports you generate typically come as a mix of Word documents, Excel spreadsheets, and external data files. Everyone in your office creates these reports differently. They are stored in various locations, in various folders on networked drives. They have different levels of information, and generally are a hassle to create and update.

Consumers of these reports (i.e. the researchers you generated them for) have to navigate confusing and disparate network paths to find these reports. They have to have Word, Excel, and whatever other programs you have (and the right versions of these programs) installed on the computer they are using, and have to have them all open at the same time to see their report and data.

In short, there is a high cost for both encoding and decoding this information. Its a lose lose situation.

Hastie is a component of a small suite of tools to facilitate faster encoding and decoding of this data. Attempting to lower the requirements of producing and consuming reports – so producers (analysts) can generate bigger, better, reports faster and more consistent with their co-workers, and consumers (researchers) can get to their data with less hand-holding and fewer hoops to jump through.

Hastie serves as a simple interface between the creators of the reports and the report system itself. It takes care of all the back-end silliness, and lets you create and publish reports quickly and easily.

Hastie is a command-line tool that communicates with the report server (really just a jekyll source directory). It creates a framework for building up a report, allows you to develop this report locally, with whatever tools you are most comfortable with, and then easily publish this report so that it can be shared with others.

Hastie is one piece of the puzzle for better, faster, more consistent reports. You also need:

• Jekyll – a static site generator that has lots of power behind it to allow customization galore. Jekyll is built for blogs – but with Hastie’s help, it makes a mighty fine report system as well.
  • Hastie requires a custom build of Jekyll that includes some missing features to be fully functional.
  • Hopefully in the future, these features will be integrated back into Jekyll proper.
• A Jekyll site framework. Jekyll allows for plugins and layouts and other components. Hastie also expects some additional files present in its ‘Jekyll Sever’ to work.
  • Check out bioreports for an example of such a site framework.

Usage: hastie [COMMAND] <OPTIONS>

Hastie Commands:
  version - Print version number and exit
  help    - Print this help and exit
  create  - Create new report directory framework with given name
  watch   - Monitor current directory for changes.
            Updates local copy of report
  publish - Send report to server. Update published reports
  update  - Update local report directory with changes from report server
  config  - Create new hastie config file for communicating with server
  create_server - Create new server directory framework with given name

create options:
  Use 'hastie create -h' for more information on start options

publish options:
  Use 'hastie publish -h' for more information on publish options

update options:
  Use 'hastie update -h' for more information on publish options

config options:
  Use 'hastie config -h' for more information on publish options

create_server options:
  Use 'hastie create_server -h' for more information on publish options

In Strange Case of Dr. Jekyll and Mr. Hyde, Dr. Hastie Lanyon finds Jekyll’s ideas too fanciful.