Fivox  0.6.0
ITK library to sample events into regular volumes
Fivox Documentation

Introduction

Fivox (Field Voxelization) is a library to generate volumetric images of 3d scalar fields (Local Field Potential, spike densities, voltage sensitive dye), with loaders for the compartment, soma and spike reports generated by the Neuron and NEST simulators used in the Blue Brain Project. Fivox supports time animation. For more information see Applications.

Fivox can be retrieved by cloning the source code.

The voxelize command line tool can be used to generate volumes for ParaView or other volume rendering applications. When compiled with Livre, launch Livre with one of the URIs used by the voxelize command line tool as the volume parameter. The fivox data source will be loaded automatically and selected through one of the volume URI schemes.

The sample-point command line tool can be used to extract the time series at a specific 3D point. The output file can be then used as the input for the plot2D.py python tool to generate a 2D graph showing the evolution of the data over time.

To use the ImageSource programmatically, please refer to the fivox namespace documentation and voxelize command line tool.

3m_spikes_scaled.jpg
Fivox spike densities rendered in Livre
paraview.jpg
Using a Fivox volume in ParaView

Features

Fivox provides the following major features:

  • Converting compartment reports to volumetric LFP-like data
  • Converting spike reports densities to volumetric data
  • Converting compartment and surface area reports to volumetric data
  • Time and animation support
  • Extract the time series at a specific point

Installation

Build Fivox from source:

1 git clone https://github.com/BlueBrain/Fivox
2 mkdir Fivox/build
3 cd Fivox/build
4 cmake ..
5 make

Usage

All command line applications support the following parameters:

("help,h", "Show help message")
("version,v", "Show program name and version")
("volume", po::value<std::string>(), volumeHelp.c_str())
("time,t", po::value<float>(), "Timestamp to load in the report")
("times", po::value<fivox::Vector2f>(),
"Time range [start end) to load in the report")
("frame,f", po::value<unsigned>(), "Frame to load in the report")
("frames", po::value<fivox::Vector2ui>(),
"Frame range [start end) to load in the report");
R"(- Generic events from file: fivox://EventsFile
- Compartment reports: fivoxcompartments://BlueConfig?report=string&target=string
- Soma reports: fivoxsomas://BlueConfig?report=string&target=string
- Spike reports: fivoxspikes://BlueConfig?duration=float&spikes=path&target=string
- Synapse densities: fivoxsynapses://BlueConfig?target=string
- Synapse densities for pathways: fivoxsynapses://BlueConfig?preTarget=string&postTarget=string
- Voltage-sensitive dye reports: fivoxvsd://BlueConfig?report=string&target=string
Parameters for all types :
- BlueConfig: BlueConfig absolute file path (default: BBPTestData)
- target: name of the BlueConfig target (default: CircuitTarget)
- preTarget: target for presynaptic neurons for synapse densities (default: unset)
- postTarget: target for postsynaptic neurons for synapse densities (default: unset)
- gidFraction: take random cells from a fraction [0,1] of the given target (default: 1)
- inputMin/inputMax: minimum and maximum input values to be considered for rescaling
(defaults: [0.0, 2.0] for Spikes
[0.0, maxDensity] for Synapses
[-80.0, 0.0] for Compartments
[-15.0, 0.0] for Somas with TestData, [-80.0, 0.0] otherwise
[-0.0000147, 0.00225] for LFP with TestData, [-10.0, 10.0] otherwise
[-100000.0, 300.0] for VSD)
- functor: type of functor to sample the data into the voxels (defaults: 'density' for Synapses, 'frequency' for Spikes, 'field' for Compartments, Somas and VSD)
- maxBlockSize: maximum memory usage allowed for one block in bytes (default: 64MB)
- cutoff: the cutoff distance in micrometers (default: 100)
- extend: the additional distance, in micrometers, by which the original data volume will be extended in every dimension (default: 0, the volume extent matches the bounding box of the data events). Changing this parameter will result in more volumetric data, and therefore more computation time
- reference: path to a reference volume to take its size and resolution, overwrites the 'size' and 'resolution' parameter
- size: size in voxels along the largest dimension of the volume, overwrites the 'resolution' parameter
- resolution: number of voxels per micrometer (default: 0.0625 for densities, otherwise 0.1)
Parameters for Compartments:
- report: name of the compartment report (default: 'voltage'; 'allvoltage' if BlueConfig is BBPTestData)
- dt: timestep between requested frames in milliseconds (default: report dt)
Parameters for Somas:
- report: name of the soma report (default: 'soma'; 'voltage' if BlueConfig is BBPTestData)
- dt: timestep between requested frames in milliseconds (default: report dt)
Parameters for Spikes:
- duration: time window in milliseconds to load spikes (default: 10)
- spikes: path to an alternate out.dat/out.spikes file (default: SpikesPath specified in the BlueConfig)
Parameters for VSD:
- report: name of the voltage report (default: 'soma'; 'voltage' if BlueConfig is BBPTestData)
- areas: path to an area report file (default: path to TestData areas if BlueConfig is BBPTestData)
- dt: timestep between requested frames in milliseconds (default: report dt))";

The voxelize command line tool also supports:

("datatype,d", po::value<std::string>()->default_value("float"),
"Type of the data in the output volume "
"[float (default), int, short, char]")
("size,s", po::value<size_t>(),
"Deprecated; use size in volume URI instead.")
("output,o", po::value<std::string>(),
"Name of the output volume file (mhd and raw); contains frame "
"number if --frames or --times")
("decompose", po::value<fivox::Vector2ui>(),
"'rank size' data-decomposition for parallel job submission")
("export-events", po::value<std::string>(),
"Name of the output events file (binary format)");

The sample-point command line tool also supports:

("point,p", po::value<fivox::Vector3f>(),
"'x y z' coordinates of the point to be sampled (3 float "
"numbers, space separated)")
("output,o", po::value<std::string>(),
"Name of the output file, containing one line per value, in the "
"format \"timestamp value\". Also a header with information about "
"the generation: volume URI, dt, frame range and the point that "
"was sampled");

About

Fivox uses CMake to create a platform-specific build environment. The following platforms and build environments are tested:

  • Linux: Ubuntu 14.04, RHEL 6.6 (Makefile, x64)
  • Mac OS X 10.9

The API documentation can be found on bluebrain.github.io.