LFS-Ayats

Real-Time Analysis Module

Advanced analysis module for LFS-Ayats with anomaly detection, performance prediction, and sector analysis capabilities.

📋 Features

🔍 Anomaly Detection (anomaly.py)

📊 Performance Prediction (predictor.py)

📏 Sector Analysis (sectors.py)

🔄 Advanced Comparator (comparator.py)

🔔 Alert System (alerts.py)

📐 Metrics Calculation (metrics.py)

🚀 Installation

The module is included in LFS-Ayats. Make sure you have the dependencies installed:

pip install -r requirements.txt
pip install -e .

💡 Usage Examples

Example 1: Anomaly Detection

from src.analysis import AnomalyDetector

# Create detector
detector = AnomalyDetector()

# Check telemetry
current_data = {
    "engine_temp": 102.0,
    "linear_speed": 50.0,
    "wheel_speed": 60.0,
}

alerts = detector.check_telemetry(current_data)
for alert in alerts:
    print(alert)

Example 2: Lap Time Prediction

from src.analysis import PerformancePredictor

# Create predictor
predictor = PerformancePredictor()

# Historical data
historical_data = [
    {"sector_times": [28.5, 31.2, 25.8]},
    {"sector_times": [28.3, 31.5, 25.6]},
]

# Predict time with 2 completed sectors
predicted_time = predictor.predict_lap_time(
    current_sector_times=[28.2, 31.0],
    historical_data=historical_data
)

print(f"Predicted time: {predicted_time:.3f}s")

Example 3: Sector Analysis

from src.analysis import SectorAnalyzer

# Create analyzer
analyzer = SectorAnalyzer()

# Multiple laps data
session_data = [
    {"sector_times": [28.5, 31.2, 25.8]},
    {"sector_times": [28.3, 31.5, 25.6]},
    {"sector_times": [28.4, 31.8, 25.7]},
]

# Identify weak sectors
weak_sectors = analyzer.identify_weak_sectors(session_data)
for sector in weak_sectors:
    print(f"Sector {sector.number}: losing {sector.time_lost:.3f}s")

Example 4: Alert System

from src.analysis import AlertSystem, AlertLevel
from src.analysis.alerts import ConsoleAlertHandler

# Create system
system = AlertSystem()
system.register_handler(ConsoleAlertHandler())

# Generate alert
system.create_and_trigger(
    AlertLevel.WARNING,
    "High temperature",
    {"temp": 98.0}
)

# Check conditions
telemetry = {"engine_temp": 110.0, "fuel": 4.0}
alerts = system.check_conditions(telemetry)

Example 5: Lap Comparison

from src.analysis import AdvancedComparator

# Create comparator
comparator = AdvancedComparator()

# Lap data
lap1 = {
    "lap_id": 5,
    "total_time": 85.5,
    "sector_times": [28.5, 31.2, 25.8]
}

lap2 = {
    "lap_id": 8,
    "total_time": 85.2,
    "sector_times": [28.3, 31.5, 25.4]
}

# Compare
comparison = comparator.compare_laps(lap1, lap2)
print(f"Difference: {comparison.time_difference:+.3f}s")

for suggestion in comparison.suggestions:
    print(f"• {suggestion}")

Example 6: Performance Metrics

from src.analysis import MetricsCalculator

# Create calculator
calculator = MetricsCalculator()

# Lap times
lap_times = [86.5, 86.2, 85.9, 85.7, 85.5]
reference = 85.0

# Calculate metrics
consistency = calculator.calculate_consistency(lap_times)
pace_score = calculator.calculate_pace_score(lap_times, reference)
performance = calculator.calculate_performance_index(lap_times, reference)

print(f"Consistency: {consistency:.1%}")
print(f"Pace: {pace_score:.1f}/100")
print(f"Performance: {performance:.1f}/100")

📚 Running Complete Examples

cd /path/to/LFS-Ayats
PYTHONPATH=. python3 examples/analysis_examples.py

🧪 Tests

The module includes 69 unit tests with complete coverage:

# Run module tests
pytest tests/unit/analysis/ -v

# With coverage
pytest tests/unit/analysis/ --cov=src/analysis --cov-report=html

📖 API Documentation

Main Classes

AnomalyDetector

detector = AnomalyDetector(
    temp_warning=95.0,      # Warning temperature (°C)
    temp_critical=105.0,    # Critical temperature (°C)
    z_score_threshold=3.0   # Threshold for outlier detection
)

Main methods:

PerformancePredictor

predictor = PerformancePredictor()

Main methods:

SectorAnalyzer

analyzer = SectorAnalyzer()

Main methods:

AdvancedComparator

comparator = AdvancedComparator()

Main methods:

AlertSystem

system = AlertSystem(
    max_history=1000,       # Maximum alerts in history
    enable_filtering=True   # Duplicate filtering
)

Main methods:

MetricsCalculator

calculator = MetricsCalculator()

Main methods:

🔧 Data Models

Alert

@dataclass
class Alert:
    level: AlertLevel          # INFO, WARNING, ERROR, CRITICAL
    message: str
    timestamp: float
    data: Dict[str, Any]

SectorComparison

@dataclass
class SectorComparison:
    sector_number: int
    lap1_time: float
    lap2_time: float
    difference: float
    percentage_diff: float

LapComparison

@dataclass
class LapComparison:
    lap1_id: int
    lap2_id: int
    time_difference: float
    sector_comparisons: List[SectorComparison]
    speed_trace_comparison: Dict[str, Any]
    racing_line_difference: float
    suggestions: List[str]

🤝 Contributing

See CONTRIBUTING.md for contribution guidelines.

📝 License

This project is licensed under the MIT License. See LICENSE for more details.

🙏 Credits

Developed as part of the LFS-Ayats project to provide advanced telemetry analysis for Live for Speed.

This site is open source. Improve this page.