adaptivetesting 1.0.0__py3-none-any.whl

adaptivetesting/__init__.py

@@ -0,0 +1,7 @@
+from . import data
+from . import implementations
+from . import math
+from . import models
+from . import services
+from . import simulation
+from . import tests

adaptivetesting/data/__init__.py

@@ -0,0 +1,2 @@
+from .__pickle_context import PickleContext
+from .__sqlite_context import SQLiteContext

adaptivetesting/data/__pickle_context.py

@@ -0,0 +1,51 @@
+from typing import List
+import pickle
+import pathlib
+from ..models.__test_result import TestResult
+from ..services.__test_results_interface import ITestResults
+
+
+class PickleContext(ITestResults):
+    def __init__(self,
+                 simulation_id: str,
+                 participant_id: int):
+        """Implementation of the ITestResults interface for
+        saving test results to the pickle format.
+        The resulting pickle file <simulation_id>.pickle
+        will be of the standard pickle format which depends
+        on the used python version.
+
+        Args:
+            simulation_id (str): Not used but required by the interface
+
+            participant_id (int): participant id and table name
+        """
+        super().__init__(simulation_id, participant_id)
+
+    def save(self, test_results: List[TestResult]) -> None:
+        """Saves a list of test results to a pickle binary file
+        (<participant_id>.pickle).
+
+        Args:
+            test_results (List[TestResult]): list of test results
+        """
+        dir_name = self.simulation_id
+
+        # create directory if it does not already exist
+        path = pathlib.Path(f"data/{dir_name}")
+        path.mkdir(parents=True, exist_ok=True)
+        # write results in file
+        with open(f"data/{dir_name}/{str(self.participant_id)}.pickle", "wb") as file:
+            pickle.dump(test_results, file)
+            file.close()
+
+    def load(self) -> List[TestResult]:
+        """Loads results from the database.
+        The implementation of this method is required
+        by the interface. However, is does not have
+        any implemented functionality and will throw an error
+        if used.
+
+        Returns: List[TestResult]
+        """
+        raise NotImplementedError("This  function is not implemented.")

adaptivetesting/data/__sqlite_context.py

@@ -0,0 +1,76 @@
+from typing import List
+from ..models.__adaptive_test import AdaptiveTest
+from ..models.__test_result import TestResult
+from ..services.__test_results_interface import ITestResults
+import sqlite3
+
+
+class SQLiteContext(ITestResults):
+    def __init__(self, simulation_id: str, participant_id: int):
+        """Implementation of the ITestResults interface for
+        saving test results to a SQLITE database.
+        The resulting sqlite file <simulation_id>.db
+        will be of the SQLITE3 format.
+
+        Args:
+            simulation_id (str): db filename
+
+            participant_id (int): participant id and table name
+        """
+        super().__init__(simulation_id, participant_id)
+
+    def save(self, test_results: List[TestResult]) -> None:
+        """Saves a list of test results to the database
+        in the table <participant_id>.
+
+        Args:
+            test_results (List[TestResult]): list of test results
+        """
+
+
+        try:
+            con = sqlite3.connect(self.filename)
+        except sqlite3.OperationalError:
+            con = sqlite3.connect(f"../{self.filename}")
+
+        cur: sqlite3.Cursor = con.cursor()
+        # create table
+        self._create_table(cur)
+        # insert test results into table
+        for result in test_results:
+            sql_query = f"""
+            INSERT INTO p_{self.participant_id}
+            VALUES ("{result.test_id}", {result.ability_estimation}, {result.standard_error},
+            {result.showed_item}, {result.response}, {result.true_ability_level})"""
+            cur.execute(sql_query)
+        # commit changes
+        con.commit()
+        # close connection
+        con.close()
+
+    def load(self) -> List[TestResult]:
+        """Loads results from the database.
+        The implementation of this method is required
+        by the interface. However, is does not have
+        any implemented functionality and will throw an error.
+
+        Returns: List[TestResult]
+        """
+        raise NotImplementedError("This  function is not implemented.")
+
+    def _create_table(self, cur: sqlite3.Cursor) -> None:
+        """Creates a table in the database with the
+        name <participant_id> if it does not exist.
+
+        Args:
+            cur (sqlite3.Cursor): database cursor
+        """
+        sql_query = f"""CREATE TABLE IF NOT EXISTS p_{self.participant_id} (
+            test_id,
+            ability_estimation,
+            standard_error,
+            showed_item,
+            response,
+            true_ability_level
+            )"""
+        cur.execute(sql_query)

