WhiskiWrap 1.2.1

Whisk package wrapper created by cxrodgers

WhiskiWrap

WhiskiWrap provides tools for running whiski (http://whiskertracking.janelia.org) more easily and efficiently.

My goal is to improve whiski in the following ways:

1. Make it more flexible about reading various input files. In my experience whiski has trouble reading certain input videos. Instead, WhiskiWrap uses your system's ffmpeg to read input files (because ffmpeg can typically read almost anything) and to generate simple tiff stacks which whiski can reliably read.
2. Make it faster, by calling many instances of trace in parallel on non-overlapping chunks of the input video.
3. Make it more cross-platform and memory-efficient, by converting whiski's output files into HDF5 files which can be read by multiple programs (Python, Matlab) on any operating system. Importantly, HDF5 files can also be read partially to avoid overflowing your system's memory.

Example

Note: The current best pipeline for running trace is interleaved_reading_and_trace, but the command pipeline_trace is the only one configured to run measure.

First start the interactive python environment by typing ipython at the terminal.

Import WhiskiWrap so it can be used:

import WhiskiWrap

Set the path to the input file. There are some test videos in this repository that you can use. Usually it's best to copy this file to a new directory, because a lot of temporary files will be created in the same directory.

mkdir ~/whiski_wrap_session
cp ~/dev/WhiskiWrap/test_video2.mp4 ~/whiski_wrap_session/test_video2.mp4
input_video = '~/whiski_wrap_session/test_video2.mp4'

Choose where you want the output HDF5 file to be.

output_file = 'output.hdf5'

Run the trace. Here we use 4 parallel processes.

WhiskiWrap.pipeline_trace(input_video, output_file, n_trace_processes=4)

If you go to the session directory, you'll see a bunch of tiff stacks and whiskers files that were generated by every instance of trace. There's also a combined HDF5 file with all the data combined. You can read it into Python like so:

import tables
import pandas
with tables.open_file(output_file) as fi:`
  test_result = pandas.DataFrame.from_records(
    fi.root.summary.read())     

This just reads the "summary": the tip and follicle of every whisker in every frame. The HDF5 file also contains the x- and y-coordinates of every pixel in every whisker, but you probably don't want to read all of this in at once.

More detail on how WhiskiWrap works

1. Split the entire video into epochs of about 100K frames (~100MB of data). The entire epoch will be read into memory, so the epoch size cannot be too big.
2. For each epoch:
3. Split it into chunks of about 1000 frames, each of which will be traced separately. The frames can optionally be cropped at this point.
4. Write each chunk to disk as a tiff stack (note: these files are quite large).
5. Trace each chunk with parallel instances of trace. A whiskers file is generated for each chunk.
6. Parse in order each chunk's whiskers file and append the results to an output HDF5 file.
7. (Optional) delete the intermediate chunk files here.

The following parameters must be chosen:

• n_trace_processes - the number of parallel instances of trace to run at the same time. The most efficient choice is the number of CPUs on your system.
• epoch_sz_frames - the number of frames per epoch. It is most efficient to make this value as large as possible. However, it should not be so large that you run out of memory when reading in the entire epoch of video. 100000 is a reasonable choice.
• chunk_sz_frames - the size of each chunk. Ideally, this should be epoch_size / n_trace_processes, so that all the processes complete at about the same time. It could also be epoch_size / (N * n_trace_processes) where N is an integer.

You may also add optional parameters to run the measure command

• measure=True - run measure command, default is False
• face='right' - run measure with face on right side, can also specify to 'left' side

Installation

WhiskiWrap is written in Python and relies on ffmpeg for reading input videos, tifffile for writing tiff stacks, whiski for tracing whiskers in the tiff stacks, and pytables for creating HDF5 files with all of the results. Also make sure that you have installed ffmpeg-python>=0.2.0.

Installing ffmpeg

First install ffmpeg and ensure it is available on your system path -- that is, you should be able to type ffmpeg in the terminal and it should find it and run it.

Installing whiski

Next install whiski. There are several ways to do this:

1. Download the pre-built binary. This is the easiest path because it doesn't require compiling anything. However, you still need to make a few changes to the Python code that is downloaded in order to make it work with WhiskiWrap.
2. Build whiski from source, using my lightly customized fork. This will probably require more trouble-shooting to make sure all of its parts are working.

To use the pre-built binary (preferred):

1. Download the zipped binary:
   1. Windows: Download whisk-1.1.0d-win32.exe or whisk-1.1.0d-win64.exe install adding to the PATH.
   2. Linux: Unpack with tar -xzf whisk-1.1.0d-64bit-Linux.tar.gz. Rename the unpacked directory to [Path-to-WhiskiWrap-Cloned-Repo]/whisk.Add to echo 'export WHISKPATH=[WhiskiWrap-Cloned-Path]/whisk' >> ~/.bashrc
   3. Mac: Unpack with tar -xzf whisk-1.1.0d-64bit-Linux.tar.gz. Rename the unpacked directory to [Path-to-WhiskiWrap-Cloned-Repo]/whisk. Add to echo 'export WHISKPATH=[WhiskiWrap-Cloned-Path]/whisk' >> ~/.bash_profile
2. Add the binaries to your system path so that you can run trace from the command line.
3. Install whisk package:
   1. git clone https://github.com/aiporre/whisk.git
   2. Copy recursively [Path-to-WhiskiWrap-Cloned-Repo]/whisk/lib/whisk/ to [Path-to-whisk-Cloned-Repo]/whisk/
   3. Install whisk package cd [Path-to-whisk-Cloned-Repo] && pip install .
4. In the WhiskiWrap repo install now this package with: pip install .
5. Test that everything worked by opening python or ipython and running import WhiskiWrap

To build from source:

1. Install required dependencies (gl.h, etc)
2. Download the source from my lightly modified fork, which makes the __init__ changes described above.
3. cd ~/dev
4. git clone https://github.com/aiporre/whisk.git
5. cd whisk
6. mkdir build && cd build
7. cmake ..
8. make
9. Copy a library into an expected location: [Path-to-whisk-Cloned-Repo]/bin
   1. In Windows: append to the PATH environmental variable [Path-to-whisk-Cloned-Repo]/bin
   2. In Linux: echo 'export WHISKPATH=[Path-to-whisk-Cloned-Repo]/bin/' >> ~/.bashrc
   3. In MacOS: echo 'export WHISKPATH=[Path-to-whisk-Cloned-Repo]/bin/' >> ~/.profile_bash
10. copy cp libwhisk.so ../whisk in Linux or mac, and copy whisk.dll ..\whisk in windows.
11. 'cd ..'
12. When you create your conda environment you should add whisk with pip install .
13. Test that everything worked by opening python or ipython and running from whisk import traj, trace
14. You need to the binaries to then environmental variables WHISKPATH and/or PATH

Installing Python modules

Here I outline the use of conda to manage and install Python modules. In the long run this is the easiest way. Unfortunately it doesn't work well with user-level pip. Specifically, you should not have anything on your $PYTHONPATH, and there shouldn't be any installed modules in your ~/.local.

1. create conda environemnt conda create -n WhiskiWrap python=3.9 pip (optional PyEnv or the nominal Python environment can also work)
2. activate with conda activate WhiskiWrap or source activate WhiskiWrap (optionally replace WhiskiWrap by your conda environment)
3. Installing WhiskWrap python module pip install . in the directory of this project
4. Install other packages...: conda install scipy pip install tifffile