add Creating Custom Components in docs

Author: alexevag

docs/creating_custom_components.md

@@ -0,0 +1,88 @@
+# Creating Custom Components in Ethopy
+
+This guide provides an introduction to extending Ethopy with your own custom components. Ethopy's modular design allows you to create specialized experiments by implementing three core component types:
+
+1. **Experiments**: Define the overall experimental flow and state transitions
+2. **Stimuli**: Create visual, auditory, or other sensory presentations
+3. **Behaviors**: Handle animal interactions and responses
+
+## Core Architecture
+
+Ethopy uses a modular architecture where each component has specific responsibilities:
+
+
+- **Experiments** manage the overall flow of your task using a state machine
+- **Stimuli** control what is presented to the subject
+- **Behaviors** track and validate responses
+- **Interfaces** communicate with hardware
+- **Loggers** record data to the database
+
+All components integrate with the DataJoint database system to store parameters and results.
+
+## Example Components
+
+We provide three detailed examples to help you understand how to create your own components:
+
+### 1. [Match Port Experiment](match_port_example.md)
+
+The Match Port experiment implements a 2-Alternative Forced Choice (2AFC) task where animals need to choose the correct port based on stimuli. This example demonstrates:
+
+- Creating a complex state machine with multiple states
+- Implementing state transitions based on animal behavior
+- Managing adaptive difficulty through staircase methods
+- Handling reward, punishment, and intertrial periods
+
+### 2. [Dot Stimulus](dot_stimulus_example.md)
+
+The Dot stimulus provides a simple visual element that can be displayed at different positions and sizes. This example shows:
+
+- Defining stimulus parameters in a DataJoint table
+- Calculating screen positions based on monitor resolution
+- Managing the lifecycle of visual elements
+- Implementing timing-based presentation
+
+### 3. [MultiPort Behavior](multi_port_behavior_example.md)
+
+The MultiPort behavior handles interactions with multiple response ports. This example illustrates:
+
+- Tracking which ports an animal interacts with
+- Validating responses based on experimental conditions
+- Managing reward delivery at specific ports
+- Recording response history and outcomes
+
+## Component Integration
+
+These three component types work together to create a complete experimental setup:
+
+1. The **Experiment** defines the sequence of states (e.g., ready → trial → reward)
+2. The **Stimulus** determines what the animal sees or hears in each state
+3. The **Behavior** handler tracks and validates the animal's responses
+
+For example, in a typical trial:
+- The experiment enters the "Trial" state
+- The stimulus presents a visual cue
+- The behavior handler detects when the animal responds
+- The experiment transitions to "Reward" or "Punish" based on the response
+- The cycle continues to the next trial
+
+## Creating Your Own Components
+
+To create your own custom components:
+
+1. **Start with the examples**: Use the provided examples as templates
+2. **Understand the lifecycle**: Each component type has specific initialization, operation, and cleanup methods
+3. **Define database tables**: Create appropriate DataJoint tables for your parameters
+4. **Implement required methods**: Each component type has essential methods that must be implemented
+5. **Test incrementally**: Start with simple implementations and add complexity gradually
+
+The detailed documentation for each example provides step-by-step guidance for implementing your own versions.
+
+## Next Steps
+
+Explore each example in detail:
+
+- [Experiment](match_port_example.md) for state machine implementation
+- [Stimulus](dot_stimulus_example.md) for visual stimulus creation
+- [Behavior](multi_port_behavior_example.md) for response handling
+
+These examples provide a foundation for understanding how to extend Ethopy with custom components tailored to your specific experimental needs.

docs/dot_stimulus_example.md