adaptivetesting/implementations/__default_implementation.py

@@ -0,0 +1,72 @@
+from typing import List
+from ..models.__adaptive_test import AdaptiveTest
+from ..models.__item_pool import ItemPool
+from ..models.__algorithm_exception import AlgorithmException
+from ..math.estimators.__ml_estimation import MLEstimator
+
+
+class DefaultImplementation(AdaptiveTest):
+    """This class represents the Default implementation using
+    Maximum Likelihood Estimation and Urry's rule during the test."""
+    def __init__(self, item_pool: ItemPool,
+                 simulation_id: str,
+                 participant_id: int,
+                 true_ability_level: float,
+                 initial_ability_level: float = 0,
+                 simulation=True,
+                 debug=False):
+        """
+        Args:
+            item_pool (ItemPool): item pool used for the test
+
+            simulation_id (str): simulation id
+
+            participant_id (int): participant id
+
+            true_ability_level (float): true ability level (must always be set)
+
+            initial_ability_level (float): initially assumed ability level
+
+            simulation (bool): will the test be simulated
+
+            debug (bool): enables debug mode
+
+        """
+        super().__init__(item_pool,
+                         simulation_id,
+                         participant_id,
+                         true_ability_level,
+                         initial_ability_level,
+                         simulation,
+                         debug)
+
+    def estimate_ability_level(self) -> float:
+        """
+        Estimates latent ability level using ML.
+        If responses are only 1 or 0,
+        the ability will be set to one
+        of the boundaries of the estimation interval (`[-10,10]`).
+        
+        Returns:
+            float: ability estimation
+        """
+        estimator = MLEstimator(
+            self.response_pattern,
+            self.get_answered_items()
+        )
+        estimation: float = float("NaN")
+        try:
+            estimation = estimator.get_estimation()
+        except AlgorithmException as exception:
+            # check if all responses are the same
+            if len(set(self.response_pattern)) == 1:
+                if self.response_pattern[0] == 0:
+                    estimation = -10
+                elif self.response_pattern[0] == 1:
+                    estimation = 10
+
+            else:
+                raise AlgorithmException("""Something else
+                when wrong when running MLE""") from exception
+
+        return estimation

adaptivetesting/implementations/__init__.py

@@ -0,0 +1,3 @@
+from .__default_implementation import DefaultImplementation
+from .__pre_test import PreTest
+from .__semi_implementation import SemiAdaptiveImplementation

adaptivetesting/implementations/__pre_test.py

@@ -0,0 +1,83 @@
+from typing import List
+import jax.numpy as np
+from ..models.__test_item import TestItem
+import random
+
+
+class PreTest:
+    def __init__(self, items: List[TestItem], seed: int | None = None):
+        """
+        The pretest class can be used to draw items randomly from
+        difficulty quantiles
+        of the item pool.
+
+        Args:
+            items: Item pool
+
+            seed (int): A seed for the item selection can be provided.
+                If not, the item selection will be drawn randomly, and you will not be able
+                to reproduce the results.
+
+        """
+        self.items = items
+        self.seed = seed
+
+    def calculate_quantiles(self) -> np.ndarray:
+        """Calculates quantiles 0.25, 0.5, 0.75
+        """
+        # get difficulties
+        difficulties: List[float] = [item.b for item in self.items]
+
+        quantiles = np.array([])
+        # calculate quantiles
+        for q in [0.25, 0.5, 0.75]:
+            quantile: np.ndarray = np.quantile(np.array(difficulties), q)
+            quantiles = np.append(quantiles, quantile)
+
+        return quantiles
+
+    def select_item_in_interval(self, lower: float, upper: float) -> TestItem:
+        """Draws item from a pool in the specified interval.
+        The item difficulty is > than the lower limit and <= the higher limit.
+
+        Args:
+            lower (float): Lower bound of the item difficulty interval.
+            
+            upper (float): Upper bound of the item difficulty interval.
+
+        Returns:
+            TestItem: Selected item.
+        """
+        # select only items with difficulty in interval
+        items_in_interval: List[TestItem] = [item for item in list(self.items) if lower < item.b <= upper]
+        # draw one item randomly
+        if self.seed is not None:
+            random.seed(self.seed)
+        item = random.sample(items_in_interval, 1)[0]
+        return item
+
+    def select_random_item_quantile(self) -> List[TestItem]:
+        """Selects a random item from the 0.25, 0.5 and 0.75 quantiles.
+
+        Returns:
+            List[TestItem]: Selected item.
+        """
+        selected_items: List[TestItem] = []
+        # create difficulties array
+        difficulties = np.array([item.b for item in self.items])
+        # add minimum and maximum difficulty values to
+        # the quantiles list for correct item selection
+        quantiles = [difficulties.min()]
+        quantiles.extend(list(self.calculate_quantiles()))
+        quantiles.extend([difficulties.max()])
+
+        for i in range(len(quantiles)-1):
+            selected_item = self.select_item_in_interval(
+                    lower=float(quantiles[i]),
+                    upper=float(quantiles[i+1])
+            )
+
+            selected_items.append(selected_item)
+
+        # return
+        return selected_items

