stanbkt.models#

Functions

predict_posterior(model, data[, ...])

Classes

BKTModelBase([fit_method, ...])

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

InitKnowledgeStrategy(*values)

Enumeration of initial knowledge estimation strategies.

ModelType(*values)

Enumeration of BKT model types.

MultiBKT([fit_method, verbose, ...])

Grouped Bayesian Knowledge Tracing model.

MultiPriors([pi_b0_know_mu, pi_b0_know_std, ...])

Bayesian priors for joint estimation of initial knowledge and other parameters.

StandardBKT([fit_method, ...])

Bayesian Knowledge Tracing (BKT) model implementation.

StandardPriors([pi_b0_know_mu, ...])

Bayesian priors for the Standard BKT model parameters.

Exceptions

FitMethodMismatchError

Raised when attempting to refit a model with a different fit method.

API Details

BKT model implementations and Bayesian priors for parameters.

This module provides the core BKT model classes and supporting utilities for model types, priors, and error handling.

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.

exception stanbkt.models.FitMethodMismatchError#

Bases: ValueError

Raised when attempting to refit a model with a different fit method.

add_note()#

Exception.add_note(note) – add a note to the exception

args#
with_traceback()#

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class stanbkt.models.InitKnowledgeStrategy(*values)#

Bases: StrEnum

Enumeration of initial knowledge estimation strategies.

Variables:

  • JOINT (str) – Jointly estimate initial knowledge from additional pre-test or prior data.

  • CORRECTNESS_ONLY (str) – Estimate initial knowledge based only on correctness data.

CORRECTNESS_ONLY = 'correctness_only'#
JOINT = 'joint'#
class stanbkt.models.ModelType(*values)#

Bases: StrEnum

Enumeration of BKT model types.

Variables:

  • STANDARD (str) – Standard Bayesian Knowledge Tracing model (single parameter set across all students).

  • GROUPED (str) – Grouped BKT model with parameters varying across student groups.

  • NESTED (str) – Nested BKT model with hierarchical parameter structure.

GROUPED = 'grouped'#
NESTED = 'nested'#
STANDARD = 'standard'#
class stanbkt.models.MultiBKT(fit_method=FitMethod.MCMC, verbose=VerbosityLevel.INFO, stan_compile_kwargs=None, cpp_compile_kwargs=None)#

Bases: BKTModelBase

Grouped Bayesian Knowledge Tracing model.

Extends the standard BKT model to allow group-specific parameters. Each student is assigned to a group via a group_id column in the data, and each group receives its own BKT parameters (pi_know, learn, forget, guess, slip).

The same Stan model (BKT_model.stan) is reused. StandardBKT collapses it to a single group; MultiBKT lets it run with the full group structure present in the data.

Parameters:

  • fit_method (FitMethod) – The method to use for fitting the Stan model.

  • verbose (VerbosityLevel) – Verbosity level for logging.

  • stan_compile_kwargs (dict | None) – Additional Stan compilation options.

  • cpp_compile_kwargs (dict | None) – Additional C++ compilation options.

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])

evaluate(**kwargs)#

Evaluate model performance (not yet implemented).

Returns:

Evaluation results (implementation pending).

Return type:

dict[str, Any]

Raises:

NotImplementedError – This method is not yet implemented.

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.

class stanbkt.models.MultiPriors(pi_b0_know_mu=<stanbkt.models.priors._UnsetType object>, pi_b0_know_std=<stanbkt.models.priors._UnsetType object>, pi_b1_know_mu=<stanbkt.models.priors._UnsetType object>, pi_b1_know_std=<stanbkt.models.priors._UnsetType object>, pi_sigma_lambda=<stanbkt.models.priors._UnsetType object>, use_defaults=True, learn_mu=<stanbkt.models.priors._UnsetType object>, learn_std=<stanbkt.models.priors._UnsetType object>, forget_mu=<stanbkt.models.priors._UnsetType object>, forget_std=<stanbkt.models.priors._UnsetType object>, guess_mu=<stanbkt.models.priors._UnsetType object>, guess_std=<stanbkt.models.priors._UnsetType object>, slip_mu=<stanbkt.models.priors._UnsetType object>, slip_std=<stanbkt.models.priors._UnsetType object>, pi_know_mu=<stanbkt.models.priors._UnsetType object>, pi_know_std=<stanbkt.models.priors._UnsetType object>)#

Bases: PriorsBase

Bayesian priors for joint estimation of initial knowledge and other parameters.

Adds b0 and b1 parameters for modeling the linear relationship between initial knowledge logit and additional data used in the InitKnowledgeStrategy.JOINT estimation strategy.

Parameters:
expected_class()#

