Astro Session Analyser - Ekos Edition

Astrophotography session analyzer specialized for Ekos/KStars. This application analyzes .analyze files generated by Ekos and sends comprehensive summaries with temporal plots to Discord.

🌟 Features

Core Features

Native Ekos Analysis: Directly parses KStars/Ekos .analyze files
Temporal Plotting: HFR, guiding error, and temperature evolution graphs
Advanced Analytics: Statistical analysis with numpy/scipy (optional)
3 Report Levels: minimal, standard, detailed - from quick notifications to comprehensive analysis
Discord Integration: Rich summaries with emojis and organized statistics
Dry-Run Mode: Safe testing without sending to Discord

Advanced Features

Multi-Filter Analysis: Performance breakdown by filter with sub-session details
Guiding Analytics: Comprehensive guiding performance analysis by filter
Quality Metrics: HFR, FWHM, star detection, and seeing conditions
Temperature Correlation: Statistical analysis of temperature effects on imaging quality
Intelligent Message Splitting: Automatic Discord message fragmentation for large sessions
Alert System: Automatic detection of performance issues and recommendations

📊 Report Levels

📱 MINIMAL - Quick Notifications

**🔭 Session Summary (Minimal)**
📸 **31 captures completed**
⏰ Duration: 5h 55m

🌤️ **Session Conditions**
🌡️ Temperature Stability: Variable (Δ5.1°C)
🔭 Mount Tracking: Good (28 events)

🎯 **Autofocus Summary**
🔄 Sessions: 9
📈 Focus Stability: Frequent adjustments

🚨 **4 Critical Issues**
• 4 aborted captures detected

📊 STANDARD - Daily Usage (Default)

**🔭 Ekos Session Summary**
📅 2024-01-15 18:12 UTC

🌙 **Session Overview**
📸 Total Captures: 31
⏰ Duration: 11:41 → 17:37 (5h 55m)
🌡️ Temperature: 15.8°C → 20.9°C (avg 17.0°C)
🎯 Objects: 1 | 🔍 Filters: 3 (H, O, S)

🌤️ **Session Conditions**
🌡️ Temperature Stability: Variable (Δ5.1°C)
🔭 Mount Tracking: Good (28 events)

🌟 **Guiding Performance**
📊 Measurements: 1,247
🎯 Avg Error: 0.92″
🟡 Guide Quality: Good
📈 RA: 0.78″ | DEC: 0.61″

📊 **Capture Details**

🎯 **NGC 7380**
📌 H Filter (11×600s, 1h 50m)
   🔧 HFR: 3.60 → 5.62 (avg 4.64, σ 0.66)
   📐 FWHM: 8.46 → 13.21 (avg 10.90, σ 1.55)
   ⭐ Stars: 249 → 250 (avg 250, consistency 1.00)
   📈 Guide: 0.89″ 🟡Good

🎯 **Autofocus Summary**
🔄 Sessions: 9
🌡️ Average Temperature: 17.1°C
📈 Focus Stability: Frequent adjustments

⚠️ **Issues & Alerts**
❌ Aborted Captures: 4

🔬 DETAILED - Data Analysis Mode

**🔭 Session Overview (1/3)**
📅 2024-01-15 18:12 UTC

🌙 **Session Overview**
📸 Total Captures: 31
⏰ Duration: 11:41 → 17:37 (5h 55m)
🌡️ Temperature: 15.8°C → 20.9°C (avg 17.0°C) (Stability: 60%)
🎯 Objects: 1 | 🔍 Filters: 3 (H, O, S)

🌤️ **Session Conditions**
🌡️ Temperature Stability: Variable (Δ5.1°C)
🔭 Mount Tracking: Good (28 events)

🌟 **Guiding Performance**
📊 Measurements: 1,247
🎯 Avg Error: 0.92″
🟡 Guide Quality: Good
📈 RA: 0.78″ | DEC: 0.61″

📊 **Image Quality Analysis**
🔧 HFR: 1.96 → 5.62 (avg 3.06)
👁️ Seeing Conditions: Average
📈 HFR Stability: 0.215 (lower is better)

**📊 Performance Analysis (2/3)**

🎯 **Filter Performance Summary**

📌 **H**: 11×600s (1.8h) - 🔧 4.64 | 📈 0.89″ 🟡
📌 **O**: 13×600s (2.2h) - 🔧 2.83 | 📈 0.95″ 🟡  
📌 **S**: 7×600s (1.2h) - 🔧 2.41 | 📈 0.91″ 🟡