adaptivetesting/implementations/__semi_implementation.py

@@ -0,0 +1,134 @@
+from typing import List
+from ..models.__adaptive_test import AdaptiveTest
+from ..models.__item_pool import ItemPool
+from ..models.__algorithm_exception import AlgorithmException
+from ..models.__test_result import TestResult
+from ..math.estimators.__ml_estimation import MLEstimator
+from .__pre_test import PreTest
+
+
+class SemiAdaptiveImplementation(AdaptiveTest):
+
+    def __init__(self,
+                 item_pool: ItemPool,
+                 simulation_id: str,
+                 participant_id: int,
+                 true_ability_level: float,
+                 initial_ability_level: float = 0,
+                 simulation=True,
+                 debug=False,
+                 pretest_seed=12345):
+        """
+        This class represents the Semi-Adaptive implementation using
+        Maximum Likelihood Estimation and Urry's rule during the test.
+        The pretest is 4 items long.
+
+        Args:
+            item_pool (ItemPool): item pool used for the test
+
+            simulation_id (str): simulation id
+
+            participant_id (int): participant id
+
+            true_ability_level (float): true ability level (must always be set)
+
+            initial_ability_level (float): initially assumed ability level
+
+            simulation (bool): will the test be simulated
+
+            debug (bool): enables debug mode
+
+            pretest_seed (int): seed used for the random number generator to draw pretest items.
+
+        """
+
+        super().__init__(item_pool,
+                         simulation_id,
+                         participant_id,
+                         true_ability_level,
+                         initial_ability_level,
+                         simulation,
+                         debug)
+
+        self.pretest_seed = pretest_seed
+
+    def estimate_ability_level(self) -> float:
+        """
+        Estimates latent ability level using ML.
+        If responses are only 1 or 0,
+        the ability will be set to one
+        of the boundaries of the estimation interval (`[-10,10]`).
+
+        Returns:
+            float: ability estimation
+        """
+        estimator = MLEstimator(
+            self.response_pattern,
+            self.get_answered_items()
+        )
+        estimation: float = float("NaN")
+        try:
+            estimation = estimator.get_estimation()
+        except AlgorithmException as exception:
+            # check if all responses are the same
+            if len(set(self.response_pattern)) == 1:
+                if self.response_pattern[0] == 0:
+                    estimation = -10
+                elif self.response_pattern[0] == 1:
+                    estimation = 10
+
+            else:
+                raise AlgorithmException("""Something else
+                    when wrong when running MLE""") from exception
+
+        return estimation
+
+    def pre_test(self):
+        """Runs pretest"""
+        # create test instance
+        pretest = PreTest(
+            items=self.item_pool.test_items,
+            seed=self.pretest_seed
+        )
+        # get selected items
+        random_items = pretest.select_random_item_quantile()
+
+        # get responses
+        for item in random_items:
+            response = self.item_pool.get_item_response(item)
+            # add response to response pattern
+            self.response_pattern.append(response)
+            # add item to answered items list
+            self.answered_items.append(item)
+
+        # remove random items from item pool
+        for item in random_items:
+            self.item_pool.delete_item(item)
+
+        # estimate ability level
+        estimation = self.estimate_ability_level()
+        self.ability_level = estimation
+
+        # create test results for all n-1 random items
+        for i in range(0, len(random_items) - 1):
+            result = TestResult(
+                ability_estimation=float("nan"),
+                standard_error=float("nan"),
+                showed_item=random_items[i].b,
+                response=self.response_pattern[i],
+                test_id=self.simulation_id,
+                true_ability_level=self.true_ability_level,
+            )
+            # append to memory
+            self.test_results.append(result)
+
+        # create test result for first ability estimation
+        intermediate_result = TestResult(
+            ability_estimation=self.ability_level,
+            standard_error=self.get_ability_se(),
+            showed_item=random_items[-1].b,
+            response=self.response_pattern[-1],
+            test_id=self.simulation_id,
+            true_ability_level=self.true_ability_level,
+        )
+        self.test_results.append(intermediate_result)

