documentation

build_docs.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+
+die() { echo "ERROR: $*"; exit 2; }
+warn() { echo "WARNING: $*"; }
+
+for cmd in mkdocs pdoc3 genbadge; do
+    command -v "$cmd" >/dev/null ||
+        warn "missing $cmd: run \`pip install $cmd\`"
+done
+
+PACKAGE="etrack"
+PACKAGESRC="src/$PACKAGE"
+PACKAGEROOT="$(dirname "$(realpath "$0")")"
+BUILDROOT="$PACKAGEROOT/site"
+
+# check for code coverage report:
+# need to call nosetest with --with-coverage --cover-html --cover-xml
+HAS_COVER=false
+test -d cover && HAS_COVER=true
+
+echo
+echo "Clean up documentation of $PACKAGE"
+echo
+
+rm -rf "$BUILDROOT" 2> /dev/null || true
+mkdir -p "$BUILDROOT"
+
+if command -v mkdocs >/dev/null; then
+    echo
+    echo "Building general documentation for $PACKAGE"
+    echo
+
+    cd "$PACKAGEROOT"
+    cp .mkdocs.yml mkdocs-tmp.yml
+    if $HAS_COVER; then
+	echo "        - Coverage: 'cover/index.html'" >> mkdocs-tmp.yml
+    fi
+    mkdir -p docs
+    sed -e 's|docs/||; /\[Documentation\]/d; /\[API Reference\]/d' README.md > docs/index.md
+    mkdocs build --config-file mkdocs.yml --site-dir "$BUILDROOT"
+    rm mkdocs-tmp.yml docs/index.md
+    cd - > /dev/null
+fi
+
+if $HAS_COVER; then
+    echo
+    echo "Copy code coverage report and generate badge for $PACKAGE"
+    echo
+
+    cd "$PACKAGEROOT"
+    cp -r cover "$BUILDROOT/"
+    genbadge coverage -i coverage.xml
+    # https://smarie.github.io/python-genbadge/
+    mv coverage-badge.svg site/coverage.svg
+    cd - > /dev/null
+fi
+
+if command -v pdoc3 >/dev/null; then
+    echo
+    echo "Building API reference docs for $PACKAGE"
+    echo
+
+    cd "$PACKAGEROOT"
+    pdoc3 --html --config latex_math=True --config sort_identifiers=False --output-dir "$BUILDROOT/api-tmp" $PACKAGESRC
+    mv "$BUILDROOT/api-tmp/$PACKAGE" "$BUILDROOT/api"
+    rmdir "$BUILDROOT/api-tmp"
+    cd - > /dev/null
+fi
+
+echo
+echo "Done. Docs in:"
+echo
+echo "    file://$BUILDROOT/index.html"
+echo

docs/etrack.md

@@ -0,0 +1,35 @@
+# E-Fish tracking
+
+Tool for easier handling of tracking results.
+
+## Installation
+
+### 1. Clone git repository
+
+```shell
+git clone https://whale.am28.uni-tuebingen.de/git/jgrewe/efish_tracking.git
+```
+
+### 2. Change into directory
+
+```shell
+cd efish_tracking
+````
+
+### 3. Install with pip
+
+```shell
+pip3 install -e . --user
+```
+
+The ```-e``` installs the package in an *editable* model that you do not need to reinstall whenever you pull upstream changes.
+
+If  you leave away the ```--user``` the package will be installed system-wide.
+
+## TrackingResults
+
+Is a class that wraps around the *.h5 files written by DeepLabCut
+
+## ImageMarker
+
+Class that allows for creating MarkerTasks to get specific positions in a video.

docs/trackingdata.md

@@ -0,0 +1,4 @@
+# TrackingData
+
+Class that represents the position data associated with one noe/bodypart.
+

mkdocs.yml

@@ -0,0 +1,17 @@
+site_name: etrack
+
+repo_url: https://github.com/bendalab/etrack/
+
+edit_uri: ""
+
+site_author: Jan Grewe jan.grewe@g-node.org
+
+theme: readthedocs
+    
+nav:
+    - Home: 'index.md'
+    - 'User guide':
+        - 'etrack': 'etrack.md'
+        - 'TrackingData' : 'trackingdata.md'
+    - 'Code':
+        - API reference: 'api/index.html'

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 name = "etrack"
 dynamic = ["version"]
 dependencies = [
-  "nixio>=1.5",
+  "hdf5",
   "nixtrack",
   "numpy",
   "matplotlib",

src/etrack/__init__.py

@@ -1,3 +1,10 @@
+# -*- coding: utf-8 -*-
+""" etrack package for easier reading and handling of efish tracking data.
+
+Copyright © 2024, Jan Grewe
+
+Redistribution and use in source and binary forms, with or without modification, are permitted under the terms of the BSD License. See LICENSE file in the root of the Project.
+"""
 from .image_marker import ImageMarker, MarkerTask
 from .tracking_result import TrackingResult, coordinate_transformation
 from .arena import Arena, Region

src/etrack/arena.py

@@ -1,3 +1,6 @@
+"""
+Classes to construct the arena in which the animals were tracked.
+"""
 import logging
 import numpy as np
 import matplotlib.pyplot as plt

src/etrack/image_marker.py

@@ -1,8 +1,11 @@
-import matplotlib.pyplot as plt 
+"""
-import cv2
+Module that defines the ImageMarker and MarkerTask classes to manually mark things in individual images.
+"""
 import os
+import cv2
 import sys
-from IPython import embed
+import matplotlib.pyplot as plt 
+
 
 class ImageMarker:
 

src/etrack/info.py

@@ -6,6 +6,9 @@
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted under the terms of the BSD License. See
 # LICENSE file in the root of the Project.
+"""
+Package info.
+"""
 import os
 import json
 

src/etrack/io/__init__.py

@@ -0,0 +1,3 @@
+"""
+Reader classes for DeepLabCut, or SLEAP written data files.
+"""

src/etrack/tracking_data.py

@@ -1,3 +1,7 @@
+"""
+Module that defines the TrackingData class that wraps the position data for a given node/bodypart that has been tracked.
+"""
+
 import numpy as np
 
 

src/etrack/util.py

@@ -1,3 +1,6 @@
+"""
+Module containing utility functions and enum classes.
+"""
 from enum import Enum
 
 class Illumination(Enum):