mlQCA API¶

Configuration and validation¶

class qca.MLQCAConfig(mode='conservative', engine='csqca', top_k=10, model_size=4, max_cutoffs_per_condition=3, consistency_cutoff=0.8, frequency_cutoff=1, minimizer='standard', random_state=201, validation='paper', n_splits=5, n_bootstrap=100, max_models=10000, n_jobs=1, required_conditions=(), excluded_conditions=(), model_params=<factory>)[source]¶

Validated settings shared by future mlQCA workflow stages.

Parameters:

mode (Literal['conservative', 'radical'])
engine (Literal['csqca', 'fsqca', 'gsqca'])
top_k (int)
model_size (int)
max_cutoffs_per_condition (int)
consistency_cutoff (float)
frequency_cutoff (int)
minimizer (str)
random_state (int)
validation (Literal['paper', 'cv', 'bootstrap'])
n_splits (int)
n_bootstrap (int)
max_models (int)
n_jobs (int)
required_conditions (tuple[str, ...])
excluded_conditions (tuple[str, ...])
model_params (Mapping[str, Any])

to_dict()[source]¶

Return a serializable configuration dictionary.

Return type:: dict[str, Any]

class qca.MLConditionSpec(name, data_type='continuous', direction='infer', required=False, enabled=True, theoretical_cutoffs=())[source]¶

Describe one uncalibrated candidate condition for mlQCA.

Parameters:

name (str)
data_type (Literal['continuous', 'ordinal', 'binary', 'nominal'])
direction (Literal['high', 'low', 'infer'])
required (bool)
enabled (bool)
theoretical_cutoffs (tuple[float, ...])

to_dict()[source]¶

Return a serializable schema record.

Return type:: dict[str, object]

class qca.ValidatedMLQCAInput(data, outcome, candidates, condition_specs, case_id=None)[source]¶

Normalized input returned by validate_mlqca_input().

Parameters:

data (DataFrame)
outcome (str)
candidates (tuple[str, ...])
condition_specs (tuple[MLConditionSpec, ...])
case_id (str | None)

property features: DataFrame¶: Return a copy of the validated predictor matrix.

property target: Series¶: Return the binary outcome as an integer Series.

qca.validate_mlqca_input(data, outcome, candidates=None, *, case_id=None, condition_specs=None, allow_missing_features=True)[source]¶

Validate and normalize input for future mlQCA workflow stages.

P0 accepts numeric or boolean candidate columns. Nominal variables should be encoded before use; native categorical support belongs to the ML backend phase.

Parameters:

data (DataFrame)
outcome (str)
candidates (Sequence[str] | None)
case_id (str | None)
condition_specs (Sequence[MLConditionSpec] | None)
allow_missing_features (bool)

Return type:

ValidatedMLQCAInput

Predictor¶

class qca.XGBoostBackend(config=None, *, model_params=None)[source]¶

Fit XGBoost and extract mlQCA condition and cutoff evidence.

Parameters:

config (MLQCAConfig | None)
model_params (Mapping[str, Any] | None)

fit(validated, evaluation=None)[source]¶

Fit XGBoost and optionally evaluate on a separate validated set.

Parameters:

validated (ValidatedMLQCAInput)
evaluation (ValidatedMLQCAInput | None)

Return type:

PredictorFitResult

class qca.PredictorFitResult(backend, model, feature_importance, cutoff_candidates, predictions, metrics=<factory>, settings=<factory>)[source]¶

Result returned by an mlQCA predictive backend.

Parameters:

backend (str)
model (Any)
feature_importance (DataFrame)
cutoff_candidates (DataFrame)
predictions (DataFrame)
metrics (dict[str, float])
settings (dict[str, Any])

property condition_ranking: DataFrame¶: Return feature importance ordered for condition selection.

property used_features: tuple[str, ...]¶: Return features used by at least one tree split.

qca.fit_xgboost_predictor(validated, config=None, *, model_params=None)[source]¶

Fit the standard mlQCA XGBoost backend.

Parameters:

validated (ValidatedMLQCAInput)
config (MLQCAConfig | None)
model_params (Mapping[str, Any] | None)

Return type:

PredictorFitResult

Calibration and engine adapters¶

qca.propose_crisp_calibrations(validated, predictor, conditions=None, *, direction_overrides=None, threshold_overrides=None, output_suffix='__crisp')[source]¶

Create one crisp calibration proposal per selected condition.

Parameters:

