adaptivetesting 1.1.1__tar.gz → 1.1.3__tar.gz

adaptivetesting-1.1.3/.github/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing Guidelines
+
+Thank you for your interest in contributing!
+
+- All pull requests **must** be opened against the `dev` branch.
+- Ensure your code passes all test workflows:
+    - `mypy` (type checking)
+    - `flake8` (linting)
+    - Unit tests
+
+Pull requests that meet these requirements will be considered for merging.

adaptivetesting-1.1.3/.readthedocs.yml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+python:
+    install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt
+        

adaptivetesting-1.1.3/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Version 1.1.2
+
+- The `ItemPool` class now correctly honors the `id` field of items. (#30, #31)
+- Examples and the readme file have been updated accordingly.

{adaptivetesting-1.1.1 → adaptivetesting-1.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adaptivetesting
-Version: 1.1.1
+Version: 1.1.3
 Summary: adaptivetesting is a Python package that can be used to simulate and evaluate custom CAT scenarios as well as implement them in real-world testing scenarios from a single codebase
 Project-URL: Homepage, https://github.com/condecon/adaptivetesting
 Project-URL: Documentation, https://github.com/condecon/adaptivetesting/tree/main/docs
@@ -29,7 +29,7 @@ Description-Content-Type: text/markdown
 - **Bayesian Methods**: Built-in support for Bayesian ability estimation with customizable priors
 - **Flexible Architecture**: Object-oriented design with abstract classes for easy extension
 - **Item Response Theory**: Full support for 1PL, 2PL, 3PL, and 4PL models
-- **Multiple Estimators**: 
+- **Multiple Estimators**:
   - Maximum Likelihood Estimation (MLE)
   - Bayesian Modal Estimation (BM)
   - Expected A Posteriori (EAP)
@@ -131,25 +131,31 @@ adaptive_test = TestAssembler(
 ### Real-world Testing (Non-simulation) with PsychoPy
 
 ```python
+# setup item pool
+# the item pool is retrieved from the PREVIC
+# https://github.com/manuelbohn/previc/tree/main/saves
+import pandas as pd
+from adaptivetesting.models import ItemPool
 from psychopy import visual, event
 from psychopy.hardware import keyboard
 from adaptivetesting.implementations import TestAssembler
 from adaptivetesting.models import AdaptiveTest, ItemPool, TestItem
 from adaptivetesting.data import CSVContext
-from adaptivetesting.math.estimators import BayesModal, CustomPrior
+from adaptivetesting.math.estimators import ExpectedAPosteriori, CustomPrior
 from adaptivetesting.math.item_selection import maximum_information_criterion
 from scipy.stats import t
 import pandas as pd
 
+previc_item_pool = pd.read_csv("item_pool.csv")
+# add item column
+previc_item_pool["id"] = list(range(1, 90))
+previc_item_pool.head()
 
-# Create item pool from DataFrame
-items_data = pd.DataFrame({
-    "a": [1.32, 1.07, 0.84, 1.19, 0.95],  # discrimination
-    "b": [-0.63, 0.18, -0.84, 0.41, -0.25],  # difficulty
-    "c": [0.17, 0.10, 0.19, 0.15, 0.12],  # guessing
-    "d": [0.87, 0.93, 1.0, 0.89, 0.94]   # upper asymptote
-})
-item_pool = ItemPool.load_from_dataframe(items_data)
+
+item_pool = ItemPool.load_from_list(
+    b=previc_item_pool["Difficulty"],
+    ids=previc_item_pool["id"]
+)
 
 # Create adaptive test
 adaptive_test: AdaptiveTest = TestAssembler(
@@ -179,12 +185,12 @@ win = visual.Window([800, 600],
 # init keyboard
 keyboard.Keyboard()
 
+## FIX THIS
 
 # define function to get user input
 def get_response(item: TestItem) -> int:
-    # get index
-    item_difficulty: float = item.b
-    stimuli: str = [item for item in item_pool.test_items if item["Difficulty"] == item_difficulty][0]["word"]
+    # select corresponding word from item pool data frame
+    stimuli: str = previc_item_pool[previc_item_pool["id"] == item.id]["word"].values[0]
 
     # create text box and display stimulus
     text_box = visual.TextBox2(win=win,
@@ -309,17 +315,18 @@ adaptive_test = TestAssembler(
 Full documentation is available in the `docs/` directory:
 
 - [API Reference](docs/readme.md)
-- [Models Module](docs/adaptivetesting.models.md)
-- [Math Module](docs/adaptivetesting.math.md)
-- [Implementation Examples](docs/adaptivetesting.implementations.md)
-- [Simulation Guide](docs/adaptivetesting.simulation.md)
+- [Models Module](docs/models.md)
+- [Math Module](docs/math.md)
+- [Implementation Examples](docs/implementations.md)
+- [Simulation Guide](docs/simulation.md)
 
 ## Testing
 
 The package includes comprehensive tests. Run them using:
 
 ```bash
-python -m pytest adaptivetesting/tests/
+uv sync
+uv run python -m unittest
 ```
 
 ## Contributing
@@ -327,7 +334,7 @@ python -m pytest adaptivetesting/tests/
 We welcome contributions! Please see our [GitHub repository](https://github.com/condecon/adaptivetesting) for:
 
 - Issue tracking
-- Feature requests  
+- Feature requests
 - Pull request guidelines
 - Development setup
 
@@ -343,6 +350,22 @@ This package is designed for researchers and practitioners in:
 
 The package facilitates the transition from research simulation to real-world testing applications without requiring major code modifications.
 
+## Citation
+If you use this package for your academic work, please provide the following reference:
+Engicht, J., Bee, R. M., & Koch, T. (2025). Customizable Bayesian Adaptive Testing with Python – The adaptivetesting Package. Open Science Framework. https://doi.org/10.31219/osf.io/d2xge_v1
+
+```
+@online{engichtCustomizableBayesianAdaptive2025,
+  title = {Customizable {{Bayesian Adaptive Testing}} with {{Python}} – {{The}} Adaptivetesting {{Package}}},
+  author = {Engicht, Jonas and Bee, R. Maximilian and Koch, Tobias},
+  date = {2025-08-06},
+  eprinttype = {Open Science Framework},
+  doi = {10.31219/osf.io/d2xge_v1},
+  url = {https://osf.io/d2xge_v1},
+  pubstate = {prepublished}
+}
+```
+
 ## License
 
 This project is licensed under the terms specified in the [LICENSE](LICENSE) file.

{adaptivetesting-1.1.1 → adaptivetesting-1.1.3}/README.md

@@ -11,7 +11,7 @@
 - **Bayesian Methods**: Built-in support for Bayesian ability estimation with customizable priors
 - **Flexible Architecture**: Object-oriented design with abstract classes for easy extension
 - **Item Response Theory**: Full support for 1PL, 2PL, 3PL, and 4PL models
-- **Multiple Estimators**: 
+- **Multiple Estimators**:
   - Maximum Likelihood Estimation (MLE)
   - Bayesian Modal Estimation (BM)
   - Expected A Posteriori (EAP)
@@ -113,25 +113,31 @@ adaptive_test = TestAssembler(
 ### Real-world Testing (Non-simulation) with PsychoPy
 
 ```python
+# setup item pool
+# the item pool is retrieved from the PREVIC
+# https://github.com/manuelbohn/previc/tree/main/saves
+import pandas as pd
+from adaptivetesting.models import ItemPool
 from psychopy import visual, event
 from psychopy.hardware import keyboard
 from adaptivetesting.implementations import TestAssembler
 from adaptivetesting.models import AdaptiveTest, ItemPool, TestItem
 from adaptivetesting.data import CSVContext
-from adaptivetesting.math.estimators import BayesModal, CustomPrior
+from adaptivetesting.math.estimators import ExpectedAPosteriori, CustomPrior
 from adaptivetesting.math.item_selection import maximum_information_criterion
 from scipy.stats import t
 import pandas as pd
 
+previc_item_pool = pd.read_csv("item_pool.csv")
+# add item column
+previc_item_pool["id"] = list(range(1, 90))
+previc_item_pool.head()
 
-# Create item pool from DataFrame
-items_data = pd.DataFrame({
-    "a": [1.32, 1.07, 0.84, 1.19, 0.95],  # discrimination
-    "b": [-0.63, 0.18, -0.84, 0.41, -0.25],  # difficulty
-    "c": [0.17, 0.10, 0.19, 0.15, 0.12],  # guessing
-    "d": [0.87, 0.93, 1.0, 0.89, 0.94]   # upper asymptote
-})
-item_pool = ItemPool.load_from_dataframe(items_data)
+
+item_pool = ItemPool.load_from_list(
+    b=previc_item_pool["Difficulty"],
+    ids=previc_item_pool["id"]
+)
 
 # Create adaptive test
 adaptive_test: AdaptiveTest = TestAssembler(
@@ -161,12 +167,12 @@ win = visual.Window([800, 600],
 # init keyboard
 keyboard.Keyboard()
 
+## FIX THIS
 
 # define function to get user input
 def get_response(item: TestItem) -> int:
-    # get index
-    item_difficulty: float = item.b
-    stimuli: str = [item for item in item_pool.test_items if item["Difficulty"] == item_difficulty][0]["word"]
+    # select corresponding word from item pool data frame
+    stimuli: str = previc_item_pool[previc_item_pool["id"] == item.id]["word"].values[0]
 
     # create text box and display stimulus
     text_box = visual.TextBox2(win=win,
@@ -291,17 +297,18 @@ adaptive_test = TestAssembler(
 Full documentation is available in the `docs/` directory:
 
 - [API Reference](docs/readme.md)
-- [Models Module](docs/adaptivetesting.models.md)
-- [Math Module](docs/adaptivetesting.math.md)
-- [Implementation Examples](docs/adaptivetesting.implementations.md)
-- [Simulation Guide](docs/adaptivetesting.simulation.md)
+- [Models Module](docs/models.md)
+- [Math Module](docs/math.md)
+- [Implementation Examples](docs/implementations.md)
+- [Simulation Guide](docs/simulation.md)
 
 ## Testing
 
 The package includes comprehensive tests. Run them using:
 
 ```bash
-python -m pytest adaptivetesting/tests/
+uv sync
+uv run python -m unittest
 ```
 
 ## Contributing
@@ -309,7 +316,7 @@ python -m pytest adaptivetesting/tests/
 We welcome contributions! Please see our [GitHub repository](https://github.com/condecon/adaptivetesting) for:
 
 - Issue tracking
-- Feature requests  
+- Feature requests
 - Pull request guidelines
 - Development setup
 
@@ -325,6 +332,22 @@ This package is designed for researchers and practitioners in:
 
 The package facilitates the transition from research simulation to real-world testing applications without requiring major code modifications.
 
+## Citation
+If you use this package for your academic work, please provide the following reference:
+Engicht, J., Bee, R. M., & Koch, T. (2025). Customizable Bayesian Adaptive Testing with Python – The adaptivetesting Package. Open Science Framework. https://doi.org/10.31219/osf.io/d2xge_v1
+
+```
+@online{engichtCustomizableBayesianAdaptive2025,
+  title = {Customizable {{Bayesian Adaptive Testing}} with {{Python}} – {{The}} Adaptivetesting {{Package}}},
+  author = {Engicht, Jonas and Bee, R. Maximilian and Koch, Tobias},
+  date = {2025-08-06},
+  eprinttype = {Open Science Framework},
+  doi = {10.31219/osf.io/d2xge_v1},
+  url = {https://osf.io/d2xge_v1},
+  pubstate = {prepublished}
+}
+```
+
 ## License
 
 This project is licensed under the terms specified in the [LICENSE](LICENSE) file.

{adaptivetesting-1.1.1 → adaptivetesting-1.1.3}/adaptivetesting/math/estimators/__functions/__estimators.py

@@ -12,22 +12,50 @@ def probability_y1(mu: np.ndarray,
 
     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
     """
+    # Compute the exponent safely
+    z = a * (mu - b)
+
+    # Use log-sum-exp trick for numerical stability
+    # For large positive z: exp(z)/(1+exp(z)) ≈ 1
+    # For large negative z: exp(z)/(1+exp(z)) ≈ exp(z)
+
+    # Clip z to prevent overflow in exp()
+    z_clipped = np.clip(z, -500, 500)  # exp(-500) and exp(500) are safe
+
+    # Compute the logistic function safely
+    # Use different formulas based on the sign of z for stability
+    result = np.empty_like(z_clipped)
+
+    # For large positive values, use alternative formula to avoid overflow
+    mask_positive = z_clipped > 20  # exp(20) is large but manageable
+    mask_negative = z_clipped < -20  # exp(-20) is very small
+    mask_medium = ~(mask_positive | mask_negative)
+
+    # Large positive z: 1/(1+exp(-z)) is more stable
+    result[mask_positive] = 1.0 / (1.0 + np.exp(-z_clipped[mask_positive]))
+
+    # Large negative z: exp(z)/(1+exp(z)) is stable
+    exp_z_neg = np.exp(z_clipped[mask_negative])
+    result[mask_negative] = exp_z_neg / (1.0 + exp_z_neg)
+
+    # Medium values: use standard formula
+    exp_z_med = np.exp(z_clipped[mask_medium])
+    result[mask_medium] = exp_z_med / (1.0 + exp_z_med)
+
+    # Apply the 4PL transformation
+    value = c + (d - c) * result
+
+    # Ensure probabilities are within valid range [c, d]
+    value = np.clip(value, c, d)
 
-    value = c + (d - c) * (np.exp(a * (mu - b))) / \
-        (1 + np.exp(a * (mu - b)))
-    
     return np.squeeze(value)
 
 
@@ -40,13 +68,13 @@ def probability_y0(mu: np.ndarray,
 
     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:
@@ -68,13 +96,13 @@ def likelihood(mu: np.ndarray,
 
     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
 
     Returns:
@@ -88,7 +116,7 @@ def likelihood(mu: np.ndarray,
 
     terms = (probability_y1(mu, a, b, c, d)**response_pattern) * \
         (probability_y0(mu, a, b, c, d) ** (1 - response_pattern))
-    
+
     return -np.prod(terms)
 
 
@@ -100,14 +128,14 @@ def maximize_likelihood_function(a: np.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
@@ -129,7 +157,7 @@ def maximize_likelihood_function(a: np.ndarray,
             "Response pattern is invalid. It consists of only one type of response.")
         raise AlgorithmException(
             "Response pattern is invalid. It consists of only one type of response.")
-    
+
     result: OptimizeResult = minimize_scalar(likelihood, args=(a, b, c, d, response_pattern),
                                              bounds=border, method='bounded') # type: ignore
 

{adaptivetesting-1.1.1 → adaptivetesting-1.1.3}/adaptivetesting/math/estimators/__test_information.py

@@ -13,27 +13,17 @@ def item_information_function(
         c: np.ndarray,
         d: np.ndarray
 ) -> np.ndarray:
-    """Calculate the information of a test item given the currently
-    estimated ability `mu`.
-
-    Args:
-        mu (np.ndarray): currently estimated ability
-        a (np.ndarray): _description_
-        b (np.ndarray): _description_
-        c (np.ndarray): _description_
-        d (np.ndarray): _description_
-
-    Returns:
-        np.ndarray: _description_
-    """
     p_y1 = probability_y1(mu, a, b, c, d)
 
+    # Clip probabilities
+    p_y1_clipped = np.clip(p_y1, 1e-10, 1 - 1e-10)
+
     def p_y1_grad(x: np.ndarray) -> np.ndarray:
-        # Central finite difference for gradient
-        h = 1e-5
+        # Use a more robust finite difference scheme
+        h = np.maximum(1e-8, 1e-8 * np.abs(x))  # Adaptive step size
         return (probability_y1(x + h, a, b, c, d) - probability_y1(x - h, a, b, c, d)) / (2 * h)
-    
-    product = (p_y1_grad(mu) ** 2) / (p_y1 * (1 - p_y1))
+
+    product = (p_y1_grad(mu) ** 2) / (p_y1_clipped * (1 - p_y1_clipped))
     information = np.sum(product)
     return information
 
@@ -59,7 +49,7 @@ def prior_information_function(prior: Prior,
         (score_values ** 2) * prior.pdf(x_vals),
         x_vals
     )
-    
+
     return information
 
 

{adaptivetesting-1.1.1 → adaptivetesting-1.1.3}/adaptivetesting/models/__item_pool.py

@@ -37,7 +37,7 @@ class ItemPool:
             return selected_item, simulated_response
         else:
             return selected_item
-    
+
     def get_item_by_item(self, item: TestItem) -> Tuple[TestItem, int] | TestItem:
         """Returns item and if defined the simulated response.
 
@@ -94,24 +94,27 @@ class ItemPool:
             a: List[float] | None = None,
             c: List[float] | None = None,
             d: List[float] | None = None,
-            simulated_responses: List[int] | None = None) -> "ItemPool":
+            simulated_responses: List[int] | None = None,
+            ids: List[int] | None = None) -> "ItemPool":
         """
         Creates test items from a list of floats.
 
         Args:
             a (List[float]): discrimination parameter
-            
+
             b (List[float]): difficulty parameter
-            
+
             c (List[float]): guessing parameter
-            
+
             d (List[float]): slipping parameter
-            
+
             simulated_responses (List[int]): simulated responses
 
+            ids (List[int]): item IDs
+
         Returns:
             List[TestItem]: item pool
-        
+
         """
         items: List[TestItem] = []
 
@@ -126,19 +129,25 @@ class ItemPool:
                 raise ValueError("Length of a and b has to be the same.")
             for i, discrimination in enumerate(a):
                 items[i].a = discrimination
-        
+
         if c is not None:
             if len(c) != len(b):
                 raise ValueError("Length of c and b has to be the same.")
             for i, guessing in enumerate(c):
                 items[i].c = guessing
-        
+
         if d is not None:
             if len(d) != len(b):
                 raise ValueError("Length of d and b has to be the same.")
             for i, slipping in enumerate(d):
                 items[i].d = slipping
 
+        if ids is not None:
+            if len(ids) != len(b):
+                raise ValueError("Length of ids and b has to be the same.")
+            for i, id_ in enumerate(ids):
+                items[i].id = id_
+
         item_pool = ItemPool(items)
         item_pool.simulated_responses = simulated_responses
 
@@ -146,10 +155,11 @@ class ItemPool:
 
     @staticmethod
     def load_from_dict(source: dict[str, List[float]],
-                       simulated_responses: List[int] | None = None) -> "ItemPool":
+                       simulated_responses: List[int] | None = None,
+                       ids: List[int] | None = None) -> "ItemPool":
         """Creates test items from a dictionary.
         The dictionary has to have the following keys:
-            
+
             - a
             - b
             - c
@@ -158,6 +168,8 @@ class ItemPool:
 
         Args:
             source (dict[str, List[float]]): item pool dictionary
+            simulated_responses (List[int]): simulated responses
+            ids (List[int]): item IDs
 
         Returns:
             List[TestItem]: item pool
@@ -170,13 +182,13 @@ class ItemPool:
         # check none
         if a is None:
             raise ValueError("a cannot be None")
-        
+
         if b is None:
             raise ValueError("b cannot be None")
-        
+
         if c is None:
             raise ValueError("c cannot be None")
-        
+
         if d is None:
             raise ValueError("d cannot be None")
 
@@ -184,6 +196,10 @@ class ItemPool:
         if not (len(a) == len(b) == len(c) == len(d)):
             raise ValueError("All lists in the source dictionary must have the same length")
 
+        if ids is not None:
+            if len(ids) != len(b):
+                raise ValueError("Length of ids and b has to be the same.")
+
         n_items = len(b)
         items: List[TestItem] = []
         for i in range(n_items):
@@ -193,12 +209,15 @@ class ItemPool:
             item.c = c[i]
             item.d = d[i]
 
+            if ids is not None:
+                item.id = ids[i]
+
             items.append(item)
 
         item_pool = ItemPool(items, simulated_responses)
-        
+
         return item_pool
-    
+
     @staticmethod
     def load_from_dataframe(source: DataFrame) -> "ItemPool":
         """Creates item pool from a pandas DataFrame.
@@ -206,7 +225,7 @@ class ItemPool:
         Each column has to contain float values.
         A `simulated_responses` (int values) column can be added to
         the DataFrame to provide simulated responses.
-        
+
 
         Args:
             source (DataFrame): _description_
@@ -218,28 +237,33 @@ class ItemPool:
         # check if columns are present
         if "a" not in source.columns:
             raise ValueError("Column 'a' not found.")
-        
+
         if "b" not in source.columns:
             raise ValueError("Column 'b' not found.")
-        
+
         if "c" not in source.columns:
             raise ValueError("Column 'c' not found.")
-        
+
         if "d" not in source.columns:
             raise ValueError("Column 'd' not found.")
-        
+
         # get values
         a: List[float] = source["a"].values.tolist() # type: ignore
         b: List[float] = source["b"].values.tolist() # type: ignore
         c: List[float] = source["c"].values.tolist() # type: ignore
         d: List[float] = source["d"].values.tolist() # type: ignore
 
+        if "ids" in source.columns:
+            ids: List[int] | None = source["ids"].values.tolist() # type: ignore
+        else:
+            ids = None
+
         # create item pool
-        item_pool = ItemPool.load_from_list(a=a, b=b, c=c, d=d)
-    
+        item_pool = ItemPool.load_from_list(a=a, b=b, c=c, d=d, ids=ids)
+
         # check if simulated responses are present
         if "simulated_responses" in source.columns:
             simulated_responses: List[int] = source["simulated_responses"].values.tolist() # type: ignore
             item_pool.simulated_responses = simulated_responses
-        
+
         return item_pool

adaptivetesting-1.1.3/adaptivetesting/models/__test_item.py

@@ -0,0 +1,33 @@
+class TestItem:
+    def __init__(self):
+        """Representation of a test item in the item pool.
+        The format is equal to the implementation in catR.
+
+        Properties:
+            - id (int | None): item ID
+            - a (float): discrimination parameter
+            - b (float): difficulty parameter
+            - c (float): guessing parameter
+            - d (float): slipping parameter / upper asymptote
+
+        """
+        self.id: int | None = None
+        self.a: float = 1
+        self.b: float = float("nan")
+        self.c: float = 0
+        self.d: float = 1
+
+    def as_dict(self, with_id: bool = False) -> dict[str, float | int | None]:
+        """Returns the item as a dictionary"""
+
+        item_dict: dict[str, float | int | None] = {
+            "a": self.a,
+            "b": self.b,
+            "c": self.c,
+            "d": self.d
+        }
+
+        if with_id and self.id is not None:
+            item_dict["id"] = self.id
+
+        return item_dict