@@ -0,0 +1,174 @@
+# Creating a Custom Stimulus: Dot Example
+
+This guide explains how to create a custom stimulus in Ethopy by examining the `dot.py` example, which implements a simple dot stimulus for visual experiments.
+
+## Overview of the Dot Stimulus
+
+The Dot stimulus displays a configurable dot (rectangular or oval) on the screen at specified coordinates and sizes. This type of stimulus is commonly used in:
+
+- Visual attention studies
+- Simple detection tasks
+- Eye movement tracking experiments
+- Timing response experiments
+
+## Defining the Stimulus Database Table
+
+Each stimulus requires defining a database table to store its parameters. Here's how the Dot stimulus defines its table:
+
+```python
+@stimulus.schema
+class Dot(Stimulus, dj.Manual):
+    definition = """
+    # This class handles the presentation of area mapping Bar stimulus
+    -> stimulus.StimCondition
+    ---
+    bg_level              : tinyblob  # 0-255 baground color
+    dot_level             : tinyblob  # 0-255 dot color
+    dot_x                 : float  # (fraction of monitor width, 0 for center, from -0.5 to 0.5) position of dot on x axis
+    dot_y                 : float  # (fraction of monitor width, 0 for center) position of dot on y axis
+    dot_xsize             : float  # fraction of monitor width, width of dots
+    dot_ysize             : float # fraction of monitor width, height of dots
+    dot_shape             : enum('rect','oval') # shape of the dot
+    dot_time              : float # (sec) time of each dot persists
+    """
+```
+
+This table definition:
+- Uses the `@stimulus.schema` decorator to associate with the database
+- Inherits from both `Stimulus` (base class) and `dj.Manual` (DataJoint table class)
+- Defines a foreign key relationship with `stimulus.StimCondition` (parent table)
+- Specifies parameters for the dot's appearance:
+  - Background and dot colors
+  - Position (x, y coordinates as fractions of screen width)
+  - Size (width and height as fractions of screen width)
+  - Shape (rectangular or oval)
+  - Duration (how long the dot persists)
+
+## Implementing the Stimulus Class
+
+The Dot class implements several key methods to control the stimulus lifecycle:
+
+```python
+def __init__(self):
+    super().__init__()
+    self.cond_tables = ['Dot']
+    self.required_fields = ['dot_x', 'dot_y', 'dot_xsize', 'dot_ysize', 'dot_time']
+    self.default_key = {'bg_level': 1,
+                        'dot_level': 0,  # degrees
+                        'dot_shape': 'rect'}
+```
+
+### 1. `__init__()` method
+
+This initializes the stimulus and defines:
+
+- `self.cond_tables`: List of condition tables this stimulus uses (just 'Dot' in this case)
+- `self.required_fields`: Parameters that must be provided for this stimulus
+- `self.default_key`: Default values for optional parameters
+
+### 2. `prepare()` method
+
+```python
+def prepare(self, curr_cond):
+    self.curr_cond = curr_cond
+    self.fill_colors.background = self.curr_cond['bg_level']
+    self.Presenter.set_background_color(self.curr_cond['bg_level'])
+    width = self.monitor.resolution_x
+    height = self.monitor.resolution_y
+    x_start = self.curr_cond['dot_x'] * 2
+    y_start = self.curr_cond['dot_y'] * 2 * width/height
+    self.rect = (x_start - self.curr_cond['dot_xsize'],
+                 y_start - self.curr_cond['dot_ysize']*width/height,
+                 x_start + self.curr_cond['dot_xsize'],
+                 y_start + self.curr_cond['dot_ysize']*width/height)
+```
+
+This method:
+1. Stores the current condition parameters
+2. Sets the background color
+3. Calculates the dot's position and size based on:
+   - Monitor resolution (to maintain aspect ratio)
+   - Condition parameters for position and size
+   - Conversion from normalized coordinates to actual screen coordinates
+4. Creates a rectangle tuple (left, top, right, bottom) for drawing
+
+### 3. `start()` method
+
+```python
+def start(self):
+    super().start()
+    self.Presenter.draw_rect(self.rect, self.curr_cond['dot_level'])
+```
+
+This method:
+1. Calls the parent class's start method (which initializes timing)
+2. Draws the rectangle using the precalculated coordinates and the specified color
+
+### 4. `present()` method
+
+```python
+def present(self):
+    if self.timer.elapsed_time() > self.curr_cond['dot_time']*1000:
+        self.in_operation = False
+        self.Presenter.fill(self.fill_colors.background)
+```
+
+This method:
+1. Checks if the dot's display time has elapsed (converting seconds to milliseconds)
+2. If the time has elapsed:
+   - Marks the stimulus as no longer in operation
+   - Fills the screen with the background color (removing the dot)
+
+### 5. `stop()` and `exit()` methods
+
+```python
+def stop(self):
+    self.log_stop()
+    self.Presenter.fill(self.fill_colors.background)
+    self.in_operation = False
+
+def exit(self):
+    self.Presenter.fill(self.fill_colors.background)
+    super().exit()
+```
+
+These methods handle cleanup:
+- `stop()`: Called when the stimulus needs to be stopped during operation
+  - Logs the stop event
+  - Clears the screen
+  - Marks the stimulus as no longer in operation
+
+- `exit()`: Called when the experiment is ending
+  - Clears the screen
+  - Calls the parent class's exit method for additional cleanup
+
+## Stimulus Lifecycle
+
+The dot stimulus follows this lifecycle:
+
+1. **Initialization**: Set up parameters and default values
+2. **Preparation**: Calculate positioning based on current conditions
+3. **Start**: Draw the dot on the screen
+4. **Present**: Monitor timing and remove the dot when its time expires
+5. **Stop/Exit**: Clean up resources and reset the display
+
+## How to Create Your Own Stimulus
+
+To create your own stimulus:
+
+1. **Define a database table** with appropriate parameters for your stimulus
+2. **Create a stimulus class** that inherits from the base `Stimulus` class
+3. **Specify required fields and defaults** in the `__init__` method
+4. **Implement preparation logic** to set up your stimulus based on conditions
+5. **Create presentation methods** that control how the stimulus appears:
+   - `start()`: Initial display
+   - `present()`: Continuous updates (if needed)
+   - `stop()` and `exit()`: Cleanup
+
+Your stimulus should handle:
+- **Positioning** on the screen (considering aspect ratio)
+- **Timing** of presentation
+- **Transitions** stimulus conditions between states
+- **Cleanup** to ensure the display returns to a neutral state
+
+By following this pattern, you can create diverse visual stimuli for behavioral experiments, from simple dots and shapes to complex moving patterns or interactive elements.