adaptivetesting/math/__init__.py

@@ -0,0 +1,2 @@
+from .__standard_error import standard_error
+from .__test_information import test_information_function

adaptivetesting/math/__standard_error.py

@@ -0,0 +1,59 @@
+import math
+from typing import List, Literal
+import jax.numpy as np
+from .__test_information import test_information_function
+from ..models.__test_item import TestItem
+
+
+def standard_error(answered_items: List[TestItem],
+                   estimated_ability_level: float,
+                   estimator: Literal["ML", "BM"] = "ML",
+                   sd: float | None = None) -> float:
+    """Calculates the standard error using the test information function.
+    If Bayes Modal is used for the ability estimation, a standard deviation value
+    of the prior distribution has to be provided.
+
+    Args:
+        answered_items (List[float]): List of answered items
+
+        estimated_ability_level (float): Currently estimated ability level
+
+        estimator (Literal["ML", "BM"]): Ability estimator (Default: ML)
+
+        sd (float | None): Standard deviation of the prior distribution. Only required for BM.
+
+    Raises:
+        ValueError
+    
+    Returns:
+        float: Standard error
+    """
+    a=np.array([item.a for item in answered_items])   
+    b=np.array([item.b for item in answered_items])
+    c=np.array([item.c for item in answered_items])
+    d=np.array([item.d for item in answered_items])
+
+    if estimator == "ML":
+        error = 1 / math.sqrt(test_information_function(mu=np.array(estimated_ability_level),
+                                                        a=a,
+                                                        b=b,
+                                                        c=c,
+                                                        d=d
+                                                        ))
+
+        return error
+    
+    if estimator == "BM":
+        information = test_information_function(mu=np.array(estimated_ability_level),
+                                                        a=a,
+                                                        b=b,
+                                                        c=c,
+                                                        d=d)
+        if sd is None:
+            raise ValueError("sd cannot be None if BM is used as estimator.")
+        
+        error = 1 / math.sqrt(
+            (1 / math.pow(sd, 2)) + information
+        )
+
+        return error

adaptivetesting/math/__test_information.py

@@ -0,0 +1,43 @@
+import jax.numpy as np
+from .estimators.__functions.__estimators import probability_y1, probability_y0
+from jax import jit, grad
+from scipy.differentiate import derivative
+
+
+
+def test_information_function(
+            mu: np.ndarray,
+               a: np.ndarray, 
+               b: np.ndarray, 
+               c: np.ndarray, 
+               d: np.ndarray, 
+) -> float:
+    """
+    Calculates test information.
+
+    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:
+        float: test information
+
+    """
+    p_y1 = probability_y1(mu, a, b, c, d)
+    
+    p_y1_grad = derivative(probability_y1, 
+                           mu,
+                           args=(a, b, c, d))
+    
+    
+
+    product = (p_y1_grad.df ** 2) / (p_y1 * (1 - p_y1))
+    information_tensor = np.cumsum(product)
+    # print(f"Information tensor: {information_tensor}")
+    information = information_tensor[len(information_tensor) - 1]
+    # convert information to float and return
+    return float(information)
+