Skip to content

Guide: Debugging Flags and Fine-Tuning

A deep dive into the powerful CLI flags that give you granular control over data processing, validation, and analysis in BatteryProc.

This guide is for advanced users, researchers validating new instruments, and anyone who needs to troubleshoot complex or unusual datasets. Here, we'll go beyond the basic processing commands to explore the flags that let you: - Fine-tune the metric reconciliation engine. - Control the cycle detection algorithms. - Enable verbose logging for deep debugging.

Note: For fully runnable scripts with sample data and plotting that demonstrate the concepts in this guide, please see the Examples Directory.

1. General Debugging Flags

These flags provide insight into the BatteryProc processing pipeline.

  • --debug : Enables verbose debug logging to the console. This is your first-line tool for troubleshooting. It will print detailed information during parsing, normalization, and metric calculation, including any assumptions made and warnings about data quality.

  • --debug-step-plan : Pretty-prints the step plan DataFrame extracted from the raw data. This is useful for confirming that BatteryProc correctly interpreted the experimental protocol from the instrument file.

  • --force-process : By default, batteryproc will skip files that appear incomplete (e.g., very few data points, still on Cycle 1). This flag overrides these safety checks and forces processing for every file, regardless of its contents.

2. Metric Reconciliation Flags

One of BatteryProc's most powerful features is its ability to recompute key metrics from raw data and compare them against the summary values reported by the instrument. This is essential for validating instrument accuracy and detecting data corruption. The following flags control this reconciliation process.

2.1. Detailed Flag Descriptions

  • --recompute-all : When to use: Use this when you fundamentally distrust the summary metrics in your source files. : What it does: Forces BatteryProc to ignore every per-cycle metric reported in the source file and always use the values it calculates from the raw time-series data. This is the ultimate override for ensuring consistency.

  • --prefer-file-metrics : When to use: This is the default behavior, but you can use it explicitly to confirm. : What it does: Trusts the instrument-reported metrics as long as they are "close enough" to the recomputed values. "Close enough" is defined by the tolerance settings.

  • --metric-tolerance : What it does: Sets the relative tolerance (as a fraction) for the comparison. The default is 0.05, meaning the file's value is accepted if it is within 5% of the recomputed value. : Example: --metric-tolerance 0.01 tightens the check to 1%.

  • --metric-tolerance-abs : What it does: Sets the absolute tolerance for the comparison. This value is applied before the relative tolerance and is useful for metrics with small magnitudes, where relative checks are too sensitive. : Example: --metric-tolerance-abs 0.5 allows a 0.5 mAh difference in capacity, even if that difference is more than the relative tolerance.

2.2. Tolerance Logic Deep Dive

The decision to trust a file metric or replace it is based on a combined tolerance check. A file value is considered valid if it passes either the absolute check or the relative check.

Algorithm: 

diff = abs(file_value - computed_value)
relative_diff = diff / max(1e-9, abs(computed_value))

# The metric passes if either condition is true
passed = (diff <= absolute_tolerance) or (relative_diff <= relative_tolerance)

It's also important to note that the absolute tolerance is scaled for certain metrics to be more physically meaningful: - Energy: The provided absolute tolerance is multiplied by 2x. - Percentages (e.g., Efficiency): The provided tolerance is scaled by 10x.

Example Calculation:

  • Settings: --metric-tolerance 0.02 (2%) and --metric-tolerance-abs 0.5 (for capacity).
  • Data:
    • File-reported discharge capacity: 98.2 mAh
    • BatteryProc-recomputed capacity: 100.0 mAh
  • Check:
    1. diff = abs(98.2 - 100.0) = 1.8 mAh
    2. Absolute Check: Is 1.8 <= 0.5? False.
    3. Relative Check: relative_diff = 1.8 / 100.0 = 0.018 (1.8%). Is 0.018 <= 0.02? True.
  • Result: Since the relative check passed, the file's value of 98.2 mAh is kept. If the recomputed value had been 103.0 mAh, the difference would be 3.0 mAh (3%), failing both checks, and the value would be replaced.

2.3. Practical Examples and Troubleshooting

  • Validating a New Instrument: 

    batteryproc new_instrument_data.xlsx --metric-tolerance 0.005 --metric-tolerance-abs 0.1 --debug
    This runs processing with very tight tolerances (0.5% relative, 0.1 mAh absolute) and prints a detailed debug log, allowing you to see every single comparison and any violations.

  • Processing Data with Known Drift: 

    batteryproc old_data.csv --metric-tolerance 0.1
    If you're working with data from an older instrument known to have slight drift, you can loosen the tolerance to 10% to silence expected warnings while still catching major errors.

  • Debugging Tolerance Violations: If you see warnings like WARNING: Metric 'discharge_mAh' for cycle 5 failed tolerance check, it means the value reported in the file for that specific metric and cycle differs significantly from the value calculated by integrating the raw current-time data. Use --recompute-all to create a "clean" output file based entirely on BatteryProc's calculations.

For a runnable demonstration of these flags, see the example_tolerance_comparison.py script.

3. Cycle Detection Flags

These flags give you direct control over the cycle detection algorithms. For a full theoretical background, see the Guide to Cycle Detection.

  • --cycle-detection METHOD : Lets you choose the detection method. : - auto: (Default) Uses the tiered strategy: trusts a valid existing index, then tries parsing step_type, then falls back to current_sign. : - step_type: Forces the engine to only use step_type labels. It will fail if the column is missing or labels are unrecognized. : - current_sign: Forces the engine to use the data-driven current sign analysis. Ideal for raw CSV files or data with unreliable step labels.

  • --current-threshold VALUE : Sets the absolute current (in Amperes) used to distinguish active cycling from rest. The default is small (e.g., 0.01 A). Increase this value if your data has a high noise floor to prevent noise from being misinterpreted as cycling.

  • --autotune-current-threshold / --no-autotune-current-threshold : Toggles the adaptive current-threshold heuristic. When enabled (--autotune-current-threshold), the engine analyzes the current distribution to find an optimal threshold, which is useful for datasets with very low currents. Use --no-autotune-current-threshold to ensure a fixed, manual threshold is used, which is better for ensuring comparability across different datasets.

  • --validate-cycles : Enables detailed cycle validation diagnostics in the output log. This will report on potential anomalies like short cycles, time reversals, or mismatches between cycle boundaries and capacity resets.

  • --cycle-config FILE : Load cycle detection parameters (like thresholds and filters) from a YAML configuration file, allowing you to save and reuse complex configurations.

Practical Examples

  • Forcing Current-Based Detection on a CSV: 

    batteryproc docs/examples/sample_3cycles.csv -o ./output/ --cycle-detection current_sign

  • Handling Noisy Data with a Custom Threshold: 

    batteryproc noisy_file.xlsx -o ./output/ --cycle-detection current_sign --current-threshold 0.05

  • Enabling Full Validation Diagnostics: 

    batteryproc docs/examples/sample_cccv.xlsx -o ./output/ --validate-cycles
    This will produce a detailed report in the console about the quality and consistency of the detected cycles.

For a runnable demonstration of the different detection methods, see the example_cycle_detection.py script.