# Documentation - Table of contents
* [Basic usage (quick start)](#quick-start)
* [Configuration options](#configuration-options)
  * [General file information](#general-file-information)
    * [Folder loading specification](#folder-loading-specification)
  * [Render movie](#render-movie)
  * [Channel metadata](#channel-metadata)
    * [Metadata override in sections](#channel-metadata-override-in-sections)
  * [Trackmate data](#trackmate-data-section)
  * [Export z-stack as volumetric data](#export-z-stack-as-volumetric-data)

* [Utilities to keep track of configuration files](#keeping-track-of-configuration-files)
  * [Command fileops-config](#command-fileops-config)
  * [Command fileops-summary](#command-fileops-summary)


# Quick start
Using the system is simple!

1- Create a configuration file. 
Add section header "DATA".
Include path (relative or absolute) to the image file that was recorded from the microscope.
Add constraints to the frames that will be parsed by the system, or the number of channels.
Include also parameter overriding data.

#### example.cfg
```
[DATA]
image = example.ome.tif
frame = all
channel = [0, 1]
override_dt = 10
```

In this configuration, the data file example.ome.tif is specified by a path relative from the location of example.cfg.
Then, the section is restricting channels 1 & 2 only, but allowing all frames to be parsed.
Finally, it is overriding the sampling time to 10 seconds and the objective magnitude to 60X.

We want to render a movie.
Then, we should add a subsequent header named "MOVIE".
Add the movie definitions as follows:

#### example.cfg - movie definition
```
[MOVIE]
title = My Title
description = Lorem Ipsum.
fps = 10
layout = twoch
zstack = all-max
filename = example.mp4
```

In this example, a movie with the name example.mp4 will be generated by rendering the two available channels using the `twoch` layout.
The movie will max-project all the images in the z-stack as established in the `zstack = all-max` configuration line.

Finally run in the terminal
```commandline
$ fileops-render example.cfg
```

# Configuration options

## General file information
Header "DATA".
This section specifies location of the file and any parameters that require overriding.
The use case of parameter overriding.

Current names allowed:

- `image`: file path (absolute or relative) of the image data acquired by the microscope.
If the path is relative, it will be referenced from the location of the configuration file.
- `series`: image series when the file format allows it and there are many series in the file.
- `frame`: restricts the number of frames to be used in the subsequent operations.
    Valid inputs are
  - `all`: use all frames.
  - list: frames can be declared using a list. 
  For example, if we want to fetch only frames 12 and 30, the line would look like:  
  ```frame = [12,30]```
  - ellipsis: this option allows to specify an interval.
  Syntax is `<initial frame>...<final frame>`.
  For example, if we want frames from 10 to 50, then the line should read:  
  ```frame = 10...50```
- `channel`: restrict channels. The only permitted way of declaration is by using a list.
- `override_dt`: override the sampling interval with a scalar number in seconds.


### Folder loading specification
When image series are stored in a folder, the `image` entry should be replaced by `folder` using the following convention:


## Render movie
Header "MOVIE".
To render a movie specified in the configuration file, use the package [movie-render](https://github.com/fabio-echegaray/movie-render).
Movie-render depends on this FileOps package.
![dependencies.svg](figs%2Fdependencies.svg)

If several movies are needed to be rendered from the same configuration file, separate every section with a name MOVIE followed by a dash and a correlative number.
E.g. MOVIE-1, MOVIE-2, and so on.

The supported parameters to render a movie from a configuration file are as follows:
- `title`: a title that is going to be rendered in the frames of the movie.
- `description`: an internal parameter to keep track of the description of what the movie is about.
- `fps`: frames per second that the movie will be rendered with.
- `layout`: specifies the layout of the movie when the data has several channels or when many z-slices are meant to be
  shown in a single frame.
  Current options are:
  - `two-ch`: renders two channels side by side.
- `zstack`: informs what to do with the z-stack in case the recorded data has this dimension.
- `zstack_fn`: informs what to do with the z-stack in case the recorded data has this dimension.
  Possible options are to select one z-stack or to project them into a single image.
  To select a single z-stack, just specify the number of the slice (starting from zero).
  To project the stack data onto a single image, the following options are currently available:
    - `all-max`: uses max projection.
- `roi`: Specifies the file of ROIs that the processing will use.
- `scalebar`: Set the scalebar size to the specified value in micrometers.
- `bitrate`: Set the bitrate of the movie in a format compatible with ffmpeg.
- `filename`: output name of the movie file.
- `include_tracks`: set to yes or true if you want to include Trackmate data (defined in Trackmate section) as an overlay to this movie.


## Channel metadata
Header must have a syntax "CHANNEL-<N>", where N is the channel number starting from 1 (1-index).
Currently, these 3 parameters are supported:
- `name`: name of the channel to be printed in every render.
- `color`: color or colormap (for example, a particular LUT) to render the channel with.
- `histogram`: yes or true if histogram information is to be included as a graph.
               Implementation varies depending on the render and the layout.

### Channel metadata override in sections
Channel information can be overridden in some sections.
This only applies to sections 'movie', 'volume' and 'panel'.
The syntax is "channel_<N>_<ATTR>", where N is the 1-indexed channel number and 
ATTR is the attribute that is being changed (drawn from the previous list of [parameters](#channel-metadata))
For example, to change the name of channel 1 in panel section 'PANEL-1', one should write:
```
[PANEL-1]
...
channel_1_name = New channel name!
...
```


## Trackmate data section
Trackmate data can be made available to other sections such as movie rendering, or volume export.
The parameters for this section are:
- `path`: path of where the Trackmate file is located.
- `store_path`: where the exported data will be saved if there is an export step in the pipeline (e.g. volume export), 
and in case the user wants to override the default path.


## Export z-stack as volumetric data
Implementation is PENDING.



# Keeping track of configuration files
To keep track of a set of configuration files, whereas this is for a particular project or in a general sense, the package provides several commands to keep track and bulk-edit configuration files.


## Command fileops-config

Create a summary of the content of config files.  
``` fileops-config generate_config_content```

Generate config files dependent on the column cfg_folder of the input spreadsheet file.  
```fileops-config generate```

Update config files based on the content of input spreadsheet file.  
```fileops-config edit```

Update config files summary list and location based on the input spreadsheet file.  
```fileops-config update```


## Command fileops-summary

Generate a summary list of microscope images stored in the specified path (recursively).
Output format is CSV.  
```fileops-summary make```

Export list of movie descriptions from microscopes to markdown format.  
```fileops-summary markdown```

Merge two lists of microscopy movie descriptions updating with the data of the second list.  
```fileops-summary merge```
