Analyzers Quick Reference

Command-line reference for all data analysis tools.

Bump Detector

Counts wheel bumps, calculates B/cm calibration.

# Basic usage
python analyzers/bump_detector.py data/recording.csv

# Custom threshold (default: 0.015)
python analyzers/bump_detector.py data/recording.csv --threshold 0.02

# Custom filter coefficient (default: 0.95)
python analyzers/bump_detector.py data/recording.csv --alpha 0.98

Output:

Bump Detection Analysis
=============================================
Samples:     5000
Duration:    10.00 s
Ultrasonic Travel: 30.5 cm
Robot Bumps: 92
=============================================
B/cm = 3.016
=============================================

FFT Analyzer

Frequency spectrum analysis using Fast Fourier Transform.

# Analyze accelerometer X
python analyzers/fft_analyzer.py data/recording.csv --channel ax

# Show plot
python analyzers/fft_analyzer.py data/recording.csv --plot

# Estimate bump frequency from all axes
python analyzers/fft_analyzer.py data/recording.csv --bump

# Save plot to file
python analyzers/fft_analyzer.py data/recording.csv --save spectrum.png

# Custom sample rate (default: 500)
python analyzers/fft_analyzer.py data/recording.csv --rate 800

Channels: ax, ay, az, gx, gy, gz

Vibration Analyzer

Speed estimation from vibration intensity.

# Basic usage
python analyzers/vibration_analyzer.py data/recording.csv

# Custom window size (default: 50)
python analyzers/vibration_analyzer.py data/recording.csv --window 30

# Custom stopped threshold (default: 0.001)
python analyzers/vibration_analyzer.py data/recording.csv --threshold 0.002

Output:

Motion State Distribution:
  STOPPED :  15.0%
  SLOW    :  25.0%
  MEDIUM  :  45.0%
  FAST    :  15.0%

Motion Classifier

Machine learning motion classification.

# Train a model
python analyzers/motion_classifier.py train data/ai_dataset.csv

# Train with specific model type
python analyzers/motion_classifier.py train data/ai_dataset.csv --model forest
python analyzers/motion_classifier.py train data/ai_dataset.csv --model tree
python analyzers/motion_classifier.py train data/ai_dataset.csv --model knn
python analyzers/motion_classifier.py train data/ai_dataset.csv --model rule

# Save model to specific file
python analyzers/motion_classifier.py train data/ai_dataset.csv --output my_model.pkl

# Evaluate model accuracy
python analyzers/motion_classifier.py evaluate data/ai_dataset.csv

# Use trained model for prediction
python analyzers/motion_classifier.py predict motion_model.pkl data/new_data.csv

Model Types: | Model | Description | Accuracy | Speed | |-------|-------------|----------|-------| | forest | Random Forest (recommended) | High | Medium | | tree | Decision Tree | Medium | Fast | | knn | K-Nearest Neighbors | Medium | Slow | | rule | Simple thresholds | Low | Fastest |

Common Options

All analyzers support:

--help, -h     Show help message

Python Module Usage

from analyzers import BumpDetector, FFTAnalyzer, VibrationAnalyzer, MotionClassifier

# Bump detection
detector = BumpDetector(threshold=0.015)
detector.load_csv('data/recording.csv')
results = detector.analyze()
print(f"B/cm = {results['bumps_per_cm']:.3f}")

# FFT analysis
fft = FFTAnalyzer(sample_rate=500)
fft.load_csv('data/recording.csv')
results = fft.analyze('ax')
print(f"Peak frequency: {results['peak_frequency']:.1f} Hz")

# Vibration analysis
vib = VibrationAnalyzer(window_size=50)
vib.load_csv('data/recording.csv')
results = vib.analyze()
print(f"Motion states: {results['state_percentages']}")

# Motion classification
clf = MotionClassifier(model_type='forest')
clf.train_from_csv('data/ai_dataset.csv')
prediction = clf.predict({'ax': 0.1, 'gx': 5, 'vib': 10})
print(f"Predicted: {prediction}")

Data Requirements

Recording CSV (bump, fft, vibration)

Minimum columns:

time_s,ax,ay,az,gx,gy,gz,us

Optional columns:

motor_l,motor_r,bumps,vib,heading,drift

AI Dataset CSV (motion classifier)

Required columns:

label,ax,ay,az,gx,gy,gz,us

Labels: STOPPED, FORWARD, BACKWARD, TURN_LEFT, TURN_RIGHT

Algorithm Summary

Analyzer	Method	Input	Output
bump_detector	HP filter + threshold	Accel magnitude	Bump count, B/cm
fft_analyzer	Fourier transform	Any channel	Frequency spectrum
vibration_analyzer	Sliding variance	Accel magnitude	Motion states
motion_classifier	ML (forest/tree/knn)	All sensors	Motion label