stanbkt.models.BKTModelBase#

class stanbkt.models.BKTModelBase(fit_method=FitMethod.MCMC, individual_initial_knowledge=False, init_knowledge_strategy=InitKnowledgeStrategy.CORRECTNESS_ONLY, verbose=VerbosityLevel.INFO, stan_compile_kwargs=None, cpp_compile_kwargs=None)#

Bases: VerboseMixin, ABC

Abstract base class for Stan Bayesian Knowledge Tracing (BKT) models.

This class defines the interface that all Stan BKT model implementations must follow.

Variables:

  • fit_method (FitMethod) – The method used for fitting the model (e.g., MCMC, VB, MAP).

  • individual_initial_knowledge (bool) – Whether to initial know states are individualized to the student. If False, a single initial knowledge parameter is estimated for all students.

  • initital_knowledge_strategy (InitKnowledgeStrategy) – Strategy for estimating initial knowledge. This is only applicable if individual_initial_knowledge is True. When this is set to CORRECTNESS_ONLY, only the correctness data is used to estimate initial knowledge. When JOINT, model requires student level covariate (e.g. pretest) to jointly estimate initial knowledge (uses correctness and covariate). For example, CORRECTNESS_ONLY uses only the correctness of the first interaction for each student to inform initial knowledge estimates, while FIRST_INTERACTION uses the correctness of the first interaction with each KC for each student.

  • verbose (VerbosityLevel) – Verbosity level for logging.

  • stan_compile_kwargs (dict) – Additional keyword arguments for Stan model compilation.

  • cpp_compile_kwargs (dict) – Additional keyword arguments for C++ compilation of the Stan model.

Parameters:
check_data_contains_fitted_kcs(kcs)#

Check if data contains any KC that was fitted. Raises an error if data contains KCs that were not fitted.

Return type:

None

Parameters:

kcs (set[str])

fit(data, priors=None, column_mapping=None, stan_fit_options=None, overwrite_kcs=False)#

Fit the BKT model to data. Each KC is fitted independently with its own model. Additional KCs can be fitted by calling fit again with new data.

Parameters:

  • data (DataFrame) – DataFrame containing the training data. Must include columns for: Student ID, Problem ID, and Correctness (0/1). If the KC column is absent, all interactions are assumed to belong to a single knowledge component.

  • priors (Union[dict[str, PriorsBase], PriorsBase, None]) – Prior specifications for the model parameters. Can be provided as: - A single BayesianPriors object applied to all KCs. - A dictionary mapping KC IDs to their specific BayesianPriors. If None, default priors will be used for all KCs.

  • column_mapping (Union[Mapping[ColumnNames, str], Mapping[str, str], Mapping[ColumnNames | str, str], None]) – Mapping of expected column names. Keys should be ‘student_id’, ‘problem_id’, ‘correct’, and ‘kc_id’. If None, default column names are used.

  • stan_fit_options (Union[MCMCFitOptions, VBFitOptions, MLEFitOptions, PFFitOptions, dict[str, Any], None]) – Additional keyword arguments to pass to the Stan fitting method. If a dict is passed, it will be forwarded as-is to the CmdStanPy fit method. It is recommended to use the typed StanFitOptions for better type checking and validation. The accepted options depend on the chosen fit method. For example: - MCMC parameters (e.g., iter_sampling, chains, seed) - VB parameters (e.g., iter, tol_rel_obj) If None, default fitting options for the chosen fit method will be used.

  • overwrite_kcs (bool) – Whether to overwrite existing fits for KCs that are already fitted. If False, an error will be raised if attempting to fit a KC that already has a fit. If True, existing fits for the same KCs will be overwritten with the new fits.

Returns:

The fitted BKT model instance.

Return type:

BKTModelBase

Raises:

ValueError – If data validation fails or incompatible cpp_compile_kwargs and stan_fit_options.

get_kcs_in_fitted_kcs(kcs)#

Return the set of KCs in the data that were fitted previously.

Return type:

set[str]

Parameters:

kcs (set[str])

log(msg, level=VerbosityLevel.INFO)#

Log a message if verbosity level permits.

Parameters:

  • msg (str) – Message to log.

  • level (VerbosityLevel) – Verbosity level of this message. Message is printed if self.verbose >= level. Lower enum values = higher verbosity.

predict(data=None, column_mapping=None, point_estimate='mean', parallel=True, fast_math=True)#

Predict hidden states using point-estimate parameters from fitted posteriors.

Return type:

DataFrame

Parameters:
predict_posterior_draws(data, column_mapping=None, stan_output=None, backend='stan')#

Return draw-level posterior prediction DataFrames.

Parameters:

  • data (DataFrame) – Student interaction data used to remap Stan indices to original IDs.

  • column_mapping (Union[Mapping[ColumnNames, str], Mapping[str, str], Mapping[ColumnNames | str, str], None]) – Column name mapping. Defaults to the standard ColumnNames defaults.

  • stan_output (Optional[dict[str, CmdStanGQ]]) – Pre-computed output from predict_posterior_stan. When provided the Stan generated-quantities step is skipped.

  • backend (Literal['stan', 'numba']) – Backend used to produce posterior draws. - stan: use Stan generated quantities output (current behavior). - numba: run deterministic hidden-state recursion for each posterior parameter draw.

Returns:

Mapping from KC ID to draw-level DataFrames. Pass to stanbkt.utils.posterior_summary to obtain summary statistics.

Return type:

dict[str, DataFrame]

predict_posterior_stan(data, column_mapping=None)#

Run Stan generated quantities for posterior state prediction.

