okntool 8.4.3
Command line program to carry out okn related tasks.
Requires Python: >=3.9

# OKN TOOL PYTHON PACKAGE LIBRARY MANUAL
## Description
This program will draw the graph image in the ABI eye research group web experience recording folder according to config file information and plot type input. 
Moreover, it can also produce va table csv and html files for both individual and summary data folder.

There are 8 types of okn tool which are:
1.  **Trial** plot which represents sensor timestamp vs pupil displacement/movement graph for each trial.
2.  **Summary** plot which is the combination of all trial plots with the same x and y axis scales.
3.  **Staircase/progress** plot which is the graph image to visualize whether there is okn or not and the visual acuity etdrs calculation steps.
4.  **Tidy** plot, the special plot for all trial protocol in which borders and boundaries are drawn in tidest format.
5.  **Simpler** plot, the special plot for face detection and eye tracker related OKNs.
6.  **indi_va_table** which will create **indi_va_table.csv** and **indi_va_table.html** depand on whether there is okn or not in each trials.
7.  **sum_va_table** which will create **sum_va_table.csv** and **sum_va_table.html** by using **indi_va_table.csv** of each folder which is produced by **indi_va_table** okn tool type.
8.  **pnm_video_splitter** which will split **pnm_eye_video.mp4** into **pnm_left_eye_video** and **pnm_right_eye_video**.
9.  **overlay_pupil_detection** which will overlay pupil detection on eye videos of **opm** and **plm** manager recording.

## Installation requirements and guide
### Anaconda
To install this program, `Anaconda python distributing program` and `Anaconda Powershell Prompt` are needed.  
If you do not have `Anaconda`, please use the following links to download and install:  
Download link: https://www.anaconda.com/products/distribution  
Installation guide link: https://docs.anaconda.com/anaconda/install/  
### PIP install
To install `okntool`, you have to use `Anaconda Powershell Prompt`.  
After that, you can use the `okntool` from any command prompt.  
In `Anaconda Powershell Prompt`:
```
pip install okntool
```  
## Usage guide
### Example usage
```
okntool -t "(plot_type)" -d "(directory to the folder)" -c "(directory to config file)" -r "(referenced csv)"
```
plot_type: "trial", "summary" or "staircase"  
If you are using "trial" plot type, please -d "(directory to trial folder)".  
If you are using "summary" or "staircase" plot type, please -d "(directory to pim_recorded_folder/trials)".  
**-r** is only for "simpler" plot type.  

There is a example folder under `development` folder.  
If you want to test this program, you can clone this repository, install `okntool` and run the following command:  
**For trial plot**
```
okntool -t "trial" -d "development/example/trials/trials/trial-1-1_disk-condition-1-1"
```

**For summary plot**
```
okntool -t "summary" -d "development/example/trials/trials"
```

**For staircase/progress plot**
```
okntool -t "staircase" -d "development/example/trials/trials"
```
or
```
okntool -t "progress" -d "development/example/trials/trials"
```

**For tidy plot**
```
okntool -t "tidy" -d "development/example/trials/trials"
```

**For simpler plot**
```
okntool -t "simpler" -d "(folders which clip folders)"
```
or
```
okntool -t "simpler" -d "(folders which clip folders)" -c (simpler plot configuration) -r (referenced csv)
```
The **-c** and **-r** arguments are optional. The okntool has its own built-in config and default referenced csv location which is two folder back of input folder directory.
i.e. If the input folder diectory is "(example/result/okn)", the default referenced csv location is "(example/protocol.simpler.csv)". 

**For indi_va_table**
```
okntool -t "indi_va_table" -d "(folder which contains clip folders each contains decider.json)"
```
or
```
okntool -t "indi_va_table" -d "(folder which contains clip folders each contains decider.json)" -p "(template html file)" -n "(decider file name)" -r "(referenced csv)" -o "(output location)"
```
The **-p**, **-n**, **-r** and **-o** arguments are optional. The okntool has its own built-in template html, default decider file name and default referenced csv location which is two folder back of input folder directory.
i.e. If the input folder diectory is "(example/result/okn)", the default referenced csv location is "(example/protocol.simpler.csv)".  

**For sum_va_table**
```
okntool -t "sum_va_table" -d "(folder which contains folders each contains indi_va_table.csv)"
```
or
```
okntool -t "sum_va_table" -d "(folder which contains folders each contains indi_va_table.csv)" -p "(template html file)" -o "(output location)"
```
The **-p** and **-o** arguments are optional. The okntool has its own built-in template html.    

**For pnm_video_splitter**
```
okntool -t "pnm_video_splitter" -d "(location of pnm_eye_video.mp4)"
```
**For split_video**
```
okntool -t "split_video" -d "(recording folder directory)"
```
(or)
```
okntool -t "sv" -d "(recording folder directory)"
```
**For overlay_pupil_detection**
```
okntool -t "overlay_pupil_detection" -d "(recording folder directory)"
```
(or)
```
okntool -t "opd" -d "(recording folder directory)"
```
If you wanna use **okn_detector_summary.csv** outside of the recording folder,  
```
okntool -t "overlay_pupil_detection" -d "(recording folder directory)" -sc "(directory to summary csv)"
```
(or)
```
okntool -t "opd" -d "(recording folder directory)" -sc "(directory to summary csv)"
```
### oknserver_graph_plot_config.json
This is a built-in config file which contains the information how trial plot, summary plot and progress plot will be drawn.  
Please read more details about them in TRIAL_PLOT_README.md, SUMMARY_PLOT_README.md, PROGRESS_PLOT_README.md and TIDY_PLOT_README.md.
If you wanna change the parameters of config file, copy and paste the built-in config file into a different directory.
After that modify the config file and run the okntool with optional argument `-c (directory to new config file)`.  
```
okntool -t "(plot_type)" -d "(directory to the folder)" -c "(directory to new config file)"
```

### simpler_plot_config.json
This is a built-in config file which contains the information how simpler plot will be drawn.  
Please read more details in SIMLER_PLOT_README.md.
If you wanna change the parameters of config file, copy and paste the built-in config file into a different directory.

### To upgrade version  
In `Anaconda Powershell Prompt`,
```
pip install -U okntool
```
or
```
pip install --upgrade okntool
```