vhistadd

-O <filename> [-O <filename>] [-O <filename>] …

The name of the VHIST file which will be generated during this workflow step. If more than one file is specified, several VHIST files with identical content will be generated. At least one -O (capital letter "O") option must be specified.

By design, vhistadd prevents you form overwriting existing VHIST files except (a) when an output VHIST file is also specified as a VHIST root file or (b) you choose the Append to VHIST file option.

-A <filename>

If the file exists, the current workflow step will be appended to the file, preserving all previous content. If it does not exits, a new VHIST file of that name will be created.

-I <filename> (file must exist)
-J <filename> (ignore if file cannot be read)

The name of the VHIST file, which is used as the basis for the new VHIST file. The generated workflow step is appended to a copy of this VHIST document. The VHIST root file is not modified except if the root file is also specified as an output VHIST file. If this option is not specified, vhistadd starts with an empty document. The -I option will cause vhistadd to stop with an error message if the VHIST root file cannot be read, use -J if vhistadd should ignore a missing root file (we have introduced -A, see previous subsection, to achieve the same effect without having to specify an output VHIST file with -O).

-s <key> <value>

We distinguish between User-defined attributes (workflow step) and pre-defined properties or attributes of a workflow step. This option is used to set one or more of the following pre-defined attributes (it is an error to use other keywords with this option):

Attribute	Brief Description
title	The title of the workflowstep.
description	A short description of the workflowstep. Longer descriptions can be embedded as input files.
comment	Additional comments referring to this workflowstep.
tool	A version string of the tool used in the workflowstep.
toolversion	An alias for tool.
toolpath	The path to the executable of the tool.
host	The name of the host, on which the workflowstep was performed.
user	The name of the user, who performed the workflowstep.
command	The commandline used to exectue the workflowstep.

-U <key> <value>
to set a user-defined attribute.

We distinguish between user-defined and Pre-defined attributes (workflow step).

-U "my key" "my value"

creates the user-defined attribute

my key

and sets it to

my value.

-W <key> <value> <unit>
to set a user-defined attribute with an associated unit.

We distinguish between user-defined and Pre-defined attributes (workflow step).

-W "my key" "my value" "my unit"

creates the user-defined attribute

my key

and sets it to

my value. The value of the attribute has the unit my unit.

-d <key> <value> or
-doc <key> value>
 
Valid keys are: producer, creator, author, keywords, title, subject

These properties are important when viewing VHIST files using a PDF browser. We refer to [3] for a detailed description.

These properties can currently only be set for newly created VHIST files. When appending a workflowstep to an existing VHIST file, an attempt to set PDF-related properties is ignored.

-i <filename> or
–infile <filename>
specifies one or more input files.

The VHIST format distinguishes between the files present before the workflow step (infiles) and files which result from executing the specified tool (outfiles).

After -i <filename>, but before the next -i option, a number of addition options refering to this file can be added. See Pre-defined flags (files) Pre-defined attributes (files), User-defined attributes (files) for further options.

-o <filename> or
–outfile <filename>
to specify one or more output files.

The VHIST format distinguishes between files present before the workflow step (infiles) and files which result from executing the specified tool (outfiles).

After -i <filename>, but before the next -i option, a number of addition options refering to this file can be added. See Pre-defined flags (files) Pre-defined attributes (files), User-defined attributes (files) for further options.

-f <key>
sets one or more pre-defined flags.
It is an error to use other flagnames than the ones defined below with
this option.

A flag enabling or disabling a property of the previously specified in- or outfile. The flags can be negated by prepending the flag's name with no-, e.g. no-embed.

Flag	Brief description
automd5	The MD5 sum [4] of the file's content is automatically calculated by vhistadd. If the file is embedded, this option is forced. By default, this option is enabled.
embed	The file's content is embedded into the generated VHIST file. By default, this option is enabled.
compress	The file is compressed using the flate compression method [5]. If the file's content is not embedded, this flag is ignored. By default, this option is enabled.
optional	The file is optional and only included in the VHIST file if it is readable, otherwise it is silently ignored. By default, this flag is not set, i.e. if vhistadd needs to access the file to compute the MD5 sum or read the last modification date but the the file is not available, vhistadd will abort with an error message. If this flag is not set, but either flags embed or automd5 are set and the file is not readable, vhistadd will also abort with an error message.
previewws	Hint that a VHIST browser with a suitable template can use this file as a preview image for the whole workflow step. Currenty must be a JPEG or PNG image.
preview	Hint that a VHIST browser with a suitable template can use this file as a preview image for the next embedded file. Currenty must be a JPEG or PNG image. Tip: define a "description" attribute to ensure correct identification of the associated data file.
thumbnail	Hint that a VHIST browser with a suitable template can use this file as a small preview image (usually called "thumbnail", e.g. a typical file icon for image files). Currenty must be a JPEG or PNG image.
thumbnailonly	Similiar to "thumbnail" but can be used to hint that this thumbnail image should be used in the context of the immediately following file and that no detailed information about this (illustrative) image is required (or, indeed, desired) as all relevant data will be supplied by the next image's attributes. CAVEAT: If the associated data file is of the type outfile, the thumbnail should also be of this type, similiar with the type infile.

-a <key> <value>
sets one or more pre-defined attributes. It is an error to
use other keywords than the ones defined below with this option.

An attribute describing a property of the previously specified in- or outfile.

