Angicart

Installation

---

Angicart depends on OCaml and other open-source UNIX utilities, and is known to work on most Linux distributions and on OS X. OCaml is not currently supported on Windows. Lines beginning with $ are meant to be typed at the command-line (Terminal) without the $. Lines beginning with # are meant to be typed at a root shell. If you need help, please contact the author as described in the README.

1. Obtain and install git. General instructions can be found at git-scm.com/download.
2. Install system dependencies using your OS package manager. On OS X, homebrew is a package manager for Unix software, available at brew.sh/. Once homebrew is working, Angicart's system dependencies can be installed as:

   	$ brew install pcre sdl sdl_image

3. Obtain and install OCaml and OCaml packages. Angicart is known to work with recent versions of OPAM. To install OPAM, see opam.ocaml.org/. The library dependancies of Angicart are provided by OPAM packages. Once OPAM and the system dependencies are installed, invoke:

   	$ opam install batteries pcre lablgl ocamlsdl ounit

4. Obtain Angicart and run it. The following command will create a directory called angicart in the current directory.

   	$ git clone https://github.com/mnewberry/angicart.git

   Enter that directory.

   	$ cd angicart

   Run the graphdisplay program to see if everything works.

   	$ ./make.sh graphdisplay run --help

   If you see the help screen (and not an error), then everything is working.

Example

On Mac OS X 10.10.3 with Homebrew and Xcode installed (with the terms and conditions accepted), OCaml, OPAM, and Angicart can be installed with the following commands:

$ git clone https://github.com/mnewberry/angicart.git
$ brew install ocaml opam pcre sdl sdl_image
$ opam init
$ eval `opam config env`
$ opam install batteries pcre lablgl ocamlsdl ounit
$ cd angicart
$ ./make.sh graphdisplay run --help


ImageMagick can be installed on such a system via MacPorts with the following command:

$ sudo port install ImageMagick

Angicart Example

---

The directory example shows an example of Angicart usage by reproducing the analysis of the paper Newberry et al. (2015) The real substance is the process script and the comments within it. These illustrate how to process data using angicart. This page serves as a guide to using the processscript to reproduce the analysis of Newberry et al. (2015) as quickly as possible and explains the context in which process runs. For further details, consult the guide, the --help output of the angicart programs themselves, the comments within the process script, or the README in the main angicart directory. The input to Angicart is a series of sequentially-names PNG images. The dicom_N directories contain the exported raster planes of original DICOM files that have been converted to PNG.

downsample_dicom.sh

Running ./downsample_dicom.sh in the example directory will resample the files in dicom_N by averaging each 2x2x2-voxel cube into a single voxel as described in the Methods and Materials, Image Acquisition section of Newberry et al. (2015), and record the output in dicom_small_N. This step is required to run the example and process scripts. The downsample_dicom.sh script requires ImageMagick to be installed.

process, process.large

Running ./process from the Angicart source directory will execute the analysis on the resampled images (dicom_small_N) and store the results in example/out. Invoke the scripts from the angicart source directory as ./example or ./process since they refer to programs in the Angicart source directory such as ./make.sh. The process.large script runs the analysis on the original-dimension PNG images in dicom_N, and is not recommended as the excess pixel-scale noise in these images will introduce erroneous vessels.

Reproducing the Analysis

If Angicart is installed and working correctly, the analysis should proceed as in the following transcript:

angicart/ $ cd example
angicart/example/ $ ./downsample_dicom.sh
dicom_1/00000.png dicom_1/00001.png -> dicom_small_1/00000.png
dicom_1/00002.png dicom_1/00003.png -> dicom_small_1/00001.png
[...]
angicart/example/ $ cd ..
angicart $ example/process
[...]



This will create the main output data in example/out/dicom_small.all.tsv. The output can be compared with example/example.dicom_small.all.tsv, the original output from Newberry et al. (2015). Note that the files may not be identical, as columns such as the color column are generated randomly. The columns of the spreadsheet are:

tag, an arbitrary string naming the input file
name, an arbitrary string naming the vessel segment. angicart typically uses a textual description of the vessel endpoints, as this is guaranteed to uniquely specify the vessel within a given image.
len, the vessel segment length, in physical units (mm in the above example).
vol, the vessel segment volume, in physical units as above.
rad, the vessel radius, computed as the square root of (vol/(pxlen)).
voxc, the count of voxels in the segment
defc, the number of voxels outside a distance rad + 1 from the vessel centerline.
col, the color of a vessel in the .vis.gd file.
tips, the number of vessel endpoints downstream of this vessel.
parent, the name of this vessel's parent
beta, the ratio of this vessel's radius to its parent's radius, or NA if no parent exists.
gamma, the ratio of this vessel's length to its parent's length, or NA if no parent exists.
nchild, the number of children of this vessel.
q, the conserved exponent of radius, if any, of the downstream branching junction.
s, the conserved exponent of length, if any, of the downstream branching junction.



