Add Deviation Percentage to Quarantine Triggers

[JohnMwashuma]

Context

Currently, the quarantine triggers in Tally Ho enforce strict rules that determine whether a form should be quarantined. However, there is no flexibility to account for small, acceptable deviations in form data.

For example, the pass_registrants_trigger check flags a form when the sum of ballots inside the box + canceled ballots exceeds the number of registered voters + buffer (qc.value).

• This strict threshold can sometimes cause false positives, unnecessarily flagging forms that may have insignificant deviations due to human or system errors.

To improve accuracy, all quarantine triggers should allow a configurable deviation percentage to reduce unnecessary quarantining while still catching serious issues.

---

Proposed Changes

1️⃣ Introduce a Deviation Percentage for All Quarantine Checks

• ✅ Modify all quarantine trigger functions to include an acceptable deviation percentage.
• ✅ Retrieve the deviation percentage from a configuration setting (qc.deviation_percentage) stored in the QuarantineCheck model.
• ✅ If a check slightly exceeds the threshold but falls within the deviation range, pass the check instead of quarantining.

2️⃣ Update pass_registrants_trigger as an Example

• ✅ Instead of a strict registrant limit, allow a small configurable deviation before triggering quarantine.
• ✅ Adjust calculation as follows:

allowed_voters = (registrants + qc.value) + (deviation_percentage * registrants)

3️⃣ Apply Deviation Logic to All Quarantine Triggers

• ✅ Modify each quarantine check to incorporate the deviation percentage logic.
• ✅ Ensure that the deviation percentage is optional (default: 0% if not set).
• ✅ Add necessary unit tests to verify behavior with different deviation values.

---

Acceptance Criteria

✅ All quarantine trigger functions respect a deviation percentage.
✅ The deviation percentage is configurable via the QuarantineCheck model.
✅ Forms just slightly above a threshold are not quarantined unnecessarily.
✅ Unit tests cover cases with different deviation percentages.

---

Implementation Plan

1️⃣ Modify QuarantineCheck Model

• Add a new field:

  deviation_percentage = models.FloatField(default=0.0)

• Allow setting this per trigger.

2️⃣ Update pass_registrants_trigger to Use Deviation

• Adjust logic to consider the deviation range.
• Ensure calculations are correctly rounded.

3️⃣ Modify Other Quarantine Triggers

• Update all trigger functions in [quarantine_checks.py](https://github.com/onaio/tally-ho/blob/5f926f6b2bb6e38b22fcc90aa66aa293e4ec87cd/tally_ho/libs/verify/quarantine_checks.py#L42) to include deviation handling.

4️⃣ Add Unit Tests

• Verify pass/fail logic for:
  • Strict threshold (0% deviation)
  • 5% deviation
  • 10% deviation

5️⃣ QA & UAT

• Validate real-world cases with test forms.
• Ensure that forms with small deviations are not quarantined unnecessarily.

---

Estimated Level of Effort (LOE)

Task	Complexity	Estimated Time
1. Modify QuarantineCheck Model	🟡 Medium	4-6 hours
2. Update pass_registrants_trigger	🟡 Medium	6-8 hours
3. Modify Other Quarantine Triggers	🟠 High	12-16 hours
4. Unit Tests & Update Existing Tests	🟠 High	10-14 hours
5. QA & UAT (User Testing & Validation)	🟠 High	8-12 hours
6. Deployment & Documentation	🟢 Low	4-6 hours

Total Estimated LOE: ~44-62 hours (~5-8 working days / ~1-1.5 weeks)

🚀 Effort Level: 🟡 Medium to High Complexity