Return the expected BKT model class type for these priors.

Return type:

type[BKTModelBase]

forget_mu: float | list[float] | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
forget_std: float | list[float] | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
static get_default_priors(estimation_type, return_none=False, n_groups=0)#

Return default priors dictionary used for MultiBKT parameters.

Parameters:

  • estimation_type (InitKnowledgeStrategy) – The strategy used for estimating initial knowledge, which determines which priors are relevant.

  • return_none (bool) – If True, return a dict with all keys set to None (improper and non-informative). If False, return a dict with default scalar values.

  • n_groups (int) – The number of groups used for the learn, forget, guess, and slip parameters.

Return type:

Union[dict[str, float | None], dict[str, list[float | None]]]

Notes

BKT specific priors are modeled as a Normal distributions with means and standard deviations specified on the logit scale for learn and forget probability parameters. Guess and slip are modeled on the half-logit scale to constrain them to [0, 0.5] on the probability scale.

In cases where estimation_type = stanbkt.models.model_types.InitKnowledgeStrategy.JOINT, the b0 and b1 parameters are modeled as Normal distributions. Additionally, the regression residuals is modeled as a positive-valued parameter (pi_sigma_lambda) with a Exponential prior.

A non-centered parameterization is used:

logit_pi_know ~ pi_b0_know + pi_b1_know * pretest + pi_sigma * logit_pi_know_z

Where,

  • pi_b0_know ~ Normal(pi_b0_know_mu, pi_b0_know_std)

  • pi_b1_know ~ Normal(pi_b1_know_mu, pi_b1_know_std)

  • pi_sigma ~ Exponential(pi_sigma_lambda)

  • logit_pi_know_z ~ N(0, 1).

This model is mathematically equivalent to:

logit_pi_know ~ Normal(pi_b0_know + pi_b1_know * pretest, pi_sigma)

but the former (non-centered) parameterization is computationally more efficient and has better convergence properties in Stan.

guess_mu: float | list[float] | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
guess_std: float | list[float] | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
classmethod key_names()#

Return all valid prior key names.

Return type:

tuple[str, ...]

learn_mu: float | list[float] | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
learn_std: float | list[float] | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_b0_know_mu: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_b0_know_std: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_b1_know_mu: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_b1_know_std: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_know_mu: float | list[float] | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_know_std: float | list[float] | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_sigma_lambda: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
slip_mu: float | list[float] | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
slip_std: float | list[float] | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
to_dict(estimation_type)#

Serialize priors to a dictionary.

Return type:

Union[dict[str, float | None], dict[str, list[float | None]]]

Parameters:

estimation_type (InitKnowledgeStrategy)

use_defaults: bool = True#
class stanbkt.models.StandardBKT(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: BKTModelBase

Bayesian Knowledge Tracing (BKT) model implementation.

This class implements the standard BKT model using Bayesian inference. It estimates population-level parameters pT, pF, pG, and pS for each knowledge component. For each KC, a separate Stan model is fitted independently.

Parameters:

  • fit_method (FitMethod) – The method to use for fitting the Stan model. Supported methods include: - FitMethod.MCMC: Markov Chain Monte Carlo sampling for full posterior inference. - FitMethod.MLE: Maximum Likelihood Estimation for point estimates of parameters. - FitMethod.VB: Variational Bayes for faster approximate inference. - FitMethod.PATHFINDER: Pathfinder variational approximation for fast inference.

  • individual_initial_knowledge (bool) – Whether to estimate individualized initial knowledge parameters for each student (True) or a single population-level initial knowledge parameter (False).

  • init_knowledge_strategy (InitKnowledgeStrategy) – Strategy for estimating initial knowledge when individual_initial_knowledge is True. This determines how the initial knowledge parameters are informed by the data: - InitKnowledgeStrategy.CORRECTNESS_ONLY: Initial knowledge is informed solely by the correctness of the first interaction for each student. - InitKnowledgeStrategy.JOINT: Initial knowledge is informed by both the correctness

  • verbose (VerbosityLevel) – Verbosity level for logging during fitting and prediction.

  • stan_compile_kwargs (dict | None) – Additional Stan compile options forwarded as stanc_options to cmdstanpy.CmdStanModel.

  • cpp_compile_kwargs (dict | None) – Additional C++ compile options forwarded as cpp_options to cmdstanpy.CmdStanModel.

Variables:

model (CmdStanModel) – The compiled Stan model.

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])

evaluate(**kwargs)#

Evaluate model performance (not yet implemented).

This method will provide evaluation metrics for the fitted model in a future release.

Returns:

Evaluation results (implementation pending).

Return type:

dict[str, Any]

Raises:

NotImplementedError – This method is not yet implemented.

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.