validated (ValidatedMLQCAInput)
predictor (PredictorFitResult)
conditions (Sequence[str] | None)
direction_overrides (Mapping[str, str] | None)
threshold_overrides (Mapping[str, float] | None)
output_suffix (str)

Return type:

DataFrame

qca.calibrate_crisp_conditions(validated, proposals, *, allow_missing=False)[source]¶

Apply crisp calibration proposals to validated mlQCA input.

Parameters:

validated (ValidatedMLQCAInput)
proposals (DataFrame)
allow_missing (bool)

Return type:

CrispCalibrationSet

qca.fit_csqca_from_predictor(validated, predictor, conditions=None, *, direction_overrides=None, threshold_overrides=None, output_suffix='__crisp', include_negations_in_necessity=True, **fit_kwargs)[source]¶

Calibrate predictor-selected conditions and fit CSQCA.

Parameters:

validated (ValidatedMLQCAInput)
predictor (PredictorFitResult)
conditions (Sequence[str] | None)
direction_overrides (Mapping[str, str] | None)
threshold_overrides (Mapping[str, float] | None)
output_suffix (str)
include_negations_in_necessity (bool)
fit_kwargs (Any)

Return type:

MLQCACSQCAResult

qca.propose_fuzzy_anchors(validated, predictor, conditions=None, *, anchor_overrides=None, direction_overrides=None, output_suffix='__fuzzy')[source]¶

Propose three fsQCA anchors for each selected condition.

Parameters:

validated (ValidatedMLQCAInput)
predictor (PredictorFitResult)
conditions (Sequence[str] | None)
anchor_overrides (Mapping[str, Sequence[float]] | None)
direction_overrides (Mapping[str, str] | None)
output_suffix (str)

Return type:

DataFrame

qca.calibrate_fuzzy_conditions(validated, proposals, *, allow_missing=False)[source]¶

Apply piecewise fuzzy calibration using mlQCA anchor proposals.

Parameters:

validated (ValidatedMLQCAInput)
proposals (DataFrame)
allow_missing (bool)

Return type:

FuzzyCalibrationSet

qca.fit_fsqca_from_predictor(validated, predictor, conditions=None, *, anchor_overrides=None, direction_overrides=None, output_suffix='__fuzzy', **fit_kwargs)[source]¶

Propose anchors, calibrate fuzzy sets, and fit FSQCA.

Parameters:

validated (ValidatedMLQCAInput)
predictor (PredictorFitResult)
conditions (Sequence[str] | None)
anchor_overrides (Mapping[str, Sequence[float]] | None)
direction_overrides (Mapping[str, str] | None)
output_suffix (str)
fit_kwargs (Any)

Return type:

MLQCAFSQCAResult

qca.calibrate_gsqca_conditions(validated, predictor, condition_kinds, *, conditions=None, threshold_overrides=None, anchor_overrides=None, direction_overrides=None)[source]¶

Calibrate crisp/fuzzy conditions and pass multi-value conditions through.

Parameters:

validated (ValidatedMLQCAInput)
predictor (PredictorFitResult)
condition_kinds (Mapping[str, str])
conditions (Sequence[str] | None)
threshold_overrides (Mapping[str, float] | None)
anchor_overrides (Mapping[str, Sequence[float]] | None)
direction_overrides (Mapping[str, str] | None)

Return type:

GSQCACalibrationSet

qca.fit_gsqca_from_predictor(validated, predictor, condition_kinds, *, conditions=None, threshold_overrides=None, anchor_overrides=None, direction_overrides=None, **fit_kwargs)[source]¶

Calibrate a gsQCA schema and fit GSQCA.

Parameters:

validated (ValidatedMLQCAInput)
predictor (PredictorFitResult)
condition_kinds (Mapping[str, str])
conditions (Sequence[str] | None)
threshold_overrides (Mapping[str, float] | None)
anchor_overrides (Mapping[str, Sequence[float]] | None)
direction_overrides (Mapping[str, str] | None)
fit_kwargs (Any)

Return type:

MLQCAGSQCAResult

Search and stability¶

qca.generate_condition_combinations(validated, predictor, config, *, conservative_models=None)[source]¶

Generate radical or conservative condition combinations.

Parameters:

validated (ValidatedMLQCAInput)
predictor (PredictorFitResult)
config (MLQCAConfig)
conservative_models (Sequence[Sequence[str]] | None)

Return type:

tuple[tuple[str, …], …]

