From e62d5981994e192a835db5650a8b9a746cd5fa09 Mon Sep 17 00:00:00 2001
From: Andi Gerken <andi.gerken@gmail.com>
Date: Thu, 22 Apr 2021 12:01:44 +0200
Subject: [PATCH] Minor documentation updates

---
 docs/app.md            | 99 ++++++++++++++++++++++++++++++++++++++++++
 docs/index.md          |  2 +
 src/robofish/io/app.py |  8 ++--
 3 files changed, 105 insertions(+), 4 deletions(-)
 create mode 100644 docs/app.md

diff --git a/docs/app.md b/docs/app.md
new file mode 100644
index 0000000..54bb225
--- /dev/null
+++ b/docs/app.md
@@ -0,0 +1,99 @@
+This module defines the command line interface.
+All commands have a ``--help`` option to get more info about them in the command line.
+
+
+## Print
+```bash
+robofish-io-print example.hdf5
+```
+Checking out the content of files.
+
+<small>
+
+```
+usage: robofish-io-print [-h] [--output_format {shape,full}] path
+
+This function can be used to print hdf5 files from the command line
+positional arguments:
+  path                  The path to a hdf5 file
+optional arguments:
+  -h, --help            show this help message and exit
+  --output_format {shape,full}
+                        Choose how datasets are printed, either the shapes or the full content is printed
+```
+
+</small>
+
+## Evaluate
+```bash
+robofish-io-evaluate *analysis_type* example.hdf5
+```
+Show some property of a file.
+
+
+<small>
+
+```
+usage: robofish-io-evaluate [-h] [--names NAMES [NAMES ...]] [--save_path SAVE_PATH]
+                            {speed,turn,orientation,relative_orientation,distance_to_wall,tank_positions,trajectories,evaluate_positionVec,follow_iid} paths [paths ...]
+
+This function can be called from the commandline to evaluate files.
+Different evaluation methods can be called, which generate graphs from the given files.
+With the first argument 'analysis_type', the type of analysis is chosen.
+
+positional arguments:
+  {speed,turn,orientation,relative_orientation,distance_to_wall,tank_positions,trajectories,evaluate_positionVec,follow_iid}
+                        The type of analysis.
+                        speed                - Evaluate the speed of the entities as histogram.
+                        turn                 - Evaluate the turn angles of the entities as histogram.
+                        orientation          - Evaluate the orientations of the entities on a 2d grid.
+                        relative_orientation - Evaluate the relative orientations of the entities as a histogram.
+                        distance_to_wall     - Evaluate the distances of the entities to the walls as a histogram.
+                        tank_positions       - Evaluate the positions of the entities as a heatmap.
+                        trajectories         - Evaluate the trajectories of the entities.
+                        evaluate_positionVec - Evaluate the vectors pointing from the focal fish to the conspecifics as heatmap.
+                        follow_iid           - Evaluate the follow metric in respect to the inter individual distance (iid).
+  paths                 The paths to files or folders. Multiple paths can be given to compare experiments.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --names NAMES [NAMES ...]
+                        Names, that should be used in the graphs instead of the pahts.
+  --save_path SAVE_PATH
+                        Filename for saving resulting graphics.
+```
+
+</small>
+
+## Trackviewer
+
+```bash
+robofish-trackviewer example.hdf5
+```
+
+The trackviewer is from a different repository. It was included in the install instructions.
+
+<small>
+
+```
+usage: robofish-trackviewer [-h] [--draw-labels] [--draw-view-vectors] [--far-plane FAR_PLANE] [--view-of-agents field of perception number of bins] [--view-of-walls field of perception number of bins]
+                            [--view-of-walls-matches]
+                            [trackset_file]
+
+View RoboFish tracks in a GUI.
+
+positional arguments:
+  trackset_file         Path to HDF5 file containing the tracks to view
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --draw-labels         Whether to draw labels inside the agents' outlines
+  --draw-view-vectors   Whether to draw view vectors to the right of / below the trackfile
+  --far-plane FAR_PLANE
+                        Maximum distance an agent can see
+  --view-of-agents field of perception number of bins
+  --view-of-walls field of perception number of bins
+  --view-of-walls-matches
+```
+
+</small>
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 8e3fd95..df674a3 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -153,6 +153,7 @@ If you find bugs or get stuck somewhere, please text `Andi` on Mattermost or by
 In the [Track Format Specification](https://git.imp.fu-berlin.de/bioroboticslab/robofish/track_format/uploads/f76d86e7a629ca38f472b8f23234dbb4/RoboFish_Track_Format_-_1.0.pdf) and in this package there are more possibilities, we don't describe explicitly here. If you want to use any of the following features, please ask Andi:
 
 Built in robofish.io and not described:
+
 - Multiple sampling frequencies
 - Timestamps per timestep
 - Calendar points
@@ -160,6 +161,7 @@ Built in robofish.io and not described:
 - Obstacles
 
 Planned in Track Format but not implemented:
+
 - 3D Tracks
 
 
diff --git a/src/robofish/io/app.py b/src/robofish/io/app.py
index fc6fee0..e31e9ca 100644
--- a/src/robofish/io/app.py
+++ b/src/robofish/io/app.py
@@ -1,10 +1,10 @@
 # -*- coding: utf-8 -*-
 
+"""
+.. include:: ../../../docs/app.md
+"""
+
 # -----------------------------------------------------------
-# Functions available to be used in the commandline to show and validate hdf5
-# according to the Robofish track format (1.0 Draft 7). The standard is
-# available at https://git.imp.fu-berlin.de/bioroboticslab/robofish/track_format
-#
 # Dec 2020 Andreas Gerken, Berlin, Germany
 # Released under GNU 3.0 License
 # email andi.gerken@gmail.com
-- 
GitLab