class stanbkt.models.StandardPriors(pi_b0_know_mu=<stanbkt.models.priors._UnsetType object>, pi_b0_know_std=<stanbkt.models.priors._UnsetType object>, pi_b1_know_mu=<stanbkt.models.priors._UnsetType object>, pi_b1_know_std=<stanbkt.models.priors._UnsetType object>, pi_sigma_lambda=<stanbkt.models.priors._UnsetType object>, use_defaults=True, learn_mu=<stanbkt.models.priors._UnsetType object>, learn_std=<stanbkt.models.priors._UnsetType object>, forget_mu=<stanbkt.models.priors._UnsetType object>, forget_std=<stanbkt.models.priors._UnsetType object>, guess_mu=<stanbkt.models.priors._UnsetType object>, guess_std=<stanbkt.models.priors._UnsetType object>, slip_mu=<stanbkt.models.priors._UnsetType object>, slip_std=<stanbkt.models.priors._UnsetType object>, pi_know_mu=<stanbkt.models.priors._UnsetType object>, pi_know_std=<stanbkt.models.priors._UnsetType object>)#

Bases: PriorsBase

Bayesian priors for the Standard BKT model parameters.

Stores prior specifications (means and standard deviations on logit scale) for the four core BKT parameters: prior knowledge (pi_know), learning rate (learn), forgetting rate (forget), guessing (guess), and slipping (slip).

Exclicitly passing None for a parameter indicates an improper and non-informative prior (Stan uses a uniform prior). If all parameters are left as None, the model will use non-informative priors for all parameters, which implies the MAP solllution will be equivalent to maximum likelihood estimation.

Each parameter can be specified as a scalar (standard model), a list of values (grouped model), or None (non-informative priors).

Guess and slip are modeled on the half-logit scale to constrain them to [0, 0.5]. All other parameters are modeled on the logit scale.

Parameters:

  • learn_mu (float | None | _UnsetType) – Prior mean for logit-scale learning rate.

  • learn_std (float | None | _UnsetType) – Prior std dev for logit-scale learning rate.

  • forget_mu (float | None | _UnsetType) – Prior mean for logit-scale forgetting rate.

  • forget_std (float | None | _UnsetType) – Prior std dev for logit-scale forgetting rate.

  • guess_mu (float | None | _UnsetType) – Prior mean for logit-scale guessing probability.

  • guess_std (float | None | _UnsetType) – Prior std dev for logit-scale guessing probability.

  • slip_mu (float | None | _UnsetType) – Prior mean for logit-scale slipping probability.

  • slip_std (float | None | _UnsetType) – Prior std dev for logit-scale slipping probability.

  • pi_know_mu (float | None | _UnsetType) – Prior mean for logit-scale initial knowledge probability.

  • pi_know_std (float | None | _UnsetType) – Prior std dev for logit-scale initial knowledge probability.

  • pi_b0_know_mu (float | None | _UnsetType) – Prior mean for the intercept (b0) in the linear regression of logit initial knowledge. Used only when estimation_type=:attr: InitKnowledgeStrategy.JOINT.

  • pi_b0_know_std (float | None | _UnsetType) – Prior std dev for the intercept (b0) in the linear regression of logit initial knowledge. Used only when estimation_type=:attr: stanbkt.models.model_types.InitKnowledgeStrategy.JOINT.

  • pi_b1_know_mu (float | None | _UnsetType) – Prior mean for the slope (b1) in the linear regression of logit initial knowledge. Used only when estimation_type=:attr: stanbkt.models.model_types.InitKnowledgeStrategy.JOINT.

  • pi_b1_know_std (float | None | _UnsetType) – Prior std dev for the slope (b1) in the linear regression of logit initial knowledge. Used only when estimation_type=:attr: stanbkt.models.model_types.InitKnowledgeStrategy.JOINT.

  • pi_sigma_lambda (float | None | _UnsetType) – Prior for the standard deviation of the linear regression residuals. Used only when estimation_type=:attr: stanbkt.models.model_types.InitKnowledgeStrategy.JOINT.

  • use_defaults (bool) – Whether to fill in missing prior values with defaults (True) or None (False). If True, any parameter not explicitly set will be filled with a default value. If False, any parameter not explicitly set will be set to None, indicating a non-informative uniform prior.

static expected_class()#

Return the expected BKT model class type for these priors.

Return type:

type[BKTModelBase]

forget_mu: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
forget_std: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
static get_default_priors(estimation_type, return_none=False, n_groups=0)#

Return default priors dictionary used for BKT parameters.