Attribute	Brief Description
filetype	A user-defined text describing the file type. We suggest a convention reminiscent of the MIME [6] standard, e.g. binary/Analyze-Header.
description	A short description of the in- or outfile. There is no formal size limit, however, we suggest not to use this option with text significantly longer then a few lines. If required, put the description in a file which can then be embedded.
comment	Additional comments referring to the in- or outfile. We suggest to use this entry for observations during this particular workflow steps, e.g. unusually poor quality of data due to some hardware malfunction.
md5file	The name of a file which contains an MD5 checksum [4] in the first line. The sum is used as user specified md5 sum for the in- or outfile. This attribute is useful in situations in which a file is not embedded and the checksum was already generated by another application, e.g. for very large files where caluclating MD5 sum is only feasible with low-priority background processes.

-u <key> <value>
sets a key value pair of your choice.

We distinguish between user-defined attributes and Pre-defined attributes (files)

-u "my key" "my value"

sets the attribute

my key

to the value

my value.

-w <key> <value> <unit>
sets a key value unit tripple of your choice.

We distinguish between user-defined attributes and Pre-defined attributes (files)

-w "my key" "my value" "my unit"

sets the attribute

my key

to the value

my value. The value of the attribute has the unit my unit.

-v or
–verbose

Use this option to have vhistadd generate more verbose output to stdout.

-q or
–quiet

If this option is set, the output to stdout is reduced to errors only.

-p or
–pretend

If this option is set, vhistadd only parses the commandline and generates the workflow step but does not generate a VHIST file. This option is useful for verifying a commandline.

–stdin

vhistadd reads its commandline not from an argfile, but from stdin.

-1 or
–firstpage

A file containing the content of the first page of a newly created VHIST document. The content of the file must be encoded in UTF-8 [7]. The text can contain Wiki-like markup which supports bold, italic and one coloured (blue) font attributes. By default, vhistadd will use res/title.txt.

This option is ignored if the workflow step is appended to an existing VHIST file.

-r or
–readme

A file containing the readme, which is embedded at the beginning of a newly created VHIST document. The content of the file must be encoded in an ASCII compatible encoding, UTF-8 [7] is preferred. By default, vhistadd will use res/embedded_readme.txt. This option is ignored if the workflow step is appended to an existing VHIST file.

The following examples will generate a new VHIST file hello.vhist which "documents" a simple application of the echo command. CAVEAT: vhistadd will fail if hello.vhist already exists (this is by design to prevent you from unintentionally overwriting important data). You also need to take into account the general problems of passing commandline arguments with special characters (spaces, inverted commas) by escaping them (e.g. use "\!" if your text contains an exclamation mark) and/or using a suitable type of inverted commas.

vhistadd.py -s title "Hello VHIST" -s command "echo 'Hello VHIST'" -O hello.vhist

This example demonstrates how add information about a workflow step involving the co-registration of two image volumes (which is an important task in multi-modality imaging of human brains) using vhistadd. We think the general idea about documenting this non-trivial task involving multiple files can be easily transferred to other experimental setups.

Assuming we have a program my-coreg-tool that is capable of performing fully-automatic co-registration of image volumes and two image volumes of the same patient from two different modalities (here: MRI and PET scans of the same patient's brain). The tool will write a coreg.log protocol which we want to embed in the VHIST file (usually logs are so small that this is the recommended pratice) in addition to information about the co-registration result (another image volume: regimage-pet.v).

We have used the ECAT7 file type in this example, which encodes one image volume with meta information in a single file; binary indicates that this file type does not store information in any "human-readable" form.

vhistadd.py
 # the workflow step's title
 -s title "Co-Registration Task"
 # the program's name and version
 -s tool "my-coreg-tool v1.23"
 # the program's full path
 -s toolpath "/usr/bin/my-coreg-tool"
 # input file: co-registration log, will be embedded
 -i coreg.log -f embed)
 # setting optional file type info on previous file
 -a filetype "text/log")
 # input file: PET image volume of patient, do not embed
 -i "pat-pet.jpg" -f no-embed
 # setting optional file type info on previous file
 -a filetype "binary/ECAT7"
 # input file: MRI image volume of patient, do not embed
 -i "pat-mri.gif" -f no-embed
 # setting optional file type info on previous file
 -a filetype "binary/ECAT7"
 # output file: co-reg. PET image volume of patient
 -o "regimage-pet.png" -f no-embed
 # setting optional file type info on previous file
 -a filetype "binary/ECAT7"
 # VHIST output file (mandatory)
 -O "regimage-pet.png.vhist"

Please note that we have tried to keep this example brief. In the sense of "Good Scientific Practice" you can easily improve on this template by adding further attributes to the workflow step or individual files: Pre-defined attributes (workflow step), User-defined attributes (workflow step), User-defined attributes (files).

Based on the output of the previous example we now want to apply a 3D image filter to the registered image volume. Documentation of this next workflow step should take advantage of the existing processing history, i.e. use the VHIST file generated in the previous step.

This is achieved by specifying the previous VHIST as the VHIST root file: the VHIST file generated in this workflow step will then contain a copy of the full previous history, the new meta information on the current process (here: 3D filtering) is appended as a new section at the end.

vhistadd.py
  # the workflow step's title
  -s title "Gauss 3D Filter"
  # an optional description
  -s description "apply filter to PET image"
  # the program's name and version
  -s tool "my-filter-tool v2.34"
  # the program's full path
  -s toolpath "C:\\Programs and Files\\my-filter-tool.exe
  # optional attribute (key-value-pair)
  -U "gauss-fwhm-mm" "2.3"
  # input file: image volume, do not embed
  -i regimage-pet.png" -f no-embed
  # output file: filter.log, will be embedded
  -o "filter.log" - f embed
  # the VHIST root file
  -I "regimage-pet.v.vhist"
  # VHIST file to generate
  -O regimage-filtered.v.vhist