Merge pull request #62 from KumarLabJax/YODA-193-add-docstrings-to-nextflow-functions-modules-and-workflows

Add docstrings to nextflow functions, modules, and workflows

Author: SkepticRaven

nextflow/modules/fecal_boli.nf

@@ -1,3 +1,18 @@
+/**
+ * This module contains process definitions for fecal boli prediction and feature calculations.
+ */
+
+ /**
+ * Predicts fecal boli in the video at minute intervals.
+ *
+ * @param tuple
+ *  - video_file The input video file.
+ *  - in_pose The input pose file.
+ *
+ * @return tuple files
+ *  - Path to the original video file.
+ *  - Modified pose file with fecal boli predictions.
+ */
 process PREDICT_FECAL_BOLI {
     label "gpu"
     label "tracking"
@@ -16,6 +31,15 @@ process PREDICT_FECAL_BOLI {
     """
 }
 
+/**
+ * Extracts fecal boli features from the pose data.
+ *
+ * @param tuple
+ *  - video_file The input video file.
+ *  - in_pose The input pose file.
+ *
+ * @return fecal_boli The generated fecal boli feature CSV file.
+ */
 process EXTRACT_FECAL_BOLI_BINS {
     label "tracking"
     label "r_fboli_extract"

nextflow/modules/flexibility.nf

@@ -1,3 +1,21 @@
+/**
+ * This module contains process definitions for generating flexibility metrics.
+ * These metrics were published in https://doi.org/10.1038/s43587-022-00266-0
+ */
+
+/**
+ * Generates flexibility index metrics from pose data.
+ *
+ * @param tuple
+ *  - video_file The input video file.
+ *  - pose_file The input pose file.
+ *
+ * @return tuple files
+ *  - Path to the generated angles CSV file.
+ *  - Path to the generated dAC CSV file.
+ *  - Path to the generated dB CSV file.
+ *  - Path to the generated flexdexraw CSV file.
+ */
 process GENERATE_FLEXIBILITY_INDEX {
     label "frailty"
     label "cpu"
@@ -32,6 +50,16 @@ process GENERATE_FLEXIBILITY_INDEX {
     """
 }
 
+/**
+ * Generates rear paw width metrics from pose data.
+ *
+ * @param tuple
+ *  - video_file The input video file.
+ *  - pose_file The input pose file.
+ *
+ * @return rearpaw Path to the generated rear paw width CSV file.
+ * @return rearpawsave Path to the generated rear paw save CSV file.
+ */
 process GENERATE_REAR_PAW_WIDTH {
     label "frailty"
     label "cpu"

nextflow/modules/gait.nf

@@ -1,3 +1,16 @@
+/**
+ * This module contains process definitions for gait analysis.
+ */
+
+/**
+ * Generates gait statistics from pose data.
+ *
+ * @param tuple
+ *  - video_file The input video file.
+ *  - pose_file The input pose file.
+ *
+ * @return gait_file The generated gait statistics file.
+ */
 process GENERATE_GAIT_H5 {
     label "gait"
     label "cpu"
@@ -24,7 +37,15 @@ process GENERATE_GAIT_H5 {
     """
 }
 
-
+/**
+ * Generates gait bin files from gait statistics.
+ *
+ * @param tuple
+ *  - gait_file The input gait statistics file.
+ *  - speed_bin The speed bin size for generating gait bins.
+ *
+ * @return gait_bin_csv The generated gait bin CSV file.
+ */
 process GENERATE_GAIT_BIN {
     label "gait"
     label "cpu"

nextflow/modules/jabs_classifiers.nf

@@ -1,3 +1,18 @@
+/**
+ * This module contains process definitions related to JABS classifiers.
+ */
+
+/**
+ * Calculates features for JABS classifiers.
+ *
+ * @param tuple
+ *  - video_file The input video file.
+ *  - in_pose The input pose file.
+ *
+ * @return tuple files
+ *  - Path to the original pose file.
+ *  - Path to the generated feature cache directory.
+ */
 process GENERATE_FEATURE_CACHE {
     // This process will correct pose pathing to a v6 file
     label "jabs_classify"
@@ -23,6 +38,20 @@ process GENERATE_FEATURE_CACHE {
     """
 }  
 
+/**
+ * Predicts behaviors using JABS classifiers.
+ *
+ * @param tuple
+ *  - in_pose The input pose file.
+ *  - feature_cache The directory containing the generated features.
+ * @param classifiers A map of classifiers:
+ *  - <classifier_name>: classifier parameter maps (not used by this process)
+ *
+ * @return tuple files
+ *  - Path to the original pose file.
+ *  - Path to the feature cache directory.
+ *  - Path to the generated behavior file. All behavior predictions are stored in a single file.
+ */
 process PREDICT_CLASSIFIERS {
     label "jabs_classify"
     label "cpu"
@@ -46,25 +75,53 @@ process PREDICT_CLASSIFIERS {
     """
 }
 
+/**
+ * Generates behavior tables from pose file, feature file, and prediction file.
+ *
+ * @param tuple
+ *  - in_pose The input pose file.
+ *  - feature_cache The directory containing the generated features.
+ *  - behavior_files The behavior prediction file.
+ * @param classifiers A map of classifiers:
+ *  - <classifier_name>: classifier parameter maps:
+ *    - stitch_value: the gap size for stitching behavior bouts
+ *    - filter_value: the minimum length for behavior bouts
+ *
+ * @return tuple files
+ *  - Path to the generated behavior bout file.
+ *  - Path to the generated behavior summary file.
+ */
 process GENERATE_BEHAVIOR_TABLES {
     label "jabs_postprocess"
     label "cpu"
     label "r_jabs_tablegen"
 
     input:
     tuple path(in_pose), path(feature_cache), path(behavior_files)
-    val classifier
+    val classifiers
 
     output:
     tuple path("${in_pose.baseName}*_bouts.csv"), path("${in_pose.baseName}*_summaries.csv"), emit: files
 
     script:
     """
-    behavior_command="--behavior ${classifier.collect { entry -> "$entry.key --stitch_gap $entry.value.stitch_value --min_bout_length $entry.value.filter_value" }.join(' --behavior ')}"
+    behavior_command="--behavior ${classifiers.collect { entry -> "$entry.key --stitch_gap $entry.value.stitch_value --min_bout_length $entry.value.filter_value" }.join(' --behavior ')}"
     python3 /JABS-postprocess/generate_behavior_tables.py --project_folder . --feature_folder . --out_prefix ${in_pose.baseName} --out_bin_size 5 \${behavior_command}
     """
 }
 
+/**
+ * Generates heuristic classifier predictions.
+ *
+ * @param tuple
+ *  - in_pose The input pose file.
+ *  - feature_cache The directory containing the generated features.
+ * @param heuristic_classifiers A list of heuristic classifier configuration files.
+ *
+ * @return tuple files
+ *  - Path to the generated bout file.
+ *  - Path to the generated summary file.
+ */
 process PREDICT_HEURISTICS {
     label "jabs_postprocess"
     label "cpu"
@@ -87,6 +144,14 @@ process PREDICT_HEURISTICS {
     """
 }
 
+/**
+ * Converts a behavior summary table to features.
+ *
+ * @param in_summary_table The input behavior summary table.
+ * @param bin_size The bin size for feature extraction.
+ *
+ * @return features The generated feature file.
+ */
 process BEHAVIOR_TABLE_TO_FEATURES {
     label "jabs_table_convert"
     label "r_jabs_table_convert"

nextflow/modules/manual_correction.nf

@@ -1,3 +1,17 @@
+/**
+ * This module contains process definitions related to manually correcting pose data using SLEAP.
+ */
+
+/**
+ * Extracts a frame from a video as a png image.
+ *
+ * @param tuple
+ *  - video The input video file.
+ *  - pose_file The input pose file (not used in this process).
+ * @param frame_index The index of the frame to extract.
+ *
+ * @return frame A png image of the extracted frame.
+ */
 process EXTRACT_VIDEO_FRAME {
     label "sleap"
 
@@ -14,6 +28,13 @@ process EXTRACT_VIDEO_FRAME {
     """
 }
 
+/**
+ * Adds a set of frames to a new SLEAP project file for arena corner annotation.
+ *
+ * @param video_frames A list of png images to be added to the SLEAP project.
+ *
+ * @return sleap_file The generated SLEAP project file containing the frames and arena corner skeleton for annotation.
+ */
 process ADD_EXAMPLES_TO_SLEAP {
     label "sleap"
 
@@ -48,6 +69,14 @@ process ADD_EXAMPLES_TO_SLEAP {
     """
 }
 
+/**
+ * Integrates SLEAP corner annotations into a pose file.
+ *
+ * @param pose_file The input pose file to be corrected.
+ * @param sleap_file The SLEAP project file containing the corner annotations.
+ *
+ * @return pose_file The corrected pose file with integrated corner annotations.
+ */
 process INTEGRATE_SLEAP_CORNER_ANNOTATIONS {
     label "sleap_io"
 

nextflow/modules/multi_mouse.nf

@@ -1,3 +1,14 @@
+/**
+ * Predicts multi-mouse segmentation.
+ *
+ * @param tuple
+ *  - video_file The input video file
+ *  - in_pose The input pose file
+ *
+ * @return tuple files
+ *  - Path to the original video file.
+ *  - Modified pose file with multi-mouse segmentation predicted.
+ */
 process PREDICT_MULTI_MOUSE_SEGMENTATION {
     label "gpu_long"
     label "tracking"
@@ -16,6 +27,17 @@ process PREDICT_MULTI_MOUSE_SEGMENTATION {
     """
 }
 
+/**
+ * Predicts multi-mouse keypoints.
+ *
+ * @param tuple
+ *  - video_file The input video file
+ *  - in_pose The input pose file
+ *
+ * @return tuple files
+ *  - Path to the original video file.
+ *  - Modified pose file with multi-mouse keypoints predicted.
+ */
 process PREDICT_MULTI_MOUSE_KEYPOINTS {
     label "gpu_long"
     label "tracking"
@@ -34,6 +56,17 @@ process PREDICT_MULTI_MOUSE_KEYPOINTS {
     """
 }
 
+/**
+ * Predicts multi-mouse identity.
+ *
+ * @param tuple
+ *  - video_file The input video file
+ *  - in_pose The input pose file
+ *
+ * @return tuple files
+ *  - Path to the original video file.
+ *  - Modified pose file with multi-mouse identity predicted.
+ */
 process PREDICT_MULTI_MOUSE_IDENTITY {
     label "gpu"
     label "tracking"
@@ -52,6 +85,18 @@ process PREDICT_MULTI_MOUSE_IDENTITY {
     """
 }
 
+/**
+ * Generates multi-mouse tracklets from the pose, segmentaiton, and identity data.
+ *
+ * @param tuple
+ *  - video_file The input video file
+ *  - in_pose The input pose file
+ *  - num_animals The number of animals to generate tracklets for
+ *
+ * @return tuple files
+ *  - Path to the original video file.
+ *  - Modified pose file with multi-mouse tracklets generated.
+ */
 process GENERATE_MULTI_MOUSE_TRACKLETS {
     label "cpu"
     label "tracking"