GitLocker: The Coding Marketplace

Description:

FreeClimber 0.3.1.1

FreeClimber
Overview
FreeClimber is a Python 3-based, background-subtracting particle detection algorithm that performs a local linear regression to quantify the vertical velocity of points moving in a common direction.

In lay terms:

Background-subtracting: Removes background pixels that do not change in a set range of frames over a video.

Particle detection: Identifies the x,y-coordinates of each spot/point/marker by frame/time.

Local linear regression: Finds the most linear segment of a position vs. time (velocity) curve by testing for the greatest regression coefficient over a subset of consecutive frames.

Vertical velocity: Slope of the most linear segment of the velocity curve, which corresponds with the most consistent increase in mean vertical position across n-frames.

This program was designed initially for assessing climbing performance in a Drosophila (fruit fly) rapid iterative negative geotaxis (RING) assay. However, this program employs several functions that may be of use beyond the initial design and can be accessed from the source code. This program includes a Graphical User Interface (GUI) for optimizing parameter configurations, and a command line interface for batch processing. This platform has several advantages over over methods and circumvents systemic biases associated with manual methods that are traditionally used to quantify climbing performance in flies.
Requirements
- argparse [1.1 ]
- ffmpeg [1.4 ]
- matplotlib [3.1.3 ]
- numpy [1.18.1]
- pandas [1.0.0 ]
- pip [20.0.2]
- scipy [1.4.1 ]
- trackpy [0.4.2 ]
- wxPython [4.0.4 ]

NOTE: We recommend using with a Python3.6 virtual environment, though it was built with a Python3.7 environment.
Installing
We recommend running this package in an Anaconda-based virtual environment. Anaconda can be downloaded here.
Make sure conda is installed (should return something like conda 4.7.11):
conda -V

Update conda if needed (press y when prompted):
conda update conda

Create a Python 3 virtual environment (replace python36 with your name of choice):
conda create -n python36 python=3.6 anaconda

NOTE: See note above about Python 3.6 vs. 3.7..
Activate your virtual environment:
conda activate python36

OR (if that doesn't work):
source activate python36

For more details about creating a conda virtual environment, see here. Once the environment is set up and activated, we can install the dependencies listed in the Requirements section above.
Using PyPi (recommended):
pip install FreeClimber
pip install ffmpeg-python

NOTE: We recommend downloading these two modules separately.
Using conda (still in beta testing):
conda install -c adamspierer freeclimber

Download the script files (can be done with git clone if user is familiar with git or by directly downloading the .py files into a single folder)
Cloning the git repository:
cd <folder of interest>
git clone https://github.com/adamspierer/FreeClimber.git

NOTE: As of now, the platform itself is not a module and these steps merely download the dependencies. The script files must be directly referenced when running the program. See our tutorial for usage instructions.
Test files
There are three different sets of video files in the test folder to demonstrate varying conditions.

clean_background
diff_number_flies
noisy_background

- clean_background: contains three vials of 9 flies per vial set on visually clean background (./examples/w1118_m_2_1.h264 OR ./examples/other/clean_background_few_flies.h264)
- diff_number_flies: contains six vials with 5, 10, 19, 23, 15, 33 flies per vial set on visually clean background (./examples_other/clean_background_different_flies.h264)
- noisy_background: small, noisy background with low resolution. This example is meant to illustrate how the platform can be configured to work with sub-optimal backgrounds, though better videos yield better results. (./examples/noisy_background_few_flies.h264)

We've also included an additional video with a wagon-wheel effect to illustrate how the detector can still perform well, even with horizontal lines moving across the screen. See ./example_other/clean_background_many_flies_with_lines.h264
Video files were recorded in h264 format (Raspberry Pi default) and can be incompatibile with certain media players. We recommend using VLC media player.
Usage
The following is a general overview of the platform usage. For detailed instructions, please see our tutorial page.
Make sure the FreeClimber scripts are downloaded and in a folder on your computer. Navigate to the FreeClimber directory and type:
cd <path_to_FreeClimber_scripts>

To run from the GUI:
Specify a file path to a video after the --video_file flag.
pythonw ./scripts/FreeClimber_gui.py --video_file ./example/w1118_m_2_1.h264

To run from the command line:
Specify a file path to a configuration file after the --config_file flag.
python FreeClimber_main.py --config_file ./example/example.cfg

--> A required <file>.cfg is needed to run the command line tool. This file is generated by the GUI, or can be modified from the provided example file. The program will find all specified video files of a common type (file_suffix) that are nested within the specified parent folder (project_path).
There are other options for running the command line version that can be accessed using the -h flag. In particular, there are options to --process_all, --process_undone, and --process_custom. As the names imply, you can process all, those unprocessed, or a custom list of flies. See the Tutorial page for more information.
Code Structure/Overview
FreeClimber_gui.py - GUI wrapper for the detector.py script.
FreeClimber_main.py - Command line interface wrapper for the detector.py script
detector.py - Contains the detector object, which is important for parsing the video file into a multi-dimensional numpy array (ndarray) and all the functions needed to get the data out.
example.cfg - A configuration file generated by the GUI or modified by the user from the provided example. It contains the detection parameters needed to run the program.
video_file.suffix - A video file (not image stack) to read in. Unsupported file formats can be converted using FFmpeg, a well-documented multimedia editing platform.
gather_files.py - Outputs a list of all files with a given suffix that can be used for customizing the files a user wants to process.
custom.prc - Output from gather_files.py, contains file paths that can be used to customize the files FreeClimber processes.
We encourage you to to visit our Tutorial page for a more thorough walk-through, description, and various caveats.
Deployment
This software has only been tested on a Mac OS X (Sierra 10.12.6) but is likely not limited to this OS.
Contributing
Contributors can fork from the repository and submit a pull request when modifications are ready. Please document the changes you made and any pertinent information that will help in our review of the changes.
Release History
We plan to release maintenance updates as needed, though we are unlikely to modify the platform's main functionality.
Citing this work
The manuscript associated with this platform is in the end stages of revision or in the review process. Please contact the authors directly for how to cite this work.
License
This work is licensed under the MIT license.
Authors
Written by Adam Spierer and Lei Zhuo with special thanks to Brown University's Computational Biology Core for assistance with code review.