-
Notifications
You must be signed in to change notification settings - Fork 1
API math
adaptivetesting.math.generate_response_pattern(ability: float, items: list[TestItem], seed: int | None = None) → list[int]
Generates a response pattern for a given ability level and item difficulties. Also, a seed can be set.
Args: : ability (float): participants ability items (list[TestItem]): test items seed (int, optional): Seed for the random process.
Returns: : list[int]: response pattern
class adaptivetesting.math.estimators.BayesModal(response_pattern: List[int] | ndarray, items: List[TestItem], prior: Prior, optimization_interval: Tuple[float, float] = (-10, 10))
Bases: IEstimator
This class can be used to estimate the current ability level of a respondent given the response pattern and the corresponding item difficulties.
This type of estimation finds the maximum of the posterior distribution.
Args:
: response_pattern (List[int] | np.ndarray ): list of response patterns (0: wrong, 1:right)
items (List[TestItem]): list of answered items
prior (Prior): prior distribution
optimization_interval (Tuple[float, float]): interval used for the optimization function
Estimate the current ability level using Bayes Modal. The bounded optimizer is used to get the ability estimate.
Raises: : AlgorithmException: Raised when maximum could not be found.
Returns: : float: ability estimation
Calculates the standard error for the given estimated ability level.
Args: : estimation (float): currently estimated ability level
Returns: : float: standard error of the ability estimation
class adaptivetesting.math.estimators.CustomPrior(random_variable: rv_continuous, *args: float, loc: float = 0, scale: float = 1)
Bases: Prior
This class is for using a custom prior in the ability estimation in Bayes Modal or Expected a Posteriori. Any continuous, univariate random variable from the scipy.stats module can be used. However, you have to consult to the scipy documentation for the required parameters for the probability density function (pdf) of that particular random variable.
Args:
: random_variable (rv_continuous): Any continuous, univariate random variable from the scipy.stats module.
*
args (float): Custom parameters required to calculate the pdf of that specific random variable.
loc (float, optional): Location parameter. Defaults to 0.
scale (float, optional): Scale parameter. Defaults to 1.
Probability density function for a prior distribution
Args: : x (float | np.ndarray): point at which to calculate the function value
Returns: : ndarray: function value
Bases: Exception
This exception can be used is the custom prior is not correctly specified.
It is usually raised if a non-normal prior is used that was not correctly inherited from the CustomPrior class.
Bases: Prior
A prior distribution constructed from empirical samples using a kernel density estimate (KDE). This class wraps scipy.stats.gaussian_kde to provide a nonparametric prior estimated from observed data. The KDE is built from the provided dataset at initialization and used to evaluate the probability density (pdf) at query points.
dataset : Samples used to fit the prior. For univariate data this can be a 1-D array of shape (n_samples,). For multivariate data, provide an array of shape (d, n_samples) (as expected by scipy.stats.gaussian_kde) or an array that can be transposed to that shape. The dataset must contain at least one sample.
kde : The fitted kernel density estimator built from the provided dataset.
Args: : dataset (np.ndarray): Samples used to fit the prior. For univariate data this can be a 1-D array of : shape (n_samples,). For multivariate data, provide an array of shape (d, n_samples) (as expected by scipy.stats.gaussian_kde) or an array that can be transposed to that shape. The dataset must contain at least one sample.
Evaluate the estimated probability density at x. Accepts inputs compatible with scipy.stats.gaussian_kde._call_: for univariate data x can be a float, 1-D array of points, or similarly shaped array for multivariate queries.
Args: : x (float | np.ndarray): point at which to evaluate the pdf
Raises:
: ValueError:
: If dataset is empty.
numpy.linalg.LinAlgError:
: If the covariance estimate used by gaussian_kde is singular (this is raised by
scipy’s implementation when the data are degenerate).
class adaptivetesting.math.estimators.ExpectedAPosteriori(response_pattern: list[int] | ndarray, items: list[TestItem], prior: Prior, optimization_interval: tuple[float, float] = (-10, 10))
Bases: BayesModal
This class can be used to estimate the current ability level of a respondent given the response pattern and the corresponding item difficulties.
This type of estimation finds the mean of the posterior distribution.
Args:
: response_pattern (List[int] | np.ndarray): list of response patterns (0: wrong, 1:right)
items (List[TestItem]): list of answered items
prior (Prior): prior distribution
optimization_interval (Tuple[float, float]): interval used for the optimization function
Estimate the current ability level using EAP.
Returns: : float: ability estimation
Calculates the standard error for the items used at the construction of the class instance (answered items). The currently estimated ability level is required as parameter.
Args: : estimated_ability (float): _description_
Returns: : float: standard error of the ability estimation
class adaptivetesting.math.estimators.MLEstimator(response_pattern: List[int] | ndarray, items: List[TestItem], optimization_interval: Tuple[float, float] = (-10, 10), **kwargs)
Bases: IEstimator
This class can be used to estimate the current ability level of a respondent given the response pattern and the corresponding item parameters. The estimation uses Maximum Likelihood Estimation.
Args:
: response_pattern (List[int]): list of response patterns (0: wrong, 1:right)
items (List[TestItem]): list of answered items
Estimate the current ability level by searching for the maximum of the likelihood function. A line-search algorithm is used.
Returns: : float: ability estimation
Calculates the standard error for the given estimated ability level.
Args: : estimation (float): currently estimated ability level
Returns: : float: standard error of the ability estimation
Bases: Prior
Normal distribution as prior for Bayes Modal or EAP estimation
Args:
: mean (float): mean of the distribution
sd (float): standard deviation of the distribution
Probability density function for a prior distribution
Args: : x (float | np.ndarray): point at which to calculate the function value
Returns: : ndarray: function value
Bases: ABC
Base class for prior distributions
Probability density function for a prior distribution
Args: : x (float | np.ndarray): point at which to calculate the function value
Returns: : ndarray: function value
Bases: Prior
Skew normal distribution as prior for Bayes Modal or EAP estimation
Args:
: loc (float): location parameter
scale (float): scale parameter
Probability density function for a prior distribution
Args: : x (float | np.ndarray): point at which to calculate the function value
Returns: : ndarray: function value
adaptivetesting.math.estimators.item_information_function(mu: ndarray, a: ndarray, b: ndarray, c: ndarray, d: ndarray) → ndarray
Calculates the item information for given parameters.
Args: : mu (np.ndarray): ability level a (np.ndarray): discrimination parameter b (np.ndarray): difficulty parameter c (np.ndarray): guessing parameter d (np.ndarray): slipping parameter
Returns: : np.ndarray: item information
adaptivetesting.math.estimators.likelihood(mu: ndarray, a: ndarray, b: ndarray, c: ndarray, d: ndarray, response_pattern: ndarray) → ndarray
Likelihood function of the 4-PL model. For optimization purposes, the function returns the negative value of the likelihood function. To get the real value, multiply the result by -1.
Args: : mu (np.ndarray): ability level a (np.ndarray): item discrimination parameter b (np.ndarray): item difficulty parameter c (np.ndarray): pseudo guessing parameter d (np.ndarray): inattention parameter response_pattern (np.ndarray): response pattern of the answered items
Returns: : float: negative likelihood value of given ability value
adaptivetesting.math.estimators.maximize_likelihood_function(a: ndarray, b: ndarray, c: ndarray, d: ndarray, response_pattern: ndarray, border: tuple[float, float] = (-10, 10)) → float
Find the ability value that maximizes the likelihood function. This function uses the minimize_scalar function from scipy and the “bounded” method.
Args:
: a (np.ndarray): item discrimination parameter
b (np.ndarray): item difficulty parameter
c (np.ndarray): pseudo guessing parameter
d (np.ndarray): inattention parameter
response_pattern (np.ndarray): response pattern of the item
border (tuple[float, float], optional): border of the optimization interval.
Defaults to (-10, 10).
Raises:
: AlgorithmException: if the optimization fails or the response
: pattern consists of only one type of response.
AlgorithmException: if the optimization fails or the response
: pattern consists of only one type of response.
Returns: : float: optimized ability value
adaptivetesting.math.estimators.maximize_posterior(a: ndarray, b: ndarray, c: ndarray, d: ndarray, response_pattern: ndarray, prior: Prior, optimization_interval: tuple[float, float] = (-10, 10)) → float
Get the maximum of the posterior distribution
Args: : a (np.ndarray): item parameter a b (np.ndarray): item parameter b c (np.ndarray): item parameter c d (np.ndarray): item parameter d response_pattern (np.ndarray): response pattern (simulated or user generated) prior (Prior): prior distribution optimization_interval (Tuple[float, float]): interval used for the optimization function
Returns: : float: Bayes Modal estimator for the given parameters
adaptivetesting.math.estimators.prior_information_function(prior: Prior, optimization_interval: tuple[float, float] = (-10, 10)) → ndarray
Calculates the fisher information for the probability density function of the specified prior
Args:
: prior (Prior): prior distribution
optimization_interval (tuple[float, float], optional): interval used for numerical integration.
Defaults to (-10, 10).
Returns: : np.ndarray: calculated fisher information of the prior
adaptivetesting.math.estimators.probability_y0(mu: ndarray, a: ndarray, b: ndarray, c: ndarray, d: ndarray) → ndarray
Probability of getting the item wrong given the ability level.
Args: : mu (np.ndarray): latent ability level a (np.ndarray): item discrimination parameter b (np.ndarray): item difficulty parameter c (np.ndarray): pseudo guessing parameter d (np.ndarray): inattention parameter
Returns: : np.ndarray: probability of getting the item wrong
adaptivetesting.math.estimators.probability_y1(mu: ndarray, a: ndarray, b: ndarray, c: ndarray, d: ndarray) → ndarray
Probability of getting the item correct given the ability level.
Args: : mu (np.ndarray): latent ability level a (np.ndarray): item discrimination parameter b (np.ndarray): item difficulty parameter c (np.ndarray): pseudo guessing parameter d (np.ndarray): inattention parameter
Returns: : np.ndarray: probability of getting the item correct
adaptivetesting.math.estimators.test_information_function(mu: ndarray, a: ndarray, b: ndarray, c: ndarray, d: ndarray, prior: Prior | None = None, optimization_interval: tuple[float, float] = (-10, 10)) → float
Calculates test information. Therefore, the information is calculated for every item and then summed up. If a prior is specified, the fisher information of the prior is calculated as well and added to the information sum.
Args: : mu (np.ndarray): ability level a (np.ndarray): discrimination parameter b (np.ndarray): difficulty parameter c (np.ndarray): guessing parameter d (np.ndarray): slipping parameter prior (Prior | None, optional): prior distribution. Defaults to None. optimization_interval (tuple[float, float], optional): interval used for numerical integration.
Returns: : float: test information
adaptivetesting.math.item_selection.maximum_information_criterion(items: list[TestItem], ability: float) → TestItem
The maximum information criterion selected the next item for the respondent by finding the item that has the highest information value.
Args: : items (list[TestItem]): list of available items ability (float): currently estimated ability
Returns: : TestItem: item that has the highest information value
Raises: : ItemSelectionException: raised if no appropriate item was found AlgorithmException: raised if test information function could not be calculated
Urry’s rule selects the test item which has the minimal difference between the item’s difficulty and the ability level.
Args:
: items (List[TestItem]): Test items (item pool)
ability (float): Ability level (current ability estimation)
Returns: : TestItem: selected test item
Getting Started
Tutorials
API Reference