qca.search_csqca_models(validated, predictor, config=None, *, conservative_models=None, direction_overrides=None, threshold_overrides=None, on_error='record', **fit_kwargs)[source]¶

Evaluate condition combinations with the PyQCA csQCA engine.

Parameters:

validated (ValidatedMLQCAInput)
predictor (PredictorFitResult)
config (MLQCAConfig | None)
conservative_models (Sequence[Sequence[str]] | None)
direction_overrides (Mapping[str, str] | None)
threshold_overrides (Mapping[str, float] | None)
on_error (Literal['record', 'raise'])
fit_kwargs (Any)

Return type:

MLQCAResult

qca.pareto_frontier(models, *, maximize=('consistency', 'coverage'), minimize=('complexity',))[source]¶

Return non-dominated valid models for the requested objectives.

Parameters:

models (DataFrame)
maximize (Sequence[str])
minimize (Sequence[str])

Return type:

DataFrame

class qca.MLQCAResult(feature_importance=<factory>, cutoff_candidates=<factory>, calibration_proposals=<factory>, condition_ranking=<factory>, candidate_models=<factory>, qca_results=(), best_model_id=None, pareto_models=<factory>, settings=<factory>, metadata=<factory>)[source]¶

Unified result container populated across mlQCA workflow phases.

Parameters:

feature_importance (DataFrame)
cutoff_candidates (DataFrame)
calibration_proposals (DataFrame)
condition_ranking (DataFrame)
candidate_models (DataFrame)
qca_results (tuple[QCAFitResult | None, ...])
best_model_id (int | str | None)
pareto_models (DataFrame)
settings (dict[str, Any])
metadata (dict[str, Any])

property best_qca_result: QCAFitResult | None¶: Return the QCA result selected by best_model_id.

summary()[source]¶

Return the candidate-model summary table.

Return type:: DataFrame

to_dataframe()[source]¶

Alias for summary().

Return type:: DataFrame

get_qca_result(model_id)[source]¶

Return one QCA result by model identifier.

Parameters:: model_id (int | str)
Return type:: QCAFitResult | None

to_markdown(path=None)[source]¶

Render a compact Markdown report and optionally write it.

Parameters:: path (str | Path | None)
Return type:: str

to_markdown_report(path=None, *, title='mlQCA Analysis Report', max_rows=20)[source]¶

Render a complete mlQCA report with reproducibility metadata.

Parameters:

path (str | Path | None)
title (str)
max_rows (int)

Return type:

str

to_jupyter_summary()[source]¶: Return a notebook-friendly summary object.

plot_importance(*, top_n=15, metric='shap_mean_abs', path=None)[source]¶

Plot feature importance using optional Matplotlib.

Parameters:

top_n (int)
metric (str)
path (str | Path | None)

plot_cutoffs(feature, *, path=None)[source]¶

Plot split-threshold frequency for one condition.

Parameters:

feature (str)
path (str | Path | None)

plot_frontier(*, path=None)[source]¶

Plot candidate models and the Pareto frontier.

Parameters:: path (str | Path | None)

qca.cross_validate_mlqca(validated, config=None, *, n_splits=None, top_k=None, cutoff_decimals=3)[source]¶

Evaluate feature and cutoff stability with stratified cross-validation.

Parameters:

validated (ValidatedMLQCAInput)
config (MLQCAConfig | None)
n_splits (int | None)
top_k (int | None)
cutoff_decimals (int)

Return type:

MLQCAStabilityResult

qca.bootstrap_mlqca(validated, config=None, *, n_bootstrap=None, top_k=None, cutoff_decimals=3)[source]¶

Evaluate feature and cutoff stability with stratified bootstrap fits.

Parameters:

validated (ValidatedMLQCAInput)
config (MLQCAConfig | None)
n_bootstrap (int | None)
top_k (int | None)
cutoff_decimals (int)

Return type:

MLQCAStabilityResult

class qca.MLQCAStabilityResult(method, run_summary, feature_stability, cutoff_stability, settings=<factory>, runs=())[source]¶

Aggregated condition and cutoff stability across repeated fits.

Parameters:

method (Literal['cv', 'bootstrap'])
run_summary (DataFrame)
feature_stability (DataFrame)
cutoff_stability (DataFrame)
settings (dict[str, Any])
runs (tuple[PredictorFitResult, ...])

summary()[source]¶

Return feature-level stability statistics.

Return type:: DataFrame

to_markdown(path=None)[source]¶

Render a compact Markdown stability report.

Parameters:: path (str | Path | None)
Return type:: str