Merge pull request #4 from mdiamantaki/main

update quickstart, configuration md files and cli.py

Author: mdiamantaki

docs/configuration.md

@@ -121,21 +121,21 @@ ethopy-analysis config-summary
 
 ## Usage Examples
 
-### Basic Usage (No Configuration)
+<!-- ### Basic Usage (No Configuration)
 ```python
 from ethopy_analysis.plots.animal import plot_animal_performance
 
 # Works with defaults
 plot_animal_performance(your_dataframe)
-```
+``` -->
 
-### With Database
+<!-- ### With Database
 ```python
 from ethopy_analysis.data.loaders import load_animal_data
 
 # Uses configured database
 animal_data = load_animal_data(animal_id=123)
-```
+``` -->
 
 ### Load Specific Config
 ```python

docs/quickstart.md

@@ -8,13 +8,14 @@ Get started with Ethopy Analysis in just a few steps.
 
 ```python
 from ethopy_analysis.data.loaders import get_sessions
+from ethopy_analysis.data.analysis import get_performance
 from ethopy_analysis.plots.animal import plot_session_performance
 
 # Load data from database
 sessions = get_sessions(animal_id=123, min_trials=20)
 
 # Create visualization
-fig, ax = plot_session_performance(123, sessions['session'].values)
+fig, ax = plot_session_performance(123, sessions['session'].values, perf_func=get_performance)
 ```
 
 ### 2. Command Line Interface
@@ -50,10 +51,10 @@ This notebook demonstrates comprehensive animal-level analysis including:
 sessions = get_sessions(animal_id, min_trials=20)
 
 # Plot session performance over time
-plot_session_performance(animal_id, sessions['session'].values)
+plot_session_performance(animal_id, sessions['session'].values, perf_func=get_performance)
 
 # Visualize liquid consumption
-plot_performance_liquid(animal_id, sessions)
+plot_performance_liquid(animal_id, sessions, xaxis='session')
 
 # Check session dates
 plot_session_date(animal_id, min_trials=1)
@@ -93,6 +94,51 @@ plot_valid_proximity_state(animal_id, session, state="Trial")
 plot_trial_time(animal_id, session, trials=[10, 11])
 ```
 
+### Data loading Example
+**File**: `examples/load_example.ipynb`
+
+This notebook demonstrates all the data loading functions available in the ethopy_analysis package including:
+
+- **Configuration and Setup Functions**: Load configuration and database setup
+- **Database Schema Functions**: Access the DataJoint database schemas
+- **Session-Level Data Loading**: Load session-level information and metadata
+- **Trial-Level Data Loading**: Load detailed trial-level data for analysis
+- **Behavioral Event Data Loading**: Load specific behavioral events like licks and proximity sensor data
+- **Analysis and Performance Functions**: Compute performance metrics and provide session analysis
+- **Complete Data Loading Example**: Load all available data for a comprehensive analysis
+- **Data Format Options**: Support both DataFrame and DataJoint formats for flexibility
+- **Error Handling and Edge Cases**: How functions handle common edge cases
+
+**Key functions demonstrated**:
+```python
+# Load configuration from file
+config = load_config(display_path=True)
+print("Configuration loaded:")
+
+# Retrieve animal_id and session for a given setup
+animal_id, session = get_setup("ef-rp13") ## "ef-rp13" is the name of the setup
+print(f"Setup 'ef-rp13' current animal_id: {animal_id}, session: {session}")
+
+# Filter sessions by date range
+sessions_filtered = get_sessions(animal_id, from_date="2025-01-01", to_date="2025-12-31")
+print(f"Sessions for animal {animal_id} in 2025:")
+print(sessions_filtered.head())
+
+# Remove aborted trials from the dataset
+trials_no_abort = get_trials(animal_id, session, remove_abort=True)
+print(f"Trials without aborts: {len(trials_no_abort)} (vs {len(trials)} with aborts)")
+
+# Retrieve all licks of a session
+trial_licks = get_trial_licks(animal_id, session)
+print(f"Total lick events for animal {animal_id}, session {session}:: {len(trial_licks)}")
+print(f"Licks per port: {trial_licks['port'].value_counts()}")
+
+# Print comprehensive summary of a session
+print(f"Comprehensive session summary for animal {animal_id}, session {session}:")
+print("=" * 60)
+session_summary(animal_id, session)
+```
+
 ## Running the Examples
 
 1. **Start Jupyter**:
@@ -103,11 +149,14 @@ plot_trial_time(animal_id, session, trials=[10, 11])
 2. **Open a notebook**:
    - `animal_analysis_example.ipynb` for animal-level analysis
    - `session_analysis_example.ipynb` for session-level analysis
+   - `load_example.ipynb` for data loading analysis
 
 3. **Configure your data**:
    - Update `animal_id` variables to match your data
    - Ensure database connection is configured (see [Configuration](configuration.md))
 
+4. **Run the cells** to see analysis results
+
 ## Configuration
 
 Before running database-dependent examples:

src/ethopy_analysis/cli.py

@@ -5,6 +5,7 @@
 import click
 import sys
 import os
+from datetime import datetime
 
 from .plots.animal import (
     plot_session_date,
@@ -146,11 +147,20 @@ def generate_report(animal_id: int, output_dir: str):
         with open(report_file, "w") as f:
             f.write("ETHOPY ANALYSIS REPORT\n")
             f.write(f"Animal ID: {animal_id}\n")
-            f.write("Generated: {}\n".format(click.DateTime().now()))
+            f.write("Generated: {}\n".format(datetime.now())) 
             f.write("=" * 50 + "\n\n")
 
             f.write("SESSION SUMMARY\n")
             f.write(f"Total sessions: {len(sessions)}\n")
+            if get_performance(animal_id, session_row['session']) is None:
+                f.write(
+                    f"  Performance: no behavior in this session\n"
+                )
+            else:    
+                f.write(
+                    f"  Performance: {get_performance(animal_id, session_row['session']):.3f}\n"
+                )
+
             f.write(
                 f"Session range: {sessions['session'].min()} - {sessions['session'].max()}\n\n"
             )