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