**🔬 Detailed Sub-Sessions (3/3)**

🎯 **NGC 7380**
📌 H Filter (11×600s, 1h 50m)
📋 Sub-sessions: 2
     #1: 22:46→23:57 (1h 10m) | 7×600s
          📈 Guide: 0.94″ 🟡Good
          🔧 HFR: 4.12 → 5.62 (avg 4.89)
          📐 FWHM: 4.94 → 6.74 (avg 5.87)
         ⭐ Stars: 249 → 250 (avg 250, consistency 1.00)
     #2: 00:15→00:55 (40m) | 4×600s
          📈 Guide: 0.81″ 🟡Good
          🔧 HFR: 3.60 → 4.98 (avg 4.22)
          📐 FWHM: 4.32 → 5.98 (avg 5.06)
         ⭐ Stars: 249 → 250 (avg 250, consistency 1.00)

🌡️ **Temperature Analysis**
📊 Thermal Stability: 60% (Range: 5.1°C)
📈 Temp-HFR Correlation: -0.234 (significant)

🎯 **Autofocus Analysis**
🔄 Sessions: 9
🔍 **By Filter:**
   • H: 3 sessions (avg temp 16.8°C)
   • O: 4 sessions (avg temp 17.2°C)
   • S: 2 sessions (avg temp 17.5°C)
⏱️ Avg Interval: 45 minutes

📋 Requirements

Python 3.7+
KStars/Ekos configured to generate analyze files
Discord webhook configured
For DETAILED level: NumPy/SciPy for advanced analytics
For plotting: matplotlib (optional)

🚀 Installation

Clone the repository

git clone https://github.com/grm/astro-session-analyser
cd astro-session-analyser

Install dependencies

# Basic installation (minimal & standard levels)
pipenv install

# For detailed level with advanced analytics
pipenv install numpy scipy

# For temporal plots (optional)
pipenv install matplotlib

Configure the application

# Copy example configuration
cp config_example.yml config.yml

# Edit config.yml with your settings

⚙️ Configuration

Basic Configuration

Edit the config.yml file:

# Discord webhook URL (required)
webhook: "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"

# Time window in hours to analyze sessions
hours: 24

# Path to Ekos analyze files (optional)
# Default: ~/.local/share/kstars/analyze
analyze_dir: "/home/username/.local/share/kstars/analyze"

# Report level: minimal, standard, detailed
discord_report_level: "standard"

# Enable temporal plotting (optional)
plotting:
  enabled: true

# Log level (optional)
log_level: "INFO"

Advanced Options (Optional)

# Advanced analytics (auto-enabled for detailed level)
advanced_analytics:
  enabled: false  # Set to true to force enable for standard level

# Alert thresholds (optional customization)
alert_thresholds:
  hfr_drift_warning: 0.5        # pixels
  temperature_swing_warning: 5.0 # °C
  success_rate_warning: 0.8     # 80%

# Notification preferences
notifications:
  performance_alerts: true
  min_captures_for_report: 1

🔧 Usage

Development and Testing

# Safe testing with dry-run (RECOMMENDED)
pipenv run python nightly_summary.py -c config.yml --dry-run

# Verbose mode for debugging
pipenv run python nightly_summary.py -c config.yml --dry-run --verbose

Production Use

# Send summary to Discord
pipenv run python nightly_summary.py -c config.yml

# With verbose output
pipenv run python nightly_summary.py -c config.yml --verbose

Automation

Add to your crontab for daily summary at 8 AM:

0 8 * * * cd /path/to/astro-session-analyser && pipenv run python nightly_summary.py -c config.yml

📊 Example Output

Discord Message with Temporal Plot

Here's an example of what gets sent to Discord, including both the comprehensive text summary and temporal visualization:

Example Discord Message:

🔭 Ekos Session Summary
📅 2025-09-04 07:49 UTC

🌙 Session Overview
📸 Total Captures: 7
⏰ Duration: 07:00 → 08:38 (1h 38m)
🎯 Objects: 1 | 🔍 Filters: 3 (H, O, S)

🌟 Guiding Performance
📊 Measurements: 22
🎯 Avg Error: 1.21″
🟡 Guide Quality: Good
📈 RA: 0.95″ | DEC: 0.74″

📊 Capture Details

🎯 NGC 7380
📌 H Filter (4×600s, 58m)
   🔧 HFR: 2.75 → 4.10 (avg 3.42, σ 0.67)
   📐 FWHM: 6.46 → 9.63 (avg 8.05, σ 1.59)
   ⭐ Stars: 244 → 250 (avg 247, consistency 0.99)
   📈 Guide: 1.19″ 🟡Good