Parameters:

  • estimation_type (InitKnowledgeStrategy) – The strategy used for estimating initial knowledge, which determines which priors are relevant.

  • return_none (bool) – If True, return a dict with all keys set to None (improper and non-informative). If False, return a dict with default scalar values.

  • n_groups (int) – The number of groups for grouped models. This is kept here for signature consistency but is not used for the standard priors since the parameters are scalar.

Return type:

Union[dict[str, float | None], dict[str, list[float | None]]]

Notes

BKT specific priors are modeled as a Normal distributions with means and standard deviations specified on the logit scale for learn and forget probability parameters. Guess and slip are modeled on the half-logit scale to constrain them to [0, 0.5] on the probability scale.

In cases where estimation_type = stanbkt.models.model_types.InitKnowledgeStrategy.JOINT, the b0 and b1 parameters are modeled as Normal distributions. Additionally, the regression residuals is modeled as a positive-valued parameter (pi_sigma_lambda) with a Exponential prior.

A non-centered parameterization is used:

logit_pi_know ~ pi_b0_know + pi_b1_know * pretest + pi_sigma * logit_pi_know_z

Where,

  • pi_b0_know ~ Normal(pi_b0_know_mu, pi_b0_know_std)

  • pi_b1_know ~ Normal(pi_b1_know_mu, pi_b1_know_std)

  • pi_sigma ~ Exponential(pi_sigma_lambda)

  • logit_pi_know_z ~ N(0, 1).

This model is mathematically equivalent to:

logit_pi_know ~ Normal(pi_b0_know + pi_b1_know * pretest, pi_sigma)

but the former (non-centered) parameterization is computationally more efficient and has better convergence properties in Stan.

guess_mu: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
guess_std: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
classmethod key_names()#

Return all valid prior key names.

Return type:

tuple[str, ...]

learn_mu: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
learn_std: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_b0_know_mu: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_b0_know_std: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_b1_know_mu: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_b1_know_std: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_know_mu: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_know_std: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
pi_sigma_lambda: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
slip_mu: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
slip_std: float | None | _UnsetType = <stanbkt.models.priors._UnsetType object>#
to_dict(estimation_type)#

Serialize priors to a dictionary.

Return type:

Union[dict[str, float | None], dict[str, list[float | None]]]

Parameters:

estimation_type (InitKnowledgeStrategy)

use_defaults: bool = True#
stanbkt.models.predict_posterior(model, data, column_mapping=None, *, smoothed=False, backend='stan', output='draws', quantiles=None, stan_output=None, n_cores=1)#
Overloads:

  • model (BKTModelBase), data (pd.DataFrame), column_mapping (_ColumnMappingInput), smoothed (bool), backend (Literal[‘stan’, ‘numba’]), output (Literal[‘stan’]), quantiles (Optional[list[float]]), stan_output (Optional[dict[str, csp.CmdStanGQ]]), n_cores (int) → dict[str, csp.CmdStanGQ]

  • model (BKTModelBase), data (pd.DataFrame), column_mapping (_ColumnMappingInput), smoothed (bool), backend (Literal[‘stan’, ‘numba’]), output (Literal[‘draws’]), quantiles (Optional[list[float]]), stan_output (Optional[dict[str, csp.CmdStanGQ]]), n_cores (int) → dict[str, pd.DataFrame]

  • model (BKTModelBase), data (pd.DataFrame), column_mapping (_ColumnMappingInput), smoothed (bool), backend (Literal[‘stan’, ‘numba’]), output (Literal[‘summary’]), quantiles (Optional[list[float]]), stan_output (Optional[dict[str, csp.CmdStanGQ]]), n_cores (int) → pd.DataFrame

Parameters:
Return type:

dict[str, CmdStanGQ] | dict[str, DataFrame] | DataFrame

Public wrapper for posterior prediction workflows.

Parameters:

  • model (BKTModelBase) – Fitted model instance.

  • data (DataFrame) – Interaction data.

  • column_mapping (Union[Mapping[ColumnNames, str], Mapping[str, str], Mapping[ColumnNames | str, str], None]) – Mapping from expected column names to source data names.

  • smoothed (bool) – Whether to use smoothed posterior hidden-state prediction models.

  • backend (Literal['stan', 'numba']) – Prediction backend. stan uses generated quantities. numba runs deterministic hidden-state recursion for each posterior parameter draw.

  • output (Literal['stan', 'draws', 'summary']) – Desired output type.

  • quantiles (Optional[list[float]]) – Quantiles used for summary output.

  • stan_output (Optional[dict[str, CmdStanGQ]]) – Precomputed Stan generated quantities output.

  • n_cores (int) – Number of cores used for summary processing.

Return type:

dict[str, CmdStanGQ] | dict[str, DataFrame] | DataFrame

On this page