diff --git a/examples/configs/README.md b/examples/configs/README.md
new file mode 100644
index 0000000..7861385
--- /dev/null
+++ b/examples/configs/README.md
@@ -0,0 +1,282 @@
+# JABS-postprocess Example Configuration Files
+
+This directory contains example configuration files for JABS-postprocess heuristic behavior classification, designed to help researchers understand and implement custom behavior detection algorithms.
+
+## Quick Start
+
+1. **Copy an example file** that matches your behavior of interest
+2. **Modify the parameters** for your specific experimental conditions  
+3. **Test with your data** using the command line interface
+4. **Iterate and refine** based on validation results
+
+```bash
+# Example usage with the basic locomotion configuration
+python -m jabs_postprocess.heuristic_classify \
+    --project_folder /path/to/your/project \
+    --behavior_config examples/configs/basic_locomotion.yaml \
+    --feature_folder features
+```
+
+## Available Configuration Files
+
+### `basic_locomotion.yaml` - **Beginner Level**
+**Purpose**: Detect when a mouse is actively moving above a simple speed threshold.
+
+**Key Features**:
+- Single condition: centroid velocity > 2.0 cm/s
+- Basic post-processing parameters
+- Extensive comments explaining each section
+- Perfect starting point for new users
+
+**Use Cases**:
+- Distinguishing movement from stationary periods
+- Basic activity level quantification
+- Locomotor response to treatments
+
+**Learning Objectives**: 
+- Understand basic YAML structure
+- Learn core configuration parameters
+- Practice simple threshold-based classification
+
+---
+
+### `complex_behavior.yaml` - **Advanced Level**  
+**Purpose**: Detect "Active Center Exploration" using multiple simultaneous conditions.
+
+**Key Features**:
+- Multi-condition logic (ALL/ANY operators)
+- Mathematical expressions (multiply, subtract, abs)
+- Spatial reasoning (center zone detection)
+- Behavioral state exclusion logic
+- Demonstrates full system capabilities
+
+**Use Cases**:
+- Open field anxiety studies
+- Spatial preference analysis
+- Complex ethological phenotyping
+
+**Learning Objectives**:
+- Master nested logical operators
+- Implement mathematical feature transformations
+- Design multi-modal behavioral definitions
+- Handle conflicting behavioral states
+
+---
+
+### `template_config.yaml` - **Reference Guide**
+**Purpose**: Comprehensive reference showing ALL available options and syntax patterns.
+
+**Key Features**:
+- Complete operator reference (>, <, >=, <=, all, any, minimum, maximum)
+- Mathematical expression examples (add, subtract, multiply, divide, abs)
+- Feature path directory
+- Parameter tuning guidelines
+- Troubleshooting guide
+- Performance optimization tips
+
+**Use Cases**:
+- Reference during configuration development
+- Learning advanced syntax patterns
+- Troubleshooting configuration issues
+- Understanding system capabilities
+
+**Learning Objectives**:
+- Comprehensive system knowledge
+- Advanced configuration techniques
+- Best practices and optimization
+- Debugging and validation strategies
+
+## Choosing the Right Configuration
+
+| **If you want to...** | **Start with** | **Complexity** |
+|------------------------|----------------|----------------|
+| Detect simple movement | `basic_locomotion.yaml` | * |
+| Learn the basics | `basic_locomotion.yaml` | * |
+| Detect complex behaviors | `complex_behavior.yaml` | **** |
+| Understand all options | `template_config.yaml` | ***** |
+| Create custom behaviors | `template_config.yaml` | ***** |
+
+## Configuration Structure Overview
+
+All configuration files follow the same basic structure:
+
+```yaml
+# 1. BEHAVIOR IDENTIFICATION
+behavior: Your Behavior Name
+
+# 2. POST-PROCESSING PARAMETERS  
+interpolate: 5    # Fill small gaps
+stitch: 10        # Merge nearby bouts
+min_bout: 30      # Minimum episode duration
+
+# 3. CLASSIFICATION LOGIC
+definition:
+  greater than:   # or other operators
+    - feature_path feature_description
+    - threshold_value
+```
+
+### Key Concepts
+
+**Post-processing Parameters**:
+- `interpolate`: Fills brief gaps in detection (handles tracking errors)
+- `stitch`: Combines nearby behavioral bouts (creates continuous episodes)  
+- `min_bout`: Sets minimum duration for valid behaviors (filters noise)
+
+**Mathematical Operations**:
+- `add`, `subtract`, `multiply`, `divide`: Basic arithmetic on features
+- `abs`: Absolute value (useful for angular differences)
+
+**Logical Operations**:  
+- `all`: Every condition must be true (AND logic)
+- `any`: At least one condition must be true (OR logic)
+- `minimum`: At least N conditions must be true
+- `maximum`: At most N conditions can be true
+
+**Comparison Operations**:
+- `greater than` (`>`, `gt`): Feature > threshold
+- `less than` (`<`, `lt`): Feature < threshold  
+- `greater than or equal` (`>=`, `gte`): Feature >= threshold
+- `less than or equal` (`<=`, `lte`): Feature <= threshold
+
+## Common Feature Paths
+
+Here are the most frequently used features for behavior classification:
+
+### Movement Features
+```yaml
+features/per_frame/centroid_velocity_mag          # Overall body speed
+features/per_frame/point_speeds NOSE speed        # Head movement
+features/per_frame/point_speeds BASE_NECK speed   # Neck movement
+features/per_frame/point_speeds FRONT_PAW_L speed # Left paw movement
+```
+
+### Spatial Features  
+```yaml
+wall_distances/wall_0                             # Distance to wall 0
+features/per_frame/corner_distances distance      # Distance to corner
+avg_wall_length                                   # Arena dimension (constant)
+```
+
+### Orientation Features
+```yaml
+features/per_frame/head_angle head_angle          # Head direction
+features/per_frame/wall_angle_0 wall_0_angle     # Angle relative to wall
+```
+
+## Parameter Tuning Guidelines
+
+### Speed Thresholds (cm/second)
+| Range | Typical Behaviors |
+|-------|------------------|
+| 0.5-2.0 | Micro-movements, grooming, sniffing |
+| 2.0-5.0 | Walking, casual exploration |
+| 5.0-15.0 | Active locomotion, investigation |
+| 15.0-30.0 | Running, escape responses |
+| >30.0 | Very rapid movement, panic |
+
+### Temporal Thresholds (frames at 30 fps)
+| Frames | Duration | Typical Use |
+|--------|----------|-------------|
+| 5-15 | 0.17-0.5s | Micro-behaviors, brief events |
+| 15-30 | 0.5-1.0s | Short interactions |
+| 30-90 | 1-3s | Moderate behavioral bouts |
+| 90-300 | 3-10s | Extended activities |
+| >300 | >10s | Sustained behavioral states |
+
+### Distance Thresholds  
+| Expression | Arena Fraction | Typical Use |
+|------------|----------------|-------------|
+| `avg_wall_length/10` | 10% | Very close to wall |
+| `avg_wall_length/5` | 20% | Periphery zone |
+| `avg_wall_length/3` | 33% | Center-periphery boundary |
+| `avg_wall_length/2` | 50% | Arena center |
+
+## Troubleshooting Guide
+
+### Common Issues and Solutions
+
+**"No behavior detected"**
+- Lower detection thresholds
+- Check that feature paths exist in your data
+- Verify units match expected ranges
+
+**"Too much behavior detected"** 
+- Raise detection thresholds
+- Add additional constraining conditions
+- Increase minimum bout length
+
+**"Fragmented behavior bouts"**
+- Increase `stitch` parameter
+- Decrease `min_bout` requirement
+- Add interpolation for small gaps
+
+**"YAML parsing errors"**
+- Check indentation (use spaces, not tabs)
+- Ensure proper nesting structure
+- Validate syntax with online YAML checker
+
+**"Feature not found errors"**
+- Verify feature paths exist in your HDF5 files
+- Check feature extraction completed successfully
+- Confirm animal indices match your data
+
+### Validation Workflow
+
+1. **Start Simple**: Begin with single-condition definitions
+2. **Visual Validation**: Check results against video footage
+3. **Iterative Refinement**: Gradually add complexity and tune parameters
+4. **Quantitative Validation**: Compare against manual scoring when possible
+5. **Documentation**: Record parameter choices and biological rationale
+
+## Scientific Best Practices
+
+### Configuration Development
+- **Document rationale**: Explain why you chose specific thresholds
+- **Version control**: Track configuration changes alongside analysis code
+- **Validate thoroughly**: Test with multiple animals and conditions
+- **Share configurations**: Enable reproducibility by sharing validated configs
+
+### Parameter Selection
+- **Biologically motivated**: Base thresholds on known behavioral characteristics
+- **Data-driven**: Use pilot data to inform reasonable parameter ranges
+- **Context-appropriate**: Adjust for different experimental paradigms
+- **Conservative first**: Start with stricter criteria, then relax as needed
+
+### Quality Control
+- **Manual verification**: Visually inspect classified bouts against video
+- **Cross-validation**: Test configurations on independent datasets  
+- **Sensitivity analysis**: Evaluate robustness to parameter changes
+- **Peer review**: Have colleagues validate behavioral definitions
+
+## Additional Resources
+
+### JABS-postprocess Documentation
+- [Main Repository](https://github.com/AdaptiveMotorControlLab/JABS-postprocess)
+- [Feature Extraction Guide](../../src/jabs_postprocess/utils/features.py)
+- [Heuristic Classification System](../../src/jabs_postprocess/utils/heuristics.py)
+
+### Related Research
+- **Open Field Analysis**: For spatial behavior paradigms
+- **Behavioral Phenotyping**: For comprehensive ethological analysis
+- **Motion Detection Algorithms**: For movement-based classifications
+
+### Community
+- Share your validated configurations
+- Request specific behavioral examples
+- Contribute improvements to example files
+
+---
+
+## Contributing
+
+Found an issue or have a suggestion for improvement?
+
+1. **Bug Reports**: File issues for incorrect examples or unclear documentation
+2. **New Examples**: Contribute configurations for additional behavioral phenotypes
+3. **Documentation**: Help improve clarity and completeness of comments
+4. **Validation**: Share results from using these configurations with your data
+
+---
+
+*Happy behavior analysis!*
\ No newline at end of file
diff --git a/examples/configs/basic_locomotion.yaml b/examples/configs/basic_locomotion.yaml
new file mode 100644
index 0000000..e2e46d6
--- /dev/null
+++ b/examples/configs/basic_locomotion.yaml
@@ -0,0 +1,95 @@
+# ================================================================================
+# BASIC LOCOMOTION DETECTION CONFIGURATION
+# ================================================================================
+# This configuration demonstrates the simplest form of heuristic behavior 
+# classification in JABS-postprocess: detecting when a mouse is actively moving.
+# 
+# Purpose: Classify frames where the mouse is engaged in active locomotion
+# Use Case: Basic movement analysis, distinguishing motion from stationary periods
+# Difficulty: Beginner
+# ================================================================================
+
+# BEHAVIOR DEFINITION
+# -------------------
+# The name that will appear in output files and behavior tables
+# This should be descriptive and match your experimental naming conventions
+behavior: 
+  Basic Locomotion
+
+# POST-PROCESSING PARAMETERS
+# ---------------------------
+# These parameters clean up the raw classification results to produce more
+# biologically meaningful behavior bouts
+
+# interpolate: Maximum number of frames to fill in missing/ambiguous classifications
+# - Used to handle brief tracking errors or ambiguous frames
+# - Value of 5 means gaps of 5 frames or less will be filled based on surrounding context
+# - At 30 fps: 5 frames = ~167ms of interpolation
+interpolate:
+  5
+
+# stitch: Maximum gap between behavior bouts that should be combined
+# - Joins nearby bouts of the same behavior separated by brief interruptions
+# - Value of 5 means locomotion bouts separated by ≤5 frames will be merged
+# - Helps create more continuous behavioral episodes
+stitch:
+  5
+
+# min_bout: Minimum number of frames required for a valid behavior bout
+# - Filters out very brief, likely spurious classifications
+# - Value of 15 means locomotion must persist for at least 15 frames to count
+# - At 30 fps: 15 frames = 0.5 seconds minimum locomotion episode
+min_bout:
+  15
+
+# BEHAVIOR CLASSIFICATION RULE
+# ----------------------------
+# This section defines the logical condition that must be met for a frame
+# to be classified as the target behavior
+
+definition:
+  # Use "greater than" comparison to detect movement above a threshold
+  greater than:
+    # First operand: The feature to evaluate
+    # This path references the centroid velocity magnitude from the feature file
+    # - "features/per_frame/centroid_velocity_mag" is the HDF5 dataset path
+    # - "centroid_velocity_mag" is a human-readable description for logs/output
+    - features/per_frame/centroid_velocity_mag centroid_velocity_mag
+    
+    # Second operand: The threshold value
+    # Mouse centroid must be moving faster than 2.0 cm/second to be classified as locomotion
+    # This threshold is deliberately conservative to avoid noise from micro-movements
+    # Typical mouse walking speeds range from 2-20 cm/s, running can exceed 30 cm/s
+    - 2.0
+
+# TECHNICAL NOTES
+# ---------------
+# • centroid_velocity_mag represents the instantaneous speed of the mouse's center of mass
+# • Values are in cm/second based on the pose estimation calibration
+# • This simple threshold approach works well for clear movement vs. stationary distinction
+# • For more nuanced locomotion analysis, consider multiple body part velocities
+#
+# FEATURE ALTERNATIVES
+# --------------------
+# Alternative features you might use for locomotion detection:
+# 
+# Using individual body part speeds:
+# - features/per_frame/point_speeds NOSE speed
+# - features/per_frame/point_speeds BASE_TAIL speed
+# 
+# Using segmentation-based centroid (if available):
+# - features/per_frame/shape_descriptor centroid_speed
+#
+# PARAMETER TUNING GUIDELINES
+# ---------------------------
+# • Lower threshold (e.g., 1.0): More sensitive, captures subtle movements
+# • Higher threshold (e.g., 5.0): More selective, only clear locomotion
+# • Longer min_bout (e.g., 30): Requires sustained movement episodes
+# • Shorter min_bout (e.g., 5): Allows brief movement bursts
+#
+# VALIDATION SUGGESTIONS
+# ----------------------
+# 1. Visually inspect classified bouts against video
+# 2. Check that stationary periods (grooming, sniffing) are excluded
+# 3. Verify that brief pauses during exploration don't fragment bouts excessively
+# 4. Compare total locomotion time against expected activity levels for your paradigm
\ No newline at end of file
diff --git a/examples/configs/complex_behavior.yaml b/examples/configs/complex_behavior.yaml
new file mode 100644
index 0000000..60ee174
--- /dev/null
+++ b/examples/configs/complex_behavior.yaml
@@ -0,0 +1,183 @@
+# ================================================================================
+# COMPLEX MULTI-CONDITION BEHAVIOR CLASSIFICATION
+# ================================================================================
+# This configuration demonstrates advanced heuristic classification using multiple
+# conditions, logical operators, and mathematical expressions to detect a complex
+# behavioral state: "Active Exploration in Arena Center"
+# 
+# Purpose: Detect when a mouse is actively exploring the central area of the arena
+#          while maintaining moderate locomotion and avoiding wall-oriented behaviors
+# Use Case: Open field anxiety studies, spatial preference analysis
+# Difficulty: Advanced
+# ================================================================================
+
+# BEHAVIOR DEFINITION
+# -------------------
+behavior: 
+  Active Center Exploration
+
+# POST-PROCESSING PARAMETERS
+# ---------------------------
+# More stringent parameters for complex behaviors to ensure reliability
+interpolate:
+  3    # Shorter interpolation window for precise behavioral episodes
+
+stitch:
+  10   # Longer stitch window to maintain exploration episodes despite brief pauses
+
+min_bout:
+  45   # Longer minimum bout (1.5s at 30fps) ensures sustained exploration behavior
+
+# COMPLEX CLASSIFICATION RULE
+# ----------------------------
+# This demonstrates the use of nested logical operators and mathematical expressions
+# to create sophisticated behavioral definitions
+
+definition:
+  # Main logical structure: ALL conditions must be satisfied simultaneously
+  all:
+    # CONDITION 1: Mouse must be actively moving (moderate locomotion)
+    # ------------------------------------------------------------------
+    - all:
+        # Multiple body parts must show movement to avoid misclassification during grooming
+        - greater than:
+            - features/per_frame/point_speeds NOSE speed
+            - 1.5    # Nose moving > 1.5 cm/s indicates head movement/exploration
+        
+        - greater than:
+            - features/per_frame/centroid_velocity_mag centroid_velocity_mag  
+            - 2.0    # Overall body movement > 2.0 cm/s
+        
+        # But not moving too fast (exclude running/escape behaviors)
+        - less than:
+            - features/per_frame/centroid_velocity_mag centroid_velocity_mag
+            - 15.0   # Less than 15 cm/s excludes rapid locomotion
+    
+    # CONDITION 2: Mouse must be in the center area of the arena
+    # ----------------------------------------------------------
+    - all:
+        # Distance from each wall must be greater than 30% of arena dimension
+        # This creates a "center zone" by excluding the periphery
+        
+        - greater than:
+            - wall_distances/wall_0
+            # Mathematical expression: multiply average wall length by 0.3
+            - multiply:
+                - avg_wall_length
+                - 0.3
+        
+        - greater than:
+            - wall_distances/wall_1
+            - multiply:
+                - avg_wall_length
+                - 0.3
+        
+        - greater than:
+            - wall_distances/wall_2
+            - multiply:
+                - avg_wall_length
+                - 0.3
+        
+        - greater than:
+            - wall_distances/wall_3
+            - multiply:
+                - avg_wall_length
+                - 0.3
+    
+    # CONDITION 3: Mouse should not be exhibiting wall-oriented behaviors
+    # -------------------------------------------------------------------
+    - any:
+        # This condition uses "any" to exclude mice that are wall-following
+        # At least one of these conditions must be true (mouse not hugging walls)
+        
+        # Head not oriented toward walls (excludes wall-sniffing/following)
+        - greater than:
+            - abs:
+                # Use absolute value of difference between head angle and wall orientation
+                - subtract:
+                    - features/per_frame/head_angle head_angle
+                    - features/per_frame/wall_angle_0 wall_0_angle
+            - 30.0    # Head angle differs from wall by more than 30 degrees
+        
+        # Alternative: mouse has moved significantly from wall in recent frames
+        # (This would require windowed features - commented out for this example)
+        # - greater than:
+        #     - features/windowed/distance_from_wall/mean mean_wall_distance_5frame
+        #     - divide:
+        #         - avg_wall_length  
+        #         - 4    # Must be >25% of arena dimension from walls on average
+
+    # CONDITION 4: Behavioral state consistency check
+    # ------------------------------------------------
+    # Ensure the mouse isn't in a conflicting behavioral state
+    - all:
+        # Not freezing (multiple body parts must be moving)
+        - any:
+            - greater than:
+                - features/per_frame/point_speeds BASE_NECK speed
+                - 1.0
+            - greater than:
+                - features/per_frame/point_speeds BASE_TAIL speed
+                - 1.0
+        
+        # Not engaged in intensive self-grooming
+        # (High paw speed combined with low centroid speed typically indicates grooming)
+        - or:
+            - greater than:
+                - features/per_frame/centroid_velocity_mag centroid_velocity_mag
+                - 3.0    # If moving moderately fast, not grooming
+            - less than:
+                - features/per_frame/point_speeds FRONT_PAW_R speed
+                - 8.0    # Or if right paw not moving rapidly
+
+# ADVANCED FEATURES DEMONSTRATED
+# ===============================
+# 1. Nested logical operators (all/any within all)
+# 2. Mathematical expressions (multiply, subtract, abs)
+# 3. Multi-feature combinations
+# 4. Spatial reasoning (center detection via wall distances)
+# 5. Behavioral exclusion logic (avoiding conflicting states)
+# 6. Threshold tuning for specific behavioral contexts
+
+# PARAMETER INTERPRETATION
+# ========================
+# Mathematical Operations:
+# • multiply: [avg_wall_length, 0.3] = 30% of average arena dimension
+# • subtract: [head_angle, wall_angle] = angular difference between head and wall
+# • abs: absolute value ensures positive angle differences
+#
+# Logical Operations:
+# • all: Every sub-condition must be True
+# • any: At least one sub-condition must be True  
+# • or: Alternative conditions (logical OR)
+
+# BIOLOGICAL RATIONALE
+# ====================
+# This configuration captures the behavioral phenotype of:
+# 1. Active exploration (moderate movement speeds)
+# 2. Central arena preference (anxiety indicator in open field tests)
+# 3. Non-thigmotactic behavior (not wall-following/hugging)
+# 4. Engaged locomotion (not freezing or self-grooming)
+
+# TUNING GUIDELINES
+# =================
+# Speed Thresholds:
+# • Increase lower bounds to be more selective for active exploration
+# • Decrease upper bounds to exclude more vigorous locomotion
+#
+# Spatial Thresholds:  
+# • Increase wall distance multiplier (0.3 → 0.4) for smaller center zone
+# • Decrease multiplier (0.3 → 0.2) for larger center zone
+#
+# Temporal Parameters:
+# • Increase min_bout for longer sustained episodes
+# • Adjust stitch to handle natural pauses in exploration
+
+# VALIDATION CHECKLIST
+# ====================
+# 1. Verify center zone size matches experimental design
+# 2. Confirm speed ranges capture intended locomotion types
+# 3. Check that wall-oriented behaviors are properly excluded
+# 4. Validate against manual scoring of exploration episodes
+# 5. Test sensitivity to different arena geometries
+# 6. Ensure robust performance across different animal sizes/strains
\ No newline at end of file
diff --git a/examples/configs/template_config.yaml b/examples/configs/template_config.yaml
new file mode 100644
index 0000000..a881587
--- /dev/null
+++ b/examples/configs/template_config.yaml
@@ -0,0 +1,332 @@
+# ================================================================================
+# COMPREHENSIVE CONFIGURATION TEMPLATE
+# ================================================================================
+# This template demonstrates ALL available configuration options and syntax
+# patterns supported by the JABS-postprocess heuristic classification system.
+# 
+# Use this as a reference guide when creating your own behavior definitions.
+# Copy relevant sections and modify parameters for your specific use case.
+# ================================================================================
+
+# SECTION 1: BEHAVIOR IDENTIFICATION
+# ===================================
+# REQUIRED: The behavior name that will appear in all output files
+# - Must be descriptive and unique within your analysis pipeline
+# - Avoid special characters that might cause file naming issues
+# - Use spaces for readability; underscores will be added automatically in filenames
+behavior: 
+  Template Behavior Name
+
+# SECTION 2: POST-PROCESSING PARAMETERS  
+# ======================================
+# These parameters refine raw classifications into meaningful behavioral bouts
+# All parameters are optional; if omitted, defaults from the parsing system are used
+
+# interpolate: Fill gaps in behavior detection
+# - Type: Integer (number of frames)
+# - Purpose: Handles brief tracking errors or ambiguous classifications
+# - Typical range: 1-10 frames
+# - Default: Usually 5 frames
+# - Example: At 30 fps, 5 frames = 167ms of gap filling
+interpolate:
+  5    # Recommended: 3-7 frames for most behaviors
+
+# stitch: Merge nearby behavior bouts
+# - Type: Integer (number of frames)  
+# - Purpose: Combines separated bouts of the same behavior
+# - Typical range: 5-30 frames
+# - Default: Usually 5 frames
+# - Example: Locomotion bouts separated by brief pauses get merged
+stitch:
+  10   # Recommended: 5-15 frames depending on behavior continuity
+
+# min_bout: Minimum duration for valid behavior episodes
+# - Type: Integer (number of frames)
+# - Purpose: Filters out brief, likely spurious classifications
+# - Typical range: 10-120 frames
+# - Default: Usually 15 frames
+# - Example: At 30 fps, 30 frames = 1 second minimum episode
+min_bout:
+  30   # Recommended: 15-60 frames for most behaviors
+
+# SECTION 3: BEHAVIOR CLASSIFICATION RULE
+# ========================================
+# This is the core logic defining when the behavior occurs
+# The 'definition' section must contain exactly one top-level operator
+
+definition:
+  # TOP-LEVEL LOGICAL OPERATORS
+  # ---------------------------
+  # Choose ONE of these as your main structure:
+
+  # Option 1: ALL conditions must be true (logical AND)
+  # Used when multiple criteria must be satisfied simultaneously
+  all:
+    # INEQUALITY OPERATORS
+    # --------------------
+    # Compare features or expressions against thresholds
+
+    # Greater than comparisons
+    # Available aliases: ">", "gt", "greater than"
+    - greater than:
+        - features/per_frame/centroid_velocity_mag centroid_velocity_mag
+        - 2.0    # Threshold value (can be integer or float)
+
+    # Less than comparisons  
+    # Available aliases: "<", "lt", "less than"
+    - less than:
+        - features/per_frame/point_speeds NOSE speed
+        - 15.0
+
+    # Greater than or equal
+    # Available aliases: ">=", "=>", "gte", "greater than equal", "greater than or equal"
+    - greater than or equal:
+        - wall_distances/wall_0
+        - 5.0
+
+    # Less than or equal
+    # Available aliases: "<=", "=<", "lte", "less than equal", "less than or equal"  
+    - less than or equal:
+        - features/per_frame/centroid_velocity_mag centroid_velocity_mag
+        - 20.0
+
+    # NESTED LOGICAL OPERATORS
+    # ------------------------
+    # You can nest logical operators for complex conditions
+
+    # ANY: At least one condition must be true (logical OR)
+    # Available aliases: "any", "or", "|"
+    - any:
+        - greater than:
+            - features/per_frame/point_speeds FRONT_PAW_L speed
+            - 3.0
+        - greater than:
+            - features/per_frame/point_speeds FRONT_PAW_R speed
+            - 3.0
+
+    # MINIMUM: At least N conditions must be true
+    # Available aliases: "minimum", "at least"
+    - minimum:
+        - 2    # At least 2 of the following conditions must be true
+        - greater than:
+            - wall_distances/wall_0
+            - 10.0
+        - greater than:
+            - wall_distances/wall_1  
+            - 10.0
+        - greater than:
+            - wall_distances/wall_2
+            - 10.0
+        - greater than:
+            - wall_distances/wall_3
+            - 10.0
+
+    # MAXIMUM: At most N conditions can be true
+    # Available aliases: "maximum", "at most"  
+    - maximum:
+        - 1    # At most 1 of the following can be true
+        - less than:
+            - wall_distances/wall_0
+            - 5.0
+        - less than:
+            - wall_distances/wall_1
+            - 5.0
+
+    # MATHEMATICAL EXPRESSIONS
+    # ========================
+    # You can perform calculations on features before comparison
+
+    # ADDITION
+    - greater than:
+        - add:
+            - features/per_frame/point_speeds FRONT_PAW_L speed
+            - features/per_frame/point_speeds FRONT_PAW_R speed
+        - 8.0    # Sum of both front paw speeds > 8.0
+
+    # SUBTRACTION  
+    - greater than:
+        - subtract:
+            - features/per_frame/point_speeds NOSE speed
+            - features/per_frame/centroid_velocity_mag centroid_velocity_mag
+        - 1.0    # Nose speed exceeds body speed by > 1.0
+
+    # MULTIPLICATION
+    - less than:
+        - multiply:
+            - avg_wall_length
+            - 0.2    # 20% of average wall length
+        - wall_distances/wall_0
+
+    # DIVISION
+    - greater than:
+        - divide:
+            - features/per_frame/point_speeds NOSE speed
+            - features/per_frame/centroid_velocity_mag centroid_velocity_mag  
+        - 1.5    # Nose speed ratio to body speed > 1.5
+
+    # ABSOLUTE VALUE
+    - less than:
+        - abs:
+            - subtract:
+                - features/per_frame/head_angle head_angle
+                - features/per_frame/wall_angle_0 wall_0_angle
+        - 45.0   # Absolute angular difference < 45 degrees
+
+# ALTERNATIVE TOP-LEVEL STRUCTURES
+# =================================
+# Instead of 'all', you could use any of these as your main operator:
+
+# Single simple condition (most common for basic behaviors)
+# definition:
+#   greater than:
+#     - features/per_frame/centroid_velocity_mag centroid_velocity_mag
+#     - 3.0
+
+# Any condition must be true
+# definition:
+#   any:
+#     - greater than:
+#         - features/per_frame/point_speeds NOSE speed
+#         - 5.0
+#     - greater than:
+#         - features/per_frame/centroid_velocity_mag centroid_velocity_mag
+#         - 3.0
+
+# At least N conditions 
+# definition:
+#   minimum:
+#     - 3
+#     - [list of conditions...]
+
+# At most N conditions
+# definition:  
+#   maximum:
+#     - 2
+#     - [list of conditions...]
+
+# SECTION 4: COMMON FEATURE PATHS
+# ================================
+# Reference guide for frequently used features in JABS-postprocess
+
+# MOVEMENT/VELOCITY FEATURES:
+# ---------------------------
+# features/per_frame/centroid_velocity_mag          # Overall body movement speed
+# features/per_frame/point_speeds NOSE speed        # Nose/snout movement
+# features/per_frame/point_speeds BASE_NECK speed   # Neck base movement
+# features/per_frame/point_speeds BASE_TAIL speed   # Tail base movement  
+# features/per_frame/point_speeds FRONT_PAW_L speed # Left front paw
+# features/per_frame/point_speeds FRONT_PAW_R speed # Right front paw
+# features/per_frame/point_speeds BACK_PAW_L speed  # Left back paw
+# features/per_frame/point_speeds BACK_PAW_R speed  # Right back paw
+
+# SPATIAL/POSITION FEATURES:
+# --------------------------
+# wall_distances/wall_0                             # Distance to wall 0
+# wall_distances/wall_1                             # Distance to wall 1  
+# wall_distances/wall_2                             # Distance to wall 2
+# wall_distances/wall_3                             # Distance to wall 3
+# features/per_frame/corner_distances distance      # Distance to nearest corner
+# avg_wall_length                                   # Average arena wall length (constant)
+
+# ORIENTATION FEATURES:
+# ---------------------  
+# features/per_frame/head_angle head_angle          # Head orientation angle
+# features/per_frame/wall_angle_0 wall_0_angle     # Angle relative to wall 0
+# features/per_frame/wall_angle_1 wall_1_angle     # Angle relative to wall 1
+# features/per_frame/wall_angle_2 wall_2_angle     # Angle relative to wall 2
+# features/per_frame/wall_angle_3 wall_3_angle     # Angle relative to wall 3
+
+# SHAPE/SIZE FEATURES (if available):
+# -----------------------------------
+# features/per_frame/shape_descriptor area          # Mouse body area
+# features/per_frame/shape_descriptor perimeter     # Mouse body perimeter
+# features/per_frame/shape_descriptor centroid_speed # Alternative centroid speed
+
+# SECTION 5: COMMON PARAMETER VALUES
+# ===================================
+
+# VELOCITY THRESHOLDS (cm/second):
+# --------------------------------
+# 0.5-1.0:   Micro-movements, grooming, subtle position adjustments
+# 1.0-2.0:   Slow movements, cautious exploration, sniffing
+# 2.0-5.0:   Moderate locomotion, typical walking/exploration
+# 5.0-15.0:  Active locomotion, faster walking, investigation
+# 15.0-30.0: Running, escape responses, vigorous movement
+# >30.0:     Very fast locomotion, panic responses
+
+# DISTANCE THRESHOLDS (cm or arena fractions):
+# ---------------------------------------------
+# Wall proximity:
+# - avg_wall_length/10 (10%): Very close to wall
+# - avg_wall_length/5  (20%): Near wall, periphery zone  
+# - avg_wall_length/4  (25%): Moderate wall distance
+# - avg_wall_length/3  (33%): Center-periphery boundary
+# - avg_wall_length/2  (50%): Arena center
+
+# TEMPORAL THRESHOLDS (frames at 30 fps):
+# ----------------------------------------
+# 5-10 frames:   Brief events, micro-behaviors (0.17-0.33 seconds)
+# 15-30 frames:  Short behaviors, quick interactions (0.5-1.0 seconds)  
+# 30-90 frames:  Moderate behaviors, exploration bouts (1-3 seconds)
+# 90-300 frames: Extended behaviors, sustained activities (3-10 seconds)
+# >300 frames:   Long-duration states, behavioral epochs (>10 seconds)
+
+# ANGULAR THRESHOLDS (degrees):
+# -----------------------------
+# 0-15°:   Very aligned, parallel orientation
+# 15-45°:  Moderate angle difference
+# 45-90°:  Significant angle difference
+# 90-135°: Perpendicular to opposite orientations
+# 135-180°: Opposing orientations
+
+# SECTION 6: TROUBLESHOOTING GUIDE
+# =================================
+
+# COMMON ISSUES AND SOLUTIONS:
+# -----------------------------
+
+# Issue: "No behavior detected" 
+# Solution: Lower thresholds, check feature availability, verify data paths
+
+# Issue: "Too much behavior detected"
+# Solution: Raise thresholds, add additional constraining conditions
+
+# Issue: "Fragmented behavior bouts"
+# Solution: Increase 'stitch' parameter, decrease 'min_bout' requirement
+
+# Issue: "Brief spurious detections"  
+# Solution: Increase 'min_bout' parameter, add sustained condition requirements
+
+# Issue: "Behavior bleeds into other states"
+# Solution: Add exclusion conditions (e.g., not freezing, not grooming)
+
+# Issue: "YAML parsing errors"
+# Solution: Check indentation (use spaces, not tabs), validate syntax
+
+# Issue: "Feature not found"
+# Solution: Verify feature paths exist in your data, check HDF5 file structure
+
+# VALIDATION WORKFLOW:
+# --------------------
+# 1. Start with simple single-condition definitions
+# 2. Test with known positive/negative examples
+# 3. Gradually add complexity and additional conditions  
+# 4. Tune parameters based on visual inspection of results
+# 5. Validate against manual scoring or established protocols
+# 6. Document final parameter choices and biological rationale
+
+# PERFORMANCE OPTIMIZATION:
+# -------------------------
+# • Place most selective conditions first in 'all' blocks
+# • Use 'any' sparingly as it requires evaluating multiple conditions
+# • Avoid deeply nested expressions when simple alternatives exist
+# • Cache commonly used mathematical expressions
+# • Consider computational cost of complex windowed operations
+
+# FILE ORGANIZATION:
+# ------------------
+# • Use descriptive behavior names that match your experimental design
+# • Keep related configurations in the same directory
+# • Document parameter choices and validation results
+# • Version control configuration files along with analysis code
+# • Share validated configurations with collaborators for reproducibility
\ No newline at end of file