setqca

A native, typed Python implementation of Qualitative Comparative Analysis (QCA).

setqca is not an R wrapper. It provides an auditable Python implementation of the mathematical core of crisp-set and fuzzy-set QCA, with exact Boolean minimisation and data-science-friendly result objects.

Status: 0.1.0 alpha. Conservative and parsimonious csQCA/fsQCA are the stable focus. Directional intermediate solutions are deliberately marked experimental until parity-tested against the reference R QCA implementation.

📖 Documentation · 🚀 Getting started · 🔬 Validation policy

Why this project

The mature R QCA ecosystem supports crisp-set, fuzzy-set, multi-value and temporal QCA with exact Boolean minimisation. Python has individual QCA-related projects, but there is still room for a general-purpose, typed and thoroughly validated scientific implementation that lives natively in the Python data stack.

Four commitments shape the design:

Features

• crisp calibration
• three-anchor direct fuzzy calibration
  • logistic (numerically stable across the whole real line)
  • piecewise linear/power
  • increasing and decreasing sets
• typed set algebra with &, | and ~
• sufficiency consistency, coverage and PRI
• necessity consistency, coverage and RoN
• complete binary truth tables
• frequency, consistency and PRI cutoffs
• contradiction and logical-remainder classification
• exact classical Quine-McCluskey prime-implicant generation
• exact branch-and-bound solution of the prime-implicant chart
• conservative solutions
• parsimonious solutions
• experimental directional intermediate solutions
• tidy pandas exports
• optional parity harness against R QCA

Installation

pip install setqca

Requires Python 3.11+. Runtime dependencies are numpy and pandas only.

For a development checkout:

git clone https://github.com/DiogoRibeiro7/setqca-python.git
cd setqca-python
poetry install

Usage

Calibration

from setqca import calibrate_direct

innovation = calibrate_direct(
    raw_innovation,
    full_out=10,
    crossover=50,
    full_in=90,
)

The default idm=0.95 maps the three anchors to approximately 0.05, 0.5 and 0.95 for increasing sets.

Typed fuzzy-set algebra

from setqca import Condition

A = Condition("A")
B = Condition("B")
C = Condition("C")

configuration = A & B & ~C
membership = configuration.evaluate(data)

fsQCA

from setqca import FSQCA

model = FSQCA(
    consistency=0.85,
    pri=0.70,
    frequency=2,
)

result = model.fit(
    data,
    outcome="Y",
    conditions=["A", "B", "C", "D"],
    case_id="case",
)

print(result)
print(result.truth_table.to_frame())
print(result.summary_frame("parsimonious"))

csQCA

from setqca import CSQCA

result = CSQCA().fit(
    crisp_data,
    outcome="Y",
    conditions=["A", "B", "C"],
)

CSQCA rejects non-binary condition or outcome columns.

Exact minimisation

The low-level engine is public for testing and research:

from setqca.minimize import minimize

# AB~C + ABC -> AB
solutions = minimize({6, 7}, width=3)
print(solutions[0].as_expression(("A", "B", "C")))
# A*B

Logical remainders are explicit don't-cares:

solutions = minimize(
    {6, 7},
    dont_cares={4, 5},
    width=3,
)

Scientific validation policy

The R QCA package is used as a reference implementation for parity tests, not as a runtime dependency. The repository includes validation/r/parity.R so canonical datasets can be run through both implementations.

Correctness rests on five layers: unit tests against known results, brute-force exactness tests of the minimiser, property-based invariant tests, error-contract tests, and R parity fixtures. See the validation page for the current parity status of each component, and docs/METHODOLOGY.md for the formal implementation contract.

Non-goals for 0.1

• claiming complete parity with R QCA;
• mvQCA;
• tQCA;
• CCubes/eQMC performance parity;
• stable standard intermediate solutions.

These are roadmap items rather than hidden approximations. See docs/ROADMAP.md.

Development

poetry install --with dev,docs
poetry run pre-commit install

make check     # lint, format, types and tests
make docs      # serve the documentation locally

Without make:

poetry run ruff check .
poetry run ruff format --check .
poetry run mypy
poetry run pytest --cov=setqca

Contributions are welcome — please read CONTRIBUTING.md first, particularly the scientific-correctness requirements for changes to the mathematical core.

Citing

If you use setqca in published research, please cite the archived release. Machine-readable metadata is provided in CITATION.cff, codemeta.json and .zenodo.json.

License

MIT — see LICENSE.