Make the truth table a reusable analytical object

[DiogoRibeiro7]

Keeps rows that thresholds excluded, records why, and lets a stored table be re-minimised without the original data.

table.positive_rows(); table.negative_rows()
table.contradictions(); table.remainders()
table.excluded_rows()          # kept out by a threshold, not by the evidence
print(table.summary())

text = table.to_json()
restored = TruthTable.from_json(text)
restored.minimize()                          # conservative
restored.minimize(include_remainders=True)   # parsimonious

Both minimisations agree with the estimator exactly; tests assert it. Only case-level fit still needs the original data, since it describes cases rather than configurations.

The distinction worth having

An outcome code conflates situations that call for different responses, so every row now carries exclusion_reason in words:

frequency 1 below the cutoff of 2
consistency 0.643 below the inclusion cutoff of 0.8
PRI 0.412 below the cutoff of 0.7

A row can clear consistency and still be excluded by PRI — the existing coding sends it to "C", which reads as "contradictory" and hides the real cause. Rather than change the coding and break parity, both failures are now named separately, and there is a test constructing exactly that case: consistency passes, PRI does not, and the reason mentions PRI and not consistency.

excluded_rows() returns only rows a threshold held back — the ones a different analytical choice would have admitted. A row with genuinely low consistency is excluded by the data and is deliberately not listed, since no threshold would rescue it. That makes it the right input to a robustness discussion.

exclusion_reason defaults to None, so existing construction is unaffected. to_frame gains an excluded_because column.

498 tests at 100% coverage; mypy strict and docs build clean.

---

Summary by cubic

Makes the truth table a reusable analytical object: keeps threshold-excluded rows with clear reasons, adds JSON serialization, and allows direct minimization from stored tables. Improves transparency and lets you reproduce solutions without the original data.

• New Features

  • Rows record exclusion_reason (frequency vs consistency vs PRI) and expose excluded_rows() for threshold-held rows only.
  • Added row accessors: positive_rows(), negative_rows(), contradictions(), remainders().
  • New TruthTableRow.excluded_by_threshold flag.
  • to_frame() gains excluded_because; summary() provides a quick count by group.
  • Serialization: to_dict(), from_dict(), to_json(), from_json().
  • TruthTable.minimize(include_remainders, max_solutions) returns Boolean covers and matches FSQCA conservative/parsimonious results; case-level fit still requires data.

• Docs & Tests

  • Expanded guide with examples for row accessors, reasons, and reusing tables.
  • Added tests covering accessors, reasons (including PRI-only failures), JSON round-trip, and estimator parity.

^{Written for commit 6a946f5. Summary will update on new commits.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!