Valid XHTML 1.0 Transitional


The following page contains a number of example VHIST documents. Click on the links below the images to download and open the VHIST files. We changed the extensions of the files to .pdf, so that your web browser or file manager will open the files with your PDF viewer. We took screenshots with the Adobe Reader on Linux.

The examples also show the commandline calls (we assume a Bash Shell), that were used to create the VHIST file(s). Some examples require demo data or special software. Therefore you can not simply rerun all of the examples on your local machine. You will, however, get a good idea what was necessary to create the VHIST files on this page.

Example 1: Hello World

You can create the most basic VHIST file with the command:

$ vhistadd -O example1.vhist


Figure 1: On the left: The first page of every VHIST file contains a description of VHIST. You can adjust the contents of this page to your likings and add information about your institute or project. On the right: A VHIST workflow step, which contains a minimum of documentation.

Download example1.vhist here.

Example 2: A More Complex VHIST File

Such a minimal VHIST file does not contain a lot of useful information. We can add information manually:

# copy a file to another location
$ cp input.txt output.txt

# document this operation with VHIST
$ vhistadd -O output.txt.vhist -s title "Copying a File" -s command "cp input.txt output.txt"
  -i input.txt -o output.txt


Figure 2: A VHIST workflow step, which contains manually added information about a processing step. The paperclip icons show that the files have been embedded. You can extract those files by right-clicking on the paperclip in your PDF browser.

Download example2.vhist here.

Example 3: Automatic VHIST files with vhistify

Adding information to a VHIST file manually is cumbersome and error prone. Our tool vhistify can gather and add this information automatically. It will also collect a lot more information:

# do something and create a VHIST file at the same time
$ vhistify --title "Copying a File" cp input.txt output.txt


Figure 3: A VHIST workflow step generated by vhistify. The VHIST file contains a lot of information, that has been gathered automatically.

Download example3.vhist here.

Example 4: Multiple processing steps

In many cases, a workflow will not contain only one processing step, but several. We can translate this property to VHIST quite easily:

# first step
$ vhistify --title "Copying a File" cp input.txt intermediate.txt
# second step
$ vhistify --title "Copying a File a Second Time" cp intermediate.txt output.txt


Figure 4: A VHIST file with two sections, one for each workflow step. vhistify stores VHIST files for every generated file and extends suitable input files automatically.

Download example4.vhist here.

Example 5: Documenting Python with vhistify

Documenting the copy tool of Unix is not very exciting. This example will show how to document a simple Python script

# document a python script
$ vhistify --title "Convert File To Upper Case" --plugins=python python myfile1.txt


Figure 5: A VHIST file for a simple Python job. Vhistify automatically detects the Python sourcecode and embeds it as a .zip archive.

Download example5.vhist here.

Example 6: More Complex Python Workflow

When a workflow step uses several input files and each file is associated with a VHIST file, vhistify will extend one of the files and embed the other one. This way, the complete history of all files is preserved.

$ vhistify --title "Convert File To Upper Case" --plugins=python python myfile1.txt
$ vhistify --title "Convert File To Upper Case" --plugins=python python myfile2.txt
$ vhistify --title "Concatenate Several Files" --plugins=python
  python myfile1-uppercase.txt myfile2-uppercase.txt output.txt


Figure 6a: A VHIST file for a more complex workflow of Python scripts. The second workflow step contains the VHIST file myfile2-uppercase.txt.vhist as an embedded file.


Figure 6b: A diagram of the workflow from example 6. The diagram was automatically generated from the VHIST file.

Download example6.vhist here.

Example 7: Preview Images

You can also embed preview images into a VHIST file.

$ export VHISTIFY_PLUGINS=matlab,previews
$ export VHISTIFY_TITLE="Create a Sinus/Cosinus Plot"
$ vhistify --no-stdin matlab_2011b -nodesktop -r createPlot


Figure 7: A VHIST file with an embedded preview image. Preview images are shown on their own page(s).

Download example7.vhist here.

Example 8: FSL Workflow

FSL (FMRIB Software Library) is a library of tools for medical imaging purposes. You can easily document processing steps, that involve FSL tools with VHIST:

# set the vhistify plugins globally

# don't embed NIfTI files
$ export VHISTIFY_DONT_EMBED_PATTERNS='*.nii.gz,*.nii'

# 1) initialize FSL
$ source

# 2) extract brain from MRI
$ vhistify --title="Extract Brain" bet pat_mmm_mri.nii.gz
  pat_mmm_mri-stripped.nii.gz -m -v

# 3) coregister MRI onto PET and store the transformation
$ vhistify --title="Coregister Images" flirt -in pat_mmm_mri-stripped.nii.gz
  -ref pat_mmm_fmz.nii.gz -omat "mr->pet.mat" -v

# 4) segment MRI into grey matter, white matter, csf
$ vhistify --title="Segment Brain" fast -v pat_mmm_mri-stripped.nii.gz

# 5) transform segmentation onto PET image
$ vhistify --title="Apply Transformation" flirt -in pat_mmm_mri-stripped_seg.nii.gz
  -ref pat_mmm_fmz.nii.gz -applyxfm -init "mr->pet.mat" -out segmented_pet.nii.gz
  -v -interp nearestneighbour


Figure 8a: The pages of the generated VHIST document. Other VHIST files that document branches in the workflow are embedded inside the VHIST document.


Figure 8b: A diagram of the workflow from example 8. The diagram was automatically generated from the VHIST file.

Download example8.vhist here.

Example 9: User-defined Attributes

VHIST allows you to add user-defined key-value pairs to a VHIST section. You can use these attributes to store any kind of additional information (temperature, algorithm used, number of iterations, patient id, time of measurement) in a VHIST file.

# add user defined attributes with or without unit
$ vhistadd -O example9a.vhist -U numIterations 124 -W size "[256, 512]" pixels


Figure 9a: You can use VHIST's user-defined attributes to store any kind of key-value pairs in a VHIST file.

Download example9a.vhist here.

# add user defined attributes via vhistify
$ vhistify --plugins=stdoutattrs echo "VHISTIFY: size[voxels]=[64, 64, 48]"


Figure 9b: You can also specifiy user-defined attributes for your own programs if you create the VHIST documentation with vhistify.

Download example9b.vhist here.