ztools

platfrom independent wrapper for running and benchmarking Zonation

Zonation conservation prioritization software can be run using both a GUI and command line interface. Often when running analyses runs in batch, repeating runs, or running the analysis in headless environments (such as Linux servers/computational units) it is useful to use Zonation's command line interface instead of the GUI. One way to build these CLI scripts is to use batch files - or bat-files - as suggested in the Zonation manual. Bat-files are also the foundation of Zonation "projects" as they define the necessary configuration files and parameters for a particular run. However, bat-files cannot be used on other platforms such as Linux.

In a nutshell, ztools is meant for:

1. Running Zonation runs in a platform independent way
2. Providing additional information on the run (Was the run successful? How long did the different stages take? What's the system configuration?)
3. Benchmarking Zonation on different hardware/software/OS configurations

Note that Zonation already reports much of the information mentioned in 2. In fact, some of the information is parsed/deduced directly from the run info file generated by Zonation. The added value here is that the results are in more concise form and direclty machine readable.

ztools package includes two command line utilities:

1. zrunner for running the Zonation-files and generating records of the run
2. zreader for reporting the results produced by zrunner

Install

WARNING as ztools has only reached version 0.1 be prepared for nothing to work and everything to change at later stage.

Dependencies

• Python 2.7+ (may work with older version as well, untested)
• pip (needed only if installing using pip).
• PyYAML. NOTE: pip/setuptools will try to install this as well so this stage is optional. On some platforms libyaml-dev or similar is needed.

Using pip

1. Install ztools directly from GitHub using the following command (may need administrative privileges):

pip install https://github.com/cbig/ztools/archive/master.zip

Using git

1. Clone the repository:

git clone https://github.com/cbig/ztools.git

2. In the package folder, install the ztools with the following command:

python setup.py install

Using bootstrapped setuptools

This option is not very well tested.

1. Download the package from https://github.com/cbig/ztools/archive/master.zip
2. Unzip the folder
3. In the package folder, install the ztools with the following command:

python setup.py install

Quick usage

zrunner

Quick roundup of available options:

usage: zrunner [-h] [-l YAMLFILE] [-x EXECUTABLE] [-o OUTPUT_FILE]
               [-w OVERWRITE] [-s]
               [INPUTS]

Run Zonation runs andperformance benchmarks.

positional arguments:
  INPUTS                input bat/sh file

optional arguments:
  -h, --help            show this help message and exit
  -l YAMLFILE, --load YAMLFILE
                        yaml file defining a suite of input files
  -x EXECUTABLE, --executable EXECUTABLE
                        select Zonation executable (must in PATH)
  -o OUTPUT_FILE, --outputfile OUTPUT_FILE
                        name of the output file
  -w OVERWRITE, --overwrite OVERWRITE
                        overwrite existing result file
  -s, --silent          run everything silent

The following examples use the basic Zonation tutorial runs and assume that you are located in folder zonation-tutorial/basic.

Running a bat file

Simply point a given bat-file to zrunner:

zrunner do_01_core_area_zonation.bat

Note that unless you use the silent switch -s/--silent an putput file will be produced.

Running a suite of bat-files as defined in a YAML file

Run all the runs in the tests folder:

zrunner -l tests/ztests_basic.yaml

The output will be created in the same folder with name pattern results_[YOUR_COMPUTER_NAME].yaml or you can define the output file name using the -o/--outputfile switch.

Running a bat-file using different Zonation versions

If you have several version of Zonation installed on your system you can define which one you want to use. If the Zonation executable is in our PATH, then you can use the short version. Oherwise a full path is needed. Here's how you run the same set of tutorial runs using zig4:

zrunner -l tests/ztests_basic.yaml -x zig4

zreader

Again, a quick roundup of available options:

usage: zreader [-h] INPUT

Read ztests result file

positional arguments:
  INPUT       input yaml file

optional arguments:
  -h, --help  show this help message and exit

Not much there, huh? Basically zreader only reads in a given zrunner produced output YAML file and produces a summary report out of it. So far only printing is implemented.

Reading the results from the single run (first example above) would look like this:

zreader results_[YOUR_COMPUTER_NAME].yaml


** SYSTEM INFO ****************************************************************
  Test run time: 2013-11-13T14:06:56.416638
  Test computer: XXXXXXXX
             OS: Linux
         Kernel: 3.10.XXXXX
   Architecture: x86_64


Zonation version: 3.1.9


** RUNS ***********************************************************************
[do_01_core_area_zonation.bat]
 Time to initialize (Zonation): 0 s
  Cell removal time (Zonation): 0 s
 Total elapsed time (Zonation): 3.0 s
 Total measured time (zrunner): 3.0 s

Besides some system information the tool just reports that the run was completed succesfully and the time spent on various stages. First 3 times reported are those measured by Zonation, the last (Total measured time) is measured by zrunner.