Parameters:
Returns:

Mapping from KC ID to raw CmdStanGQ fit objects. Pass the result to predict_posterior_draws to obtain draw-level DataFrames.

Return type:

dict[str, CmdStanGQ]

predict_posterior_summary(data, column_mapping=None, quantiles=[0.025, 0.975], stan_output=None, n_cores=1, backend='stan')#

Return per-observation posterior summaries without materializing all draws.

Parameters:

  • data (DataFrame) – Student interaction data used to remap Stan indices to original IDs.

  • column_mapping (Union[Mapping[ColumnNames, str], Mapping[str, str], Mapping[ColumnNames | str, str], None]) – Column name mapping. Defaults to the standard ColumnNames defaults.

  • quantiles (list[float]) – Quantiles to include in the returned posterior summary.

  • stan_output (Optional[dict[str, CmdStanGQ]]) – Pre-computed output from predict_posterior_stan. When provided, the Stan generated-quantities step is skipped.

  • n_cores (int) – Number of concurrent KC jobs to run. Use -1 to use all available CPU cores.

  • backend (Literal['stan', 'numba']) – Backend used to produce posterior summaries. - stan: summarize Stan generated quantities output. - numba: generate draw-level predictions via numba and summarize them.

Returns:

Per-observation posterior summary statistics for the overlapping fitted KCs.

Return type:

DataFrame

Warning

Setting n_cores greater than 1, or -1, can substantially increase peak memory usage and will most likely cause out-of-memory failures when the dataset is large.

predict_smoothed(data=None, column_mapping=None, point_estimate='mean', parallel=True, fast_math=True)#

Predict smoothed hidden states using point-estimate parameters.

Return type:

DataFrame

Parameters:
predict_smoothed_posterior_draws(data, column_mapping=None, stan_output=None, backend='stan')#

Return draw-level smoothed posterior prediction DataFrames.

Parameters:

  • data (DataFrame) – Student interaction data used to remap Stan indices to original IDs.

  • column_mapping (Union[Mapping[ColumnNames, str], Mapping[str, str], Mapping[ColumnNames | str, str], None]) – Column name mapping. Defaults to the standard ColumnNames defaults.

  • stan_output (Optional[dict[str, CmdStanGQ]]) – Pre-computed output from predict_smoothed_posterior_stan. When provided the Stan generated-quantities step is skipped.

  • backend (Literal['stan', 'numba']) – Backend used to produce posterior draws. - stan: use Stan generated quantities output (current behavior). - numba: run deterministic hidden-state recursion for each posterior parameter draw.

Returns:

Mapping from KC ID to draw-level DataFrames. Pass to stanbkt.utils.posterior_summary to obtain summary statistics.

Return type:

dict[str, DataFrame]

predict_smoothed_posterior_stan(data, column_mapping=None)#

Run Stan generated quantities for smoothed posterior state prediction.

Parameters:
Returns:

Mapping from KC ID to raw CmdStanGQ fit objects. Pass the result to predict_smoothed_posterior_draws to obtain draw-level DataFrames.

Return type:

dict[str, CmdStanGQ]

predict_smoothed_posterior_summary(data, column_mapping=None, quantiles=[0.025, 0.975], stan_output=None, n_cores=1, backend='stan')#

Return per-observation smoothed posterior summaries without materializing all draws.

Parameters:

  • data (DataFrame) – Student interaction data used to remap Stan indices to original IDs.

  • column_mapping (Union[Mapping[ColumnNames, str], Mapping[str, str], Mapping[ColumnNames | str, str], None]) – Column name mapping. Defaults to the standard ColumnNames defaults.

  • quantiles (list[float]) – Quantiles to include in the returned posterior summary.

  • stan_output (Optional[dict[str, CmdStanGQ]]) – Pre-computed output from predict_smoothed_posterior_stan. When provided, the Stan generated-quantities step is skipped.

  • n_cores (int) – Number of concurrent KC jobs to run. Use -1 to use all available CPU cores.

  • backend (Literal['stan', 'numba']) – Backend used to produce posterior summaries. - stan: summarize Stan generated quantities output. - numba: generate draw-level predictions via numba and summarize them.

Returns:

Per-observation smoothed posterior summary statistics for the overlapping fitted KCs.

Return type:

DataFrame

Warning

Setting n_cores greater than 1, or -1, can substantially increase peak memory usage and will most likely cause out-of-memory failures when the dataset is large.

save(save_base_location)#

Save fitted model artifacts to a compressed archive.

Parameters:

save_base_location (str | PathLike[str]) – Archive path where fitted model artifacts should be saved.

Raises:

RuntimeError – If model has not been fitted yet.

Return type:

None

set_verbosity(level)#

Set the verbosity level for logging.

Parameters:

level (VerbosityLevel) – New verbosity level.

Raises:

ValueError – If level is not a valid VerbosityLevel.

summary(kcs=None, percentiles=(2.5, 97.5), column_mapping={}, clear_cache=False)#

Get summary statistics for model parameters.

Parameters:

  • kcs (Union[list[str], str, None]) – KCs to summarize. Can be a single KC string, a list of KCs, or None. If None, summarizes all fitted KCs.

  • percentiles (Tuple[float, float]) – Percentiles to include in summary. Values should be in range [1, 99]. Ignored when the fit method is MLE, MLE produces a point estimate only.

  • clear_cache (bool) – Whether to refresh the cached summaries.

  • column_mapping (dict[str, str])

Returns:

Summary statistics.

Return type:

Any

Raises:

RuntimeError – If model has not been fitted yet.