Frequently Asked Questions¶
Data & Import¶
What data formats does RRational support?¶
RRational supports 8 input formats:
- HRV Logger (iOS/Android) — CSV with timestamps and events
- VNS Analyse (clinical) — TXT with embedded annotations
- Polar Sensor Logger / Polar Beat — CSV with phone timestamps
- Polar Flow — TSV export (elapsed time only)
- Empatica E4 / EmbracePlus — IBI.csv with Unix timestamps
- Elite HRV — Plain text, one RR value per line
- Kubios HRV — Report or signal/series export
- Plain text RR — Any single-column RR interval file
See Data Formats for detailed specifications.
How are participant IDs extracted?¶
By default, RRational extracts participant IDs from filenames using the pattern (\d{4}[A-Z]{4}) (four digits followed by four uppercase letters). For example, 0001CTRL_RR_2024-01-15.csv becomes 0001CTRL. You can customize the pattern in the Data tab settings — a simpler (\d+) ("first number found") is one of the selectable presets.
Can I merge multiple recording files per participant?¶
Yes. If multiple _RR_ files share the same participant ID, RRational automatically merges them chronologically. For VNS Analyse, multiple .txt files per participant are concatenated with gap detection.
Artifact Detection¶
What artifact rate is acceptable?¶
Following the 2024 Quigley guidelines:
| Artifact Rate | Quality Grade | Recommendation |
|---|---|---|
| ≤ 2% | Excellent | All metrics valid |
| 2–5% | Good | All metrics valid |
| 5–10% | Moderate | Time-domain only |
| > 10% | Poor | Segment excluded |
A segment is also excluded automatically if it has fewer than 50 beats, regardless of artifact rate (too short for any reliable HRV metric).
Which artifact detection method should I use?¶
- Kubios (Segmented) — recommended for long recordings (> 10 min). Processes in 5-minute windows for better sensitivity.
- Kubios (Single-pass) — for short segments (< 10 min)
- Threshold — simple min/max filter, useful for initial screening
Should I correct artifacts before analysis?¶
Yes. RRational uses the Kubios algorithm (Lipponen & Tarvainen, 2019) for correction. Corrected NN intervals replace detected artifacts with interpolated values. However, segments with > 10% artifacts should be excluded entirely rather than corrected.
Analysis¶
How many beats do I need for valid HRV analysis?¶
| Domain | Minimum Beats | Recommended |
|---|---|---|
| Time-domain (RMSSD, SDNN) | 100 | 300+ |
| Frequency-domain (LF, HF) | 300 | 500+ |
Short recordings produce unreliable frequency metrics. RRational warns you when beat counts are insufficient.
What does RMSSD measure?¶
RMSSD (Root Mean Square of Successive Differences) reflects parasympathetic (vagal) cardiac modulation. It is the most robust short-term HRV metric and is resistant to breathing rate confounds.
Is the LF/HF ratio a valid measure of sympathovagal balance?¶
No. Current consensus (Quigley et al., 2024; Laborde et al., 2017) rejects the LF/HF ratio as an index of sympathovagal balance. The LF band reflects both sympathetic and parasympathetic activity plus baroreflex function. RRational includes it for completeness but we recommend focusing on RMSSD and HF power for parasympathetic assessment.
What window size should I use?¶
- 5 minutes — standard for short-term HRV (Task Force, 1996)
- 2–3 minutes — acceptable for ultra-short recordings (Munoz et al., 2015)
- Ensure consistent window sizes within a study
Why are my LF/HF values different from Kubios HRV?¶
By default RRational uses the NeuroKit2 pipeline (normalized PSD, 100 Hz interpolation). This gives different absolute values than Kubios — but the relative pattern across conditions is preserved.
To get Kubios-comparable absolute ms² values, switch the Frequency-domain pipeline dropdown in the Analysis tab to "Kubios-compatible". Our cross-validation shows ±5% agreement on LF, HF and RMSSD on properly matched segments. See Kubios Compatibility Guide.
Why is my SDNN much higher than in Kubios?¶
This is by design — RRational follows the Task Force 1996 standard definition (standard deviation of raw NN intervals). Kubios computes SDNN on a detrended interpolated signal, which removes low-frequency variance and lowers SDNN by roughly 30–50%. Both are valid; cite which one you used. See Kubios Compatibility Guide.
Is RRational scientifically validated?¶
Yes. The HRV engine is NeuroKit2 (Makowski et al. 2021), a peer-reviewed, widely cited library. We provide an independent cross-validation against Kubios HRV Scientific, together with guideline conformance and DOI-linked references, in the Validation report. The validation recordings contain identifiable participant data and are not redistributed, but the report documents the exact pipeline parameters so the comparison can be reproduced on equivalent data.
Segments & Sections¶
What is the difference between segments and sections?¶
- Segments are time-based windows (e.g., every 5 minutes) created automatically for artifact detection and quality assessment
- Sections are event-based boundaries (e.g., "measurement_start" to "pause_start") defined by your experimental protocol
How do I set up repeating experimental conditions?¶
- Define Event Sequences in Setup > Sequences (e.g., Sequence A: music, silence, music, silence)
- Assign participants to sequences
- Set Condition Labels (e.g., "condition_a" → "Music", "condition_b" → "Silence")
- Use Repeating Section Analysis in the Analysis tab
Export & Reporting¶
What export formats are available?¶
- CSV — metric tables with all computed HRV values
- HTML / Markdown report — formatted analysis report for sharing
- .rrational — native format preserving full analysis state (reimportable)
What should I report in a publication?¶
Following the GRAPH checklist (Quintana et al., 2016):
- Recording device and sampling rate
- Artifact detection method and threshold
- Artifact rate per segment
- Correction algorithm used
- HRV metrics with window duration
- Number of excluded segments and reasons
- Beat count per analyzed segment
Appearance¶
How do I customize plot colors?¶
Open the sidebar → expand Settings → scroll to Color Theme. Choose a preset (Scientific, Colorful, High Contrast, Monochrome, Pastel) or select Custom to pick individual colors for RR line, NN line, artifacts, exclusions, events, and sections. Click Save Settings to persist your choice.
Does dark mode affect plot colors?¶
Yes. When you switch to dark mode, all plot colors are automatically lightened for better visibility on dark backgrounds. You don't need to configure separate dark mode colors.
What are the preset themes?¶
| Preset | Style | Best for |
|---|---|---|
| Scientific | Classic blue/green tones | Publications, presentations |
| Colorful | Vibrant purple/pink/teal | Exploratory analysis |
| High Contrast | Pure primary colors | Accessibility, projectors |
| Monochrome | Grayscale | B&W printing |
| Pastel | Soft, muted tones | Light backgrounds, reports |
Technical¶
The macOS app won't open / "unverified developer"¶
The standalone app is not signed with an Apple Developer certificate. macOS Gatekeeper blocks unsigned apps by default.
Fix: Right-click RRational.app → Open (not double-click). Click Open in the dialog. This only needs to be done once.
Alternative: Open Terminal and run:
Why is the app slow to start?¶
First launch imports heavy dependencies (NeuroKit2, Plotly, NumPy). Subsequent reruns are fast due to caching. Use --test-mode for quick testing with demo data.
Can I use RRational without an internet connection?¶
Yes. RRational runs entirely locally. No data is transmitted externally. All processing happens on your machine.
How do I update RRational?¶
RRational is installed from source (it is not published on PyPI), so updating means pulling the latest main and re-syncing dependencies.