which can be imported into an editor for viewing or further analysis, as shown below.

Output files to verify your analysis are available to download as a zipped directory: dicom_small_out.zip.

Guide

---

Angicart depends on OCaml and other open-source UNIX utilities, and is known to work on most Linux distributions and on OS X. OCaml is not currently supported on Windows. Lines beginning with $ are meant to be typed at the command-line (Terminal) without the $. Lines beginning with # are meant to be typed at a root shell. If you need help, please contact the author as described in the README. Each program can be built using the accompanying script make.sh. For example, the program graphdisplay can be built using $ ./make.sh grapshdisplay native while the other four programs can be built by replacing graphdisplay with the desired program name.

Program Descriptions

• pngs2pls - Converts input image files to a list of points that differentiation vessels from nonvessels. Differentiation is accomplished by applying threshold to the brightness of individual voxels from the stack of input images.
  
  Options:
  -d Source directory for images named NNNNN.png
-r range
-t Use thresholding with value N.NNN
-g Output a graphdisplay file of the point list
-o Output file
-help Display this list of options
--help Display this list of options

  Example usage:
  $ pngs2pls.native -d dir -r min max -t threshold -o output where dir is the directory for the png images, min is the first index (an integer), max is the last index, threshold is the relative intensity between 0.0 and 1.0 to differentiate vasculature from nonvasculature, and output is the desired name for the output file with the list of points
• pls2pg - Creates point graph from the list of points created with png2pls
  
  Options:
  -f point list file, created by png2pls
-E Keep entire graph, not just the LCC
-o output file
-help Display this list of options
--help Display this list of options

  Example usage:
  $ pls2pg.native -o output [-f] points.pls where output is the desired name of the file with the point graph and points.pls is to be replaced with the name of the input file with the list of points from the program pngs2pls.
• skeletonize - Erodes the point graph data from pls2pg to determine the centerlines of the network.
  
  Options:
  -f pointgraph, created by pls2pg
-o Output file
-help Display this list of options
--help Display this list of options

  Example usage:
  $ skeletonize.native -o output [-f] lcc.pg output is the desired name of the file with the skeleton and lcc.pg is to be replaced with the name of the input file with the point graph from the program pls2pg.
• vis - Analyzes the full network topology and segment attributes given the skeleton from skeletonize
  
  Options:
  -f pointgraph, created by skeleton
-g Output graph for visualization
-v tree data tab-separated value file
-l the tag, or first data column
-b branchpoint data file
-S Output fake symmetric data
-A Output fake symmetric data
-d Dimension of a voxel in millimeters
-help Display this list of options
--help Display this list of options

  Example usage:
  vis.native -g out.gp -v out.tsv -d 0.7x0.7x0.8 [-f] skel.gd where out.gp is the desired name of the segmentented visualization; out.tsv is to be replaced by the desired name of the analysis (formatted as tab-separated values); the three numbers in 0.7x0.7x0.8 are to be replaced respectively by the horizontal separation between pixels, the vertical separation between pixels, and the separation bewteen consecutive images from the input image files; and skel.gd is to be replaced with the name of the input file with the skeleton from the program skeleton
• graphdisplay - Interactively visualizes with the network, skeleton, or segmentation.
  
  Options:
  -f File to display
-g Take a pointgraph file as input rather than a graphdisplay file
-p With -g, display points only (no edges)
-help Display this list of options
--help Display this list of options


FAQs

---

(Compiled from the various README.md files)

Publications:

• E. Tekin*, D. Hunt*, M.G. Newberry*, and V.M. Savage^s, (2016) Do vascular networks branch optimally or randomly across spatial scales? PLoS Computational Biology 12(11) e1005223.
• Newberry MG, Ennis DB, Savage VM (2015) "Testing Foundations of Biological Scaling Theory Using Automated Measurements of Vascular Networks." PLoS Comput Biol 11(8): e1004455. doi:10.1371/journal.pcbi.1004455
• Hunt D, Savage VM "Asymmetries arising from the space-filling nature of vascular networks." (preprint) arXiv:1508.03682