createFrequencyMatrix {SwimR} | R Documentation

## Analyzing the frequency of worm thrashing over time and creating the frequency matrix and annotation file

### Description

This function analyzes the frequency of worm thrashing over time for the files returned by the Tracker program and then combined the frequency of all files into a matrix and extracted genotype information from tracker file names to create annotation file.

### Arguments

`inputPath` | `inputPath` is a directory which contains the files returned by the Tracker program. Because annotation file is generated by extracting the genotype information from tracker file names, the user should use dashes to denote genotypes and separate the date in the file name like Genotype_Drug(if used)_Dose(if used)_Date_#. The following are some examples of tracker file names: N4_AMPH_100uM_2-11-14_1 (genotype is N4), dat-1ok157_IMI_10uM_12-12-12_7(genotype is dat-1ok157), cat-2e1112dat-1ok157_2-20-09_2 (genotype is cat-2e1112dat-1ok157) and dat-1ok157dop-3vs106_5-17-06_4 (genotype is dat-1ok157dop-3vs106).
`outputPath` | `outputPath` is a directory which saves the plots and files returned by the function.
`method` | The function provides four different counting methods: "FFT" (Fast Fourier Transform), "Extrema", "PeakDet" (peak delta) and "RT+GP" (Get Peaks plus Racetrack Filter) and the users can select one of them to output the corresponding frequency matrix. The default outputted `method` is "Extrema".
`Threshold` | `Threshold` is the amount of degrees (in radians) required to count at as thrash and the default is 0.6.
`DeltaPeakDt` | `DeltaPeakDt` is the threshold for "peak delta" algorithm, similar to `Threshold` and the default is 1.6.
`MinFrameBtwnMax` | `MinFrameBtwnMax` is the minimum number of frames between maxima and the default is 4.
`MinDelta` | `MinDelta` is similar to `DeltaPeakDet` and the default is 2.5.
`longPeriod` | `longPeriod` is the longest period cycle which is not zerod and the default is 5.
`AvWindowSize` | `AvWindowSize` is the length of the average window in seconds and the default is 10 seconds.
`fps` | `fps` is the frame per second and the default is 15.
`ZP_Length` | `ZP_Length` is the Zero-padding length and the default is 100.
`WindowSize` | `WindowSize` is the size of window for computing the Fast Fourier Transform and the default is 30.
`MaxCompWin` | `MaxCompWin` is the window size on deciding if the current angle is a maxima and the default is 2.
`minTime` | `minTime` is the minimum threshold of time points for the following analysis and the default is 0 second.
`maxTime` | `maxTime` is the maximum threshold of time points for the following analysis and the default is 600 seconds.

### Details

The createFrequencyMatrix function outputs six files:

1. `outputDescription_createFrequencyMatrix.html` contains a summary of all output files.

2. `XFig.jpg` is the image of scatter plot of one animal plotted as "Frequency vs Time(min)" with all four counting methods overlaid. "X" of "XFig.jpg" represents the input file names.

3. `XFigSub.jpg` is the same as `XFig.jpg` except counting methods are broken up into four different plots. This is very helpful in checking through a video to make sure that Tracker tracked the worm properly. Bad contrast can be a problem with Tracker missing the worm and these files help to identify troublesome videos for retracking or discarding.

4. `XFreq.csv` is the CSV file of raw data organized by column, where column one represents frequency as counted by FFT, column two represents frequency calculated by Extrema, column three represents frequency calculated by PeakDt, column four represents frequency as counted by RT+GP and column five represents time in seconds.

5. `frequencyMatrix.txt` is a TXT file which contains the information of `frequencyMatrix`.

6. `annotationfile.txt` is a TXT file which contains the information of `annotation`.

### Value

The createFrequencyMatrix function returns a list object which contains the following information:

`frequencyMatrix` | `frequencyMatrix` combines the analysis results of the frequency of worm thrashing over time for all Tracker files in the `inputPath`.
`annotation` | `annotation` contains all genotype information extracted from file names of all Tracker files in the `inputPath`.

### Note

The worm frequency analysis script in this function is converted from matlab script coded by Katherine Fleming and Paul Fleming.

### Author(s)

Jing Wang and Andrew Hardaway

### See Also

`SwimR`

### Examples

        inputPath <- system.file("extdata","trackerFiles",package="SwimR")
        outputPath <- getwd()
        freMat <- createFrequencyMatrix(inputPath, outputPath, method = "Extrema",
     Threshold = 0.6, DeltaPeakDt = 1.6, MinFrameBtwnMax = 4, MinDelta = 2.5, longPeriod = 5,
     AvWindowSize = 10, fps = 15, ZP_Length = 100, WindowSize = 30, MaxCompWin = 2, minTime = 0,
     maxTime = 600)

[Package SwimR version 1.20.0 Index]