📌 O Filter (2×600s, 20m)
   🔧 HFR: 2.25 → 2.25 (avg 2.25, σ 0.00)
   📐 FWHM: 5.29 → 5.29 (avg 5.29, σ 0.00)
   ⭐ Stars: 247 → 248 (avg 248, consistency 1.00)
   📈 Guide: 1.24″ 🟡Good

🎯 Autofocus Summary
🔄 Sessions: 3
📈 Focus Stability: Good

⚠️ Issues & Alerts
❌ Aborted Captures: 4

The temporal plot shows:

🔧 HFR Evolution: Focus quality changes over time with autofocus events marked
📈 Guiding Performance: Mount tracking stability with quality zones
🌡️ Temperature Evolution: Environmental conditions during the session

🔍 Troubleshooting

No Data Found

Verify that KStars/Ekos generates .analyze files in ~/.local/share/kstars/analyze/
Check the analyze_dir path in configuration
Use --verbose to see detailed logs

Discord Webhook Error

Verify the webhook URL in config.yml
Test with --dry-run first to see formatted output

Advanced Analytics Issues

For DETAILED level, install: pipenv install numpy scipy
The system gracefully falls back to basic mode if dependencies are missing
Check console output for "advanced analytics" vs "basic analytics"

Plotting Issues

Install matplotlib: pipenv install matplotlib
Check plotting.enabled: true in configuration
Plots are saved to plots/ directory and attached to Discord messages

Parsing Issues

Check KStars/Ekos version (tested with 3.7.7+)
Enable verbose mode: --verbose
Use dry-run for safe testing: --dry-run

🎯 Use Cases

Quick Monitoring → MINIMAL Level

Essential notifications for automation
Critical alerts only
Perfect for mobile notifications and monitoring systems

Daily Usage → STANDARD Level (Default)

Comprehensive session summaries
All essential astrophotography metrics
Balanced information without complexity

Data Analysis → DETAILED Level

In-depth statistical analysis with sub-sessions
Quality and performance optimization insights
Scientific metrics with correlation analysis
Advanced troubleshooting information

🔬 Advanced Analytics (DETAILED Level)

Automatic Features

When you select discord_report_level: "detailed", the system automatically enables:

Sub-Session Analysis: Detailed breakdown of each imaging run by filter
Statistical Correlations: Temperature-HFR analysis with significance testing
Quality Scoring: Objective analysis of session quality and conditions
Performance Metrics: Success rates and filter-specific efficiency analysis
Trend Analysis: HFR stability and degradation detection
Intelligent Alerts: Automatic detection of issues with actionable recommendations

Dependencies

The detailed level requires scientific Python libraries:

pipenv install numpy scipy

🧪 Development

Safe Testing

Always use dry-run mode during development:

# Test without sending to Discord
pipenv run python nightly_summary.py -c config.yml --dry-run --verbose

Architecture

nightly_summary.py: CLI interface and orchestration
ekos_analyzer.py: Ekos .analyze file parser and data extraction
ekos_discord_formatter.py: Unified Discord message formatter for all levels
session_plotter.py: Temporal plot generation with matplotlib
advanced_metrics.py: Statistical calculations and quality analysis
utils.py: Configuration, logging, and Discord utilities

🤝 Contributing

Contributions are welcome! The project uses:

Python 3.7+ with Pipenv for dependency management
NumPy/SciPy for advanced analytics (optional)
matplotlib for temporal plotting (optional)
Clear separation between basic and advanced features with graceful degradation

📄 License

This project is under MIT license. See LICENSE file for details.

🙏 Acknowledgments

KStars/Ekos team for excellent astrophotography software
Discord community for feedback and suggestions
NumPy/SciPy communities for statistical computing tools

🚀 Latest Updates

Enhanced Multi-Filter Analysis: Comprehensive sub-session breakdown by filter
Improved Guiding Analytics: Real-time guiding performance analysis with quality assessment
Intelligent Message Splitting: Automatic Discord message fragmentation for large sessions
Temporal Plotting System: HFR, guiding, and temperature evolution graphs
Advanced Statistical Analysis: Temperature correlations and quality metrics
Better Error Handling: Graceful degradation and clear error messages
Unified Configuration: Single config file supporting all features and levels

Perfect for astrophotographers from beginners to data enthusiasts! 🔭✨