=============== Documentation =============== BRAS ==== This aim of this program is to extract from a video the movement of bacteria. It can analyse an almost unlimited number of bacteria and its speed is determined by the data transfer rate. The user sets up interactively windows of interest to be analysed. Each window contains a single cell and a luminosity threshold is associated to remove the background information. The program calculates for each windows the position of the bacterium centre of mass along the time. Inputs ------ The program takes as input a video file. Depending of the OpenCV version used, you may need to use uncompressed video format. You can also provide a configuration file. Each time you analyse a video, a configuration file is saved containing the windows positions and intensity thresholds. If an experiment is split in multiple video files, you can use this file to keep the same windows across the experiment videos. As some video recorders may not record the frame per second (FPS) rate, it has to be set manually to avoid any errors in the later speed measurement. Utilisation ----------- A window showing the movie to be analysed is first opened. Using the keyboard, regions of interest have to be set. The following keys are available: * **+**/**-**: change the window size * **[left]**/**[right]**/**[up]**/**[down]**: move the window * **[space]**: select current window for analysis * **[backspace]**: remove previously selected window * **g**/**t**: change the contrast threshold * **z**, **x**, **c**, **v**: jump to start, 25%, 50%, 75% * **q**: launch the analysis The active window is in green while the already selected ones are in red. You can move the active window using the arrow keys and change its size. One important parameter is the contrast threshold: it is used to isolate the bacteria from the video background. When correctly set, you should see clearly the the bacteria in grey/white while the background should be black. When the position, the size and the contrast of the active window are set, you can store this setting with the space bar and select another bacteria. You can start the analysis of the movie by pressing the 'q' key. A monitor window will then appear to track the analysis process. At the end, graphs will be plotted showing the analysis done. They show the displacement of the bacteria in the window reference, the number of turns done function of the time and a simple analysis of the rotation speed. Outputs ------- *BRAS* saves at the end of the analysis, 3 kind of files in the video directory: * An **HDF5** file (suffix: *.h5*) containing all the data. 3 data-sets are stored in this file: * ``FPS``: the frame per second parameter * ``windows``: structure containing the region of interest (position, size, contrast threshold, number) * ``IQ``: 3D array containing the positions (x,y) positions for each bacteria for each frame. * A **video frame image** with the region of interest and their index overlayed. * The first analysis **plots** displayed at the end of the processing. **HDF5** files can be opened by most of the data processing software or languages: Python (using `PyTables`_ or `h5py`_), `R`_, `Octave`_, `Matlab`_, IDL, LabView, `Mathematica`_... This file is used by *Click & Mean* for the subsequent analysis. Click & Mean ============ *Click & Mean* helps in the extraction of long-term rotation speed trends. It reads the **HDF5** files generated by *BRAS* and writes output files in *CSV* format that can be read by almost any data analysis software or spreadsheet. When and **HDF5** file is opened, speed rotation is computed for every bacteria using 2 different techniques: * a simple differentiation of the instantaneous angle taken by bacteria over time. A filtered signal, in green, is also displayed *(Top graph)* * A time-frequency analysis of bacterial positions in complex plane using Short-time Fourier transforms presented as a spectrogram. *(Bottom graph)* Both graphs can be zoomed and panned using the mouse after having chosen the right option below the plot area. One can display the different bacteria analysed using the buttons **Back** and **Forward**. *Click & Mean* allows to calculate the average speed over a time period. To do so, click on the **Add** button. To select the time window for the averaging, click on the graph with the left button. The first click sets the start of the window and the second the end. The average speed (in Hz, i.e. turn per second) is calculate using 3 techniques and display on the side table. The following values are calculated: * **** is the differentiation of the instantaneous angle averaged over the time period. * **** is the differentiation of a re-normalised instantaneous angle averaged over the time period. The *re-normalised angle* is obtain by changing the plan reference for measuring the angle. This measurement works well for rotating bacteria but gives poor results for stopped ones. * **** is obtain by extracting the maximum frequency given by a discrete Fourier transform of position evolution on a complex plane. This works well is the rotation speed is constant during the selected time period. A measurement can be removed from the table by selecting it and clicking on the **Delete** button. Each recorded bacteria has its own measurement table displayed only when the associated graphs are present. You can finally export your measurements for all the bacteria in spreadsheet in *CSV* format using the menu. Video Player ============ This is a simple video analyser. You can move easily along your movie with a slider or move frame by frame using the side buttons. It gives you the position in minutes and seconds or in frame number. When opening a video, you can as an option open the *HDF5* file associated to the movie. If you decide to do so, you will be able to visualise the regions of interest and their number. You can also export the displayed frame as a *PNG* picture. .. _`PyTables`: http://www.pytables.org/ .. _`h5py`: http://h5py.alfven.org/ .. _`Matlab`: http://www.mathworks.com/help/techdoc/ref/hdf5.html .. _`Mathematica`: http://reference.wolfram.com/mathematica/ref/format/HDF5.html .. _`Octave`: http://www.gnu.org/software/octave/doc/interpreter/Simple-File-I_002fO.html .. _`R`: http://lib.stat.cmu.edu/R/CRAN/web/packages/hdf5/index.html .. Local Variables: mode: rst mode: ispell-minor ispell-dictionary: "british" End: