- config : added info that a method is required in the docstrings

- config : moved some variables at the top of the module for convenience
- moved example script to examples
- updated README

Author: guillaumelegoc

README.md

@@ -5,12 +5,13 @@
 
 This repository contains a package called `features_from_dlc` that is used to compute and plot behavioral metrics from DeepLabCut tracking files.
 
-You'll also find some utility scripts in the scripts folder, as well as separate notebooks (.ipynb files) in the notebooks directory.
+You'll also find some utility scripts in the `scripts` folder, notebooks (.ipynb files) in the `notebooks` directory and an example on how to use the package in the `examples` folder.
 
 Jump to :
 - [Install instruction](#quick-start)
 - [The `features_from_dlc` package](#the-features_from_dlc-package)
 - [Usage](#usage)
+- [The configuration file](#the-configuration-file)
 
 ##  Installation
 To use the scripts and notebooks, you first need to install some things. If conda is already installed, ignore steps 1-2.
@@ -66,13 +67,13 @@ The attempt to make this modular is the idea that the principle is always the sa
 #### Getting started
 Follow the instructions in the [Quick start](#quick-start) section. Then, the idea is to edit the example script and configuration files before running it your data. In principle you can do that with any text editor, but it is recommended to use an IDE for ease of use. You can use any of your liking, below is explained how to use Visual Studio Code.
 
-Note that after installation, the `features_from_dlc` package is installed inside the conda environment. The `features_from_dlc` folder is not used anymore, rather, we will use a script to import the package and use it on the data. The `ffd_quantify.py` script located in `scripts/` is a template you can copy and modify as needed.
+Note that after installation, the `features_from_dlc` package is installed inside the conda environment. The `features_from_dlc` folder is not used anymore, rather, we will use a script to import the package and use it on the data. The `ffd_quantify.py` script located in `examples/` is a template you can copy and modify as needed.
 
 ##### Visual Studio Code
 It's easier to use as conda is nicely integrated and it is made easy to switch between environments.
 1. Install [vscode](https://code.visualstudio.com/download) (it does not require admin rights).
 1. Install Python extension (squared pieces in the left panel).
-1. Open the `scripts/ffd_quantify.py` script. In the bottom right corner, you should see a "conda" entry : click on it and select the ffd conda environment. To run the script, click on the Play icon on the top right.
+1. Open the `examples/ffd_quantify.py` script. In the bottom right corner, you should see a "conda" entry : click on it and select the ffd conda environment. To run the script, click on the Play icon on the top right.
 
 #### Requirements
 You need to have tracked your video clips with DeepLabCut and saved the output files (either .h5 or .csv files). One file corresponds to one and only one trial, so you might need to split your original videos into several short clips around the stimulation onsets and offsets beforehand. This can be done with [`videocutter` program](https://github.com/TeamNCMC/videocutter). All files analyzed together must :
@@ -87,7 +88,7 @@ You also need a configuration file. It defines the features one wants to extract
 Optionnaly, you can have a settings.toml file next to the DLC files to analyze. It specifies the experimental settings (timings and pixel size). If the file does not exist, default values from the configuration file will be used instead. See [The settings.toml file](#the-settingstoml-file).
 
 #### Usage
-1. Copy-paste the `scripts/ffd_quantify.py` file elsewhere on your computer, open it with an editor.
+1. Copy-paste the `examples/ffd_quantify.py` file elsewhere on your computer, open it with an editor.
 1. Fill the `--- Parameters ---` section. This includes :
    - `directory` : the full path to the directory containing the *files to be analyzed*.
    - `configs_path` : the full path to the directory containing the *configuration files* (eg. `modality.py` and `config_plot.toml`).

configs/openfield.py

@@ -4,14 +4,13 @@
 Give it a sensible name, describing to which modality it corresponds (openfield, ...).
 
 All global variables (in CAPSLOCK before the Class definition) should exist.
-Remember to edit the `features_metrics_range` variable in the `get_features()` function
-to adjust when the in-stim quantifying metric should be computed.
 
 This particular version :
 modality : openfield
-features : speed, head angle, body angle, x, y
-author : Guillaume Le Goc (g.legoc@posteo.org), Rémi Proville (Acquineuro)
-version : 2024.11.27
+features : speed, heading angle, bending angle, x, y
+bodyparts : Left ear, Right ear, Nose, Tail base
+authors : Guillaume Le Goc (g.legoc@posteo.org), Rémi Proville (Acquineuro)
+version : 2024.12.19
 
 """
 
@@ -41,13 +40,34 @@
 # Features to normalize by subtracting their pre-stim mean. This must be a tuple, so if
 # there is only one, write it like FEATURES_NORM = ("something",)
 FEATURES_NORM = ("theta_body", "theta_neck")
+# Select the time range in which the metric is computed, in the same units as
+# `stim_time`, BEFORE time-shifting is performed. This should be a dict mapping a
+# feature to another dict, itself mapping a metric to a 2-elements list. The metrics
+# names should be defined in `Config.get_features()`.
+FEATURES_METRICS_RANGE = {
+    "speed": {"mean": [0.5, 1], "deceleration": [0.5, 0.60]},
+    "theta_body": {"mean": [0.75, 1]},
+    "theta_neck": {"mean": [0.75, 1]},
+    "xbody": {},
+    "ybody": {},
+}
+# Choose metrics that will have their y axis shared with the time series, eg.
+# when the metric is in the same units as the feature plotted. Same structure as
+# FEATURES_METRICS_RANGE, with True/False
+FEATURES_METRICS_SHARE = {
+    "speed": {"mean": True, "deceleration": False},
+    "theta_body": {"max": True},
+    "theta_neck": {"max": True},
+    "xbody": {},
+    "ybody": {},
+}
 # Multiplier of standard deviation to define the initiation of reaction to determine the
 # delay from stimulation onset
 NSTD = 3
 # Number of points to fit after signal is above NSTD times the pre-stim std
 NPOINTS = 3
 # Maximum allowed delay, above which it is not considered as a response
-MAXDELAY = 0.5  # in seconds
+MAXDELAY = 0.5  # in same units as CLIP_DURATION
 
 # --- Data cleaning parameters
 # Likelihood threshold, below which values will be interpolated.
@@ -74,9 +94,14 @@
     "ybody": "centroid y (mm)",
 }
 # Preset y axes limits
-FEATURES_YLIM = {}  # must be [ymin, ymax], empty {} for automatic
-# Features to NOT plot (must be a list [])
-FEATURES_OFF = ["xbody", "ybody"]
+FEATURES_YLIM = {
+    "speed": [0, 45],
+    "theta_body": [-60, 220],
+    "theta_neck": [-40, 120],
+    # must be [ymin, ymax]
+}  # must be [ymin, ymax], empty {} for automatic
+# Features to NOT plot
+FEATURES_OFF = ("xbody", "ybody")
 
 
 # --- Configuration class
@@ -177,6 +202,8 @@ def read_setting(self, setting, fallback):
         """
         Read key from settings, with a fallback if not there.
 
+        Required.
+
         Parameters
         ----------
         setting : str
@@ -204,6 +231,8 @@ def setup_time(self):
         Create the common time vector and shift all time variable so that stimulation
         onset is time 0. get_features() should be run before.
 
+        Required.
+
         """
         # common time vector for all time series
         self.time_common = np.linspace(
@@ -242,6 +271,8 @@ def get_pixel_size(self):
         3. PIXEL_SIZE global variable at the top of this file.
         This value is stored in `pixel_size` attribute.
 
+        Required.
+
         Parameters
         ----------
         settings : dict
@@ -284,6 +315,8 @@ def get_features(self) -> tuple[dict, dict, dict, dict]:
         eg. the computed metric is in the same units as the feature itself.
         - features_labels : maps a feature to its displayed name on the y-axis of graph.
 
+        Required.
+
         """
         # How to compute features. It must be mapping between a feature name and a
         # lambda function that takes a DataFrame as a sole argument and returns a Serie
@@ -317,32 +350,20 @@ def get_features(self) -> tuple[dict, dict, dict, dict]:
                 "mean": lambda val, _: np.mean(val),
                 "deceleration": lambda s, t: -self.get_accel_coef(s, t),
             },
-            "theta_body": {"max": lambda val, _: np.max(val)},
-            "theta_neck": {"max": lambda val, _: np.max(val)},
+            "theta_body": {"mean": lambda val, _: np.mean(val)},
+            "theta_neck": {"mean": lambda val, _: np.mean(val)},
             "xbody": {},
             "ybody": {},
         }
 
         # Select the time range in which the metric is computed, in the same units as
         # `stim_time`, before time-shifting is performed.
-        features_metrics_range = {
-            "speed": {"mean": [0.5, 1], "deceleration": [0.5, 0.75]},
-            "theta_body": {"max": [0.5, 1]},
-            "theta_neck": {"max": [0.5, 1]},
-            "xbody": {},
-            "ybody": {},
-        }
+        features_metrics_range = FEATURES_METRICS_RANGE
 
         # Choose metrics that will have their y axis shared with the time series, eg.
         # when the metric is in the same units as the feature plotted. This is a similar
         # dict, with True and False.
-        features_metrics_share = {
-            "speed": {"mean": True, "deceleration": False},
-            "theta_body": {"max": True},
-            "theta_neck": {"max": True},
-            "xbody": {},
-            "ybody": {},
-        }
+        features_metrics_share = FEATURES_METRICS_SHARE
 
         # Labels for each features, appears on the y axis of time series
         features_labels = FEATURES_LABELS
@@ -361,6 +382,8 @@ def write_parameters_file(
         """
         Saves (hardcoded) parameters used to analyze data and generate figures.
 
+        Required.
+
         Parameters
         ----------
         outdir : str
@@ -394,6 +417,8 @@ def preprocess_df(self, df: pd.DataFrame) -> pd.DataFrame:
         highly confident on a point that is badly placed, and there might be another way
         to find "bad" values.
 
+        Required.
+
         Parameters
         ----------
         df : pd.DataFrame

scripts/ffd_quantify.py examples/ffd_quantify.pyscripts/ffd_quantify.py renamed to examples/ffd_quantify.py

@@ -10,8 +10,6 @@
 
 import os
 
-import pandas as pd
-
 import features_from_dlc as ffd
 
 # --- Parameters ---
@@ -22,7 +20,7 @@
 
 # - Animals
 # Only files beginning by those will be processed. If only one, write as ("xxx",)
-animals = ("animal0", "animal1")
+animals = ("animal0", "animal1", "animal2")
 
 # - Groups
 # This must be a dictionnary {key: values}.
@@ -33,8 +31,8 @@
 # it's assigned to the corresponding condition, whether there's something else eleswhere
 # in the file name. See get_condition() function for examples.
 conditions = {
-    "condition1": ["mouse0"],
-    "condition2": ["identifier"],
+    "condition1": ["animal0"],
+    "condition2": ["something"],
     "condition3": ["something_else"],
 }
 # Choose whether the conditions are paired, eg. if the same subject appears in several
@@ -80,6 +78,7 @@
 )
 
 # # Alternatively, use already generated features.csv file
+# import pandas as pd
 # cfg = ffd.get_config(modality, configs_path, None)  # get config
 # features = pd.read_csv(os.path.join(outdir, "features.csv"))  # load features