Merge pull request #1 from athpapoutsi/fixes

Fixes on the documentation

Author: alexevag

docs/creating_custom_components.md

@@ -1,19 +1,12 @@
 # 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:
+This guide provides an introduction to extending Ethopy with 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
+2. **Stimuli**: Create and control visual, auditory, or other sensory presentations 
+3. **Behaviors**: Handle and track 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
+In addition, the following two core modules can be implemented
 - **Interfaces** communicate with hardware
 - **Loggers** record data to the database
 
@@ -27,7 +20,7 @@ We provide three detailed examples to help you understand how to create your own
 
 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
+- Creating a state machine with multiple states
 - Implementing state transitions based on animal behavior
 - Managing adaptive difficulty through staircase methods
 - Handling reward, punishment, and intertrial periods
@@ -55,7 +48,7 @@ The MultiPort behavior handles interactions with multiple response ports. This e
 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
+2. The **Stimulus** determines what the stimulus the animal experiences in each state
 3. The **Behavior** handler tracks and validates the animal's responses
 
 For example, in a typical trial:

docs/dot_stimulus_example.md

@@ -84,13 +84,12 @@ def prepare(self, curr_cond):
 ```
 
 This method:
-1. Stores the current condition parameters
-2. Sets the background color
-3. Calculates the dot's position and size based on:
+1. Sets the background color
+2. 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. Creates a rectangle tuple (left, top, right, bottom) for drawing
 
 ### 3. `start()` method
 

docs/getting_started.md

@@ -80,11 +80,11 @@ EthoPy relies on a MariaDB database for experiment configuration and data loggin
    ```bash
    ethopy-setup-djdocker
    ```
-   alterative follow the instruction from datajoint [here](https://github.com/datajoint/mysql-docker)
+   Alteratively follow the instructions from datajoint [here](https://github.com/datajoint/mysql-docker)
 
    The default username is "root".
 
-> **Note:** if ethopy-setup-djdocker not works try to setup the docker image based on the [datajoint instructions](https://github.com/datajoint/mysql-docker)
+> **Note:** if ethopy-setup-djdocker does not work try to setup the docker image based on the [datajoint instructions](https://github.com/datajoint/mysql-docker)
 
 
 > **Note:** By default, Docker requires sudo because the Docker daemon runs as root.
@@ -109,7 +109,7 @@ This command adds your user to the docker group, so you can run Docker commands
 
 === "Windows"
     `%USERPROFILE%\.ethopy\local_conf.json`
-   dj_local_conf have all the parameters refers to [datajoint configuration](https://datajoint.com/docs/elements/element-miniscope/0.2/tutorials/01-Configure/):
+   dj_local_conf includes the parameters relevant to the [datajoint configuration](https://datajoint.com/docs/elements/element-miniscope/0.2/tutorials/01-Configure/):
    ```json
    {
        "dj_local_conf": {

docs/index.md

@@ -17,8 +17,8 @@ Ethopy is a state control system for automated, high-throughput behavioral train
 
 - **Modular Design**: Comprised of several overridable modules that define the structure of experiments, stimuli, and behavioral control
 - **Database Integration**: Automatic storage and management of experimental data using Datajoint
-- **Multiple Experiment Types**: Support for various experiment paradigms (match to sample, 2AFC, open field, etc.)
-- **Hardware Integration**: Interfaces with multiple hardware setups (raspberry, arduino, desktop computer, screen, camera etc.)
+- **Multiple Experiment Types**: Support for various experiment paradigms (Go-NoGo, 2AFC, open field, etc.)
+- **Hardware Integration**: Interfaces with multiple hardwares (raspberry, arduino, desktop computer, screen, camera etc.)
 - **Stimulus Control**: Various stimulus types supported (Gratings, Movies, Olfactory, 3D Objects)
 - **Real-time Control**: State-based experiment control with precise timing
 - **Extensible**: Easy to add new experiment types, stimuli, or behavioral interfaces
@@ -34,29 +34,20 @@ The following diagram illustrates the relationship between the core modules:
 --- 
 ## Installation & Setup
 
+For a step-by-step guide of installation procedure see [here](getting_started.md)
+
 ### Requirements
 
 - Python 3.8 or higher
-- Maria DB Database (instructions for [database setup](database.md))
+- Maria DB Database (instructions for [database setup](database_setup.md))
 
 
 ### Basic Installation
 
 ```bash
 pip install ethopy
 ```
-
-For optional features:
-```bash
-# For 3D object support
-pip install "ethopy[obj]"
-
-# For development
-pip install "ethopy[dev]"
-
-# For documentation
-pip install "ethopy[docs]"
-```
+For more detailed instructions follow the [Installation](installation.md)
 
 ### Running Experiments
 
@@ -76,7 +67,7 @@ ethopy --task-idx 1
 
 ## Core Architecture
 
-Understanding Ethopy's core architecture is essential for both using the system effectively and extending it for your needs. Ethopy is built around four core modules that work together to provide a flexible and extensible experimental framework. Each module handles a specific aspect of the experiment, from controlling the overall flow to managing stimuli and recording behavior.
+Understanding Ethopy's core architecture is essential for both using the system effectively and extending it for your needs. Ethopy is built around five core modules that work together to provide a flexible and extensible experimental framework. Each module handles a specific aspect of the experiment, from controlling the overall flow to managing stimuli and recording behavior.
 
 ### 1. Experiment Module
 
@@ -95,14 +86,7 @@ Each state has four overridable functions that control its behavior:
 - **FreeWater**: Water delivery experiments
 - **Calibrate**: Port calibration for water delivery
 
-#### Configuration
-
-Experiments require setup configuration through:
-- `SetupConfiguration`
-- `SetupConfiguration.Port`
-- `SetupConfiguration.Screen`
-
-Experiment parameters are defined in Python configuration files and stored in the `Task` table within the `lab_experiment` schema.
+Experiment parameters are defined in Python configuration files and stored in the `Task` table within the `lab_experiments` schema.
 
 ### 2. Behavior Module
 
@@ -125,8 +109,18 @@ Controls stimulus presentation and management.
   - Bar: Moving bars for retinotopic mapping
   - Dot: Moving dots
 
+### 4. Interface Module (Non-overridable)
+Manages hardware communication and control.
+
+#### Configuration
+
+Experiments require setup configuration through:
+- `SetupConfiguration`
+- `SetupConfiguration.Port`
+- `SetupConfiguration.Screen`
+Configuration files are stored within the `lab_interface` schema.
 
-#### Logger Module (Non-overridable)
+### 5. Logger Module (Non-overridable)
 Manages all database interactions across modules. Data is stored in three schemas:
 
 **lab_experiments**:  
@@ -138,51 +132,15 @@ Manages all database interactions across modules. Data is stored in three schema
 **lab_stimuli**:  
 <img src="http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/ef-lab/EthoPy/master/utils/plantuml/stimuli.iuml">
 
-#### Interface Module (Non-overridable)
-Manages hardware communication and control.
 
 ## Development & Contributing
+Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. Please follow thse [instructions] (https://github.com/ef-lab/ethopy_package/blob/main/docs/contributing.md) for contributions.
 
-### Development Setup
-
-1. Clone the repository:
-```bash
-git clone https://github.com/ef-lab/ethopy_package/  # Main repository
-cd ethopy
-```
-
-2. Install development dependencies:
-```bash
-pip install -e ".[dev,docs]"
-```
-
-### Code Quality
-
-The project uses several tools to maintain code quality:
-
-- **ruff**: Code formatting and linting
-- **isort**: Import sorting
-- **pytest**: Testing and test coverage
-
-Run tests:
-```bash
-pytest tests/
-```
-
-### Documentation
-
-Documentation is built using MkDocs. Install documentation dependencies and serve locally:
-
-```bash
-pip install ".[docs]"
-mkdocs serve
-```
-
-### License
+## License
 
 This project is licensed under the MIT License - see the [LICENSE](https://github.com/ef-lab/ethopy_package/blob/master/LICENSE) file for details.
 
-### Support
+## Support
 
 For questions and support:
 

docs/local_conf.md

@@ -12,7 +12,6 @@ EthoPy automatically looks for a file called `local_conf.json` in a special fold
 
 ## Quick Start Guide
 
-### Step 1: Basic Setup
 When you first start EthoPy, you'll need to create a configuration file. Here's a simple example to get you started:
 
 ```json
@@ -28,7 +27,7 @@ When you first start EthoPy, you'll need to create a configuration file. Here's
 }
 ```
 
-### Step 2: What Each Part Means
+What Each Part Means
 - **database settings**: How to connect to your MySQL database
 - **source_path**: Where your experimental data is stored
 - **target_path**: Where backup copies should be saved
@@ -40,30 +39,38 @@ Here's what a full configuration file looks like with all the optional settings:
 ```json
 {
     "dj_local_conf": {
-        "database.host": "127.0.0.1",
-        "database.user": "root",
-        "database.password": "your_password",
-        "database.port": 3306
+        "database.host": "YOUR DATABASE",
+        "database.user": "USERNAME",
+        "database.password": "PASSWORD",
+        "database.port": "PORT",
+        "database.reconnect": true,
+        "database.enable_python_native_blobs": true
     },
-    "source_path": "/path/to/data",
-    "target_path": "/path/to/backup",
     "logging": {
         "level": "INFO",
         "directory": "~/.ethopy/",
         "filename": "ethopy.log"
     },
+    "SCHEMATA": {
+        "experiment": "Experiment_Name",   
+        "behavior": "Behavior_Name", 
+        "stimulus": "Stimulus_Name",
+        "interface": "Interface_Name",  
+        "recording": "Recording_Name",      
+    },
     "channels": {
-        "Liquid": {"1": 22, "2": 23},
-        "Lick": {"1": 17, "2": 27}
-    }
+        "Signal": {"PORT1": "GPIO_pin", "PORT2": "GPIO"},
+    },
+    "source_path": "LOCAL_RECORDINGS_DIRECTORY",
+    "target_path": "TARGET_RECORDINGS_DIRECTORY",
 }
 ```
 
 ## Understanding Each Section
 
 ### 1. Database Settings (`dj_local_conf`)
 
-This section tells EthoPy how to connect to your MySQL database:
+This section instructs EthoPy to connect to your MySQL database. Below we analyze an indicative example:
 
 ```json
 {
@@ -82,7 +89,7 @@ This section tells EthoPy how to connect to your MySQL database:
 
 ### 2. File Paths
 
-These tell EthoPy where to find and save your data:
+These instruct EthoPy where to find and save your data:
 
 ```json
 {
@@ -107,9 +114,9 @@ This controls how EthoPy saves information about what it's doing:
 }
 ```
 
-### 4. Schema Names
+### 4. Schema Names (Optional)
 
-If your database uses custom names for different parts of your experiment data:
+If your database uses custom names for different parts of your experiment data, e.g.:
 
 ```json
 {
@@ -127,13 +134,12 @@ If your database uses custom names for different parts of your experiment data:
 
 **Skip this section if you're not using physical hardware like valves, sensors, or LEDs.**
 
-If you're running experiments with physical hardware (like water valevs, lick detectors, or LEDs), you need to tell EthoPy which pins on your Raspberry Pi connect to which devices.
+If you're running experiments with physical hardware (like water valves, lick detectors, or LEDs) connected to a Rasberry Pi, you need to instruct EthoPy which GPIO pins on your Raspberry Pi connect to which devices.
 
 ```json
 {
     "channels": {
-        "Liquid": {"1": 22, "2": 23},    // Water valve connections
-        "Lick": {"1": 17, "2": 27},      // Lick sensor connections
+        "Signal": {"PORT1": "GPIO_pin", "PORT2": "GPIO_pin"},    
     }
 }
 ```
@@ -205,12 +211,12 @@ Your database is on a different computer in the lab:
 ```json
 {
     "dj_local_conf": {
-        "database.host": "192.168.1.100",
+        "database.host": "database_ip",   // Database server address (make sure your db has fix ip)
         "database.user": "lab_user",
         "database.password": "lab_password",
         "database.port": 3306
     },
-    "source_path": "/Users/yourname/experiment_data",
+    "source_path": "/Users/yourname/experiment_data",   
     "target_path": "/Users/yourname/experiment_backup"
 }
 ```
@@ -272,7 +278,7 @@ You're running behavioral experiments with physical hardware:
 
 ### Problem: "Hardware not responding"
 
-**Symptoms:** Your pumps, sensors, or LEDs aren't working
+**Symptoms:** Your valves, sensors, or LEDs aren't working
 
 **Solutions to try:**
 1. **Check physical connections** - Make sure all wires are properly connected

docs/match_port_example.md

@@ -38,7 +38,7 @@ The StateMachine in Ethopy automatically finds all state classes that inherit fr
 
 ## Overview of the Match Port Experiment
 
-The Match Port experiment challenges animals to correctly choose between ports based on stimuli. 
+The Match Port experiment requires animals to correctly choose between ports based on stimuli. 
 
 It implements:
 - Adaptive difficulty using staircase methods
@@ -139,7 +139,6 @@ Each state is implemented as a class inheriting from the base `Experiment` class
 ```python
 class Trial(Experiment):
     def entry(self):
-        self.resp_ready = False
         super().entry()
         self.stim.start()
 
@@ -179,16 +178,15 @@ Let's break down the Trial state's functionality in detail:
 
 ```python
 def entry(self):
-    self.resp_ready = False
     super().entry()
     self.stim.start()
 ```
 
-- `self.resp_ready = False`: Resets the response readiness flag at the beginning of each trial
 - `super().entry()`: Calls the parent class's entry method which:
   - Records the current state in the logger
   - Logs a state transition event with timestamp
   - Starts the state timer
+  - Resets the response readiness flag at the beginning of each Trial
 - `self.stim.start()`: Initializes the stimulus for the current trial, activating any hardware or software components needed
 
 ### 2. `run()` method
@@ -282,7 +280,7 @@ def exit(self):
 
 ## State Machine Flow
 
-The experiment implements a state machine that flows through these main states:
+The MatchPort experiment implements a state machine that flows through these main states:
 
 1. `Entry` → Initial setup
 2. `PreTrial` → Prepare stimulus and wait for animal readiness