adaptivetesting 1.1.5__tar.gz → 1.2__tar.gz

adaptivetesting-1.2/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: adaptivetesting
+Version: 1.2
+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
+Author-email: Jonas Engicht <dev@condecon.de>
+Project-URL: Homepage, https://github.com/condecon/adaptivetesting
+Project-URL: Documentation, https://github.com/condecon/adaptivetesting/wiki
+Project-URL: Repository, https://github.com/condecon/adaptivetesting.git
+Project-URL: Issues, https://github.com/condecon/adaptivetesting/issues
+Keywords: statistics,psychology,item-response-theory,computerized-adaptive-testing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.1.0
+Requires-Dist: pandas>=2.3.0
+Requires-Dist: scipy>=1.15.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: matplotlib>=3.10.0
+Requires-Dist: numdifftools>=0.9.42
+Dynamic: license-file
+
+# adaptivetesting
+
+<img src="/docs/_static/logo.svg" style="width: 100%">
+</img>
+
+**An open-source Python package for simplified, customizable Computerized Adaptive Testing (CAT) using Bayesian methods.**
+
+
+## Key Features
+
+- **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, GRM, GPCM
+- **Multiple Estimators**:
+  - Maximum Likelihood Estimation (MLE)
+  - Bayesian Modal Estimation (BM)
+  - Expected A Posteriori (EAP)
+- **Item Selection Strategies**: Maximum information criterion
+- **Content Balancing**: Maximum Priority Index, Weighted Penalty Model
+- **Exposure Control**: Randomesque Item Selection, Maximum Priority Index 
+- **Simulation Framework**: Comprehensive tools for CAT simulation and evaluation
+- **Real-world Application**: Direct transition from simulation to production testing
+- **Stopping Criteria**: Support for standard error and test length criteria
+- **Data Management**: Built-in support for CSV and pickle data formats
+
+## Installation
+
+Install from PyPI using pip:
+
+```bash
+pip install adaptivetesting
+```
+
+For the latest development version:
+
+```bash
+pip install git+https://github.com/condecon/adaptivetesting
+```
+
+## Contributing
+
+We welcome contributions! Please see our [GitHub repository](https://github.com/condecon/adaptivetesting) for:
+
+- Issue tracking
+- Feature requests
+- Pull request guidelines
+- Development setup
+
+## Research and Applications
+
+This package is designed for researchers and practitioners in:
+
+- Educational assessment
+- Psychological testing
+- Cognitive ability measurement
+- Adaptive learning systems
+- Psychometric research
+
+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.2/README.md

@@ -0,0 +1,79 @@
+# adaptivetesting
+
+<img src="/docs/_static/logo.svg" style="width: 100%">
+</img>
+
+**An open-source Python package for simplified, customizable Computerized Adaptive Testing (CAT) using Bayesian methods.**
+
+
+## Key Features
+
+- **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, GRM, GPCM
+- **Multiple Estimators**:
+  - Maximum Likelihood Estimation (MLE)
+  - Bayesian Modal Estimation (BM)
+  - Expected A Posteriori (EAP)
+- **Item Selection Strategies**: Maximum information criterion
+- **Content Balancing**: Maximum Priority Index, Weighted Penalty Model
+- **Exposure Control**: Randomesque Item Selection, Maximum Priority Index 
+- **Simulation Framework**: Comprehensive tools for CAT simulation and evaluation
+- **Real-world Application**: Direct transition from simulation to production testing
+- **Stopping Criteria**: Support for standard error and test length criteria
+- **Data Management**: Built-in support for CSV and pickle data formats
+
+## Installation
+
+Install from PyPI using pip:
+
+```bash
+pip install adaptivetesting
+```
+
+For the latest development version:
+
+```bash
+pip install git+https://github.com/condecon/adaptivetesting
+```
+
+## Contributing
+
+We welcome contributions! Please see our [GitHub repository](https://github.com/condecon/adaptivetesting) for:
+
+- Issue tracking
+- Feature requests
+- Pull request guidelines
+- Development setup
+
+## Research and Applications
+
+This package is designed for researchers and practitioners in:
+
+- Educational assessment
+- Psychological testing
+- Cognitive ability measurement
+- Adaptive learning systems
+- Psychometric research
+
+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.5 → adaptivetesting-1.2}/adaptivetesting/__init__.py

@@ -12,18 +12,21 @@ from .data.__pickle_context import PickleContext
 from .implementations.__default_implementation import DefaultImplementation
 from .implementations.__pre_test import PreTest
 from .implementations.__semi_implementation import SemiAdaptiveImplementation
-from .implementations.__test_assembler import TestAssembler
+from .implementations.__test_assembler import TestAssembler, ContentBalancingArgs, ExposureControlArgs
 
 from .math.__gen_response_pattern import generate_response_pattern
 from .math.estimators.__ml_estimation import MLEstimator
 from .math.estimators.__bayes_modal_estimation import BayesModal
 from .math.estimators.__expect_a_posteriori import ExpectedAPosteriori
-from .math.estimators.__prior import Prior, NormalPrior, CustomPrior, CustomPriorException
+from .math.estimators.__prior import Prior, NormalPrior, CustomPrior, CustomPriorException, SkewNormalPrior, EmpiricalPrior
 from .math.estimators.__functions.__estimators import probability_y0, probability_y1, maximize_likelihood_function, likelihood
 from .math.estimators.__functions.__bayes import maximize_posterior
 from .math.estimators.__test_information import test_information_function, item_information_function, prior_information_function
 from .math.item_selection.__maximum_information_criterion import maximum_information_criterion
 from .math.item_selection.__urrys_rule import urrys_rule
+from .math.content_balancing.__weighted_penalty_model import WeightedPenaltyModel
+from .math.content_balancing.__constraint import *
+from .math.content_balancing.__functions import *
 
 from .models.__adaptive_test import AdaptiveTest
 from .models.__algorithm_exception import AlgorithmException
@@ -39,4 +42,14 @@ from .services.__item_selection_protocol import ItemSelectionStrategy
 
 from .simulation.__simulation import Simulation, SimulationPool, setup_simulation_and_start
 
-from .utils.__descriptives import bias, average_absolute_deviation, rmse
+from .utils.__descriptives import bias, average_absolute_deviation, rmse
+from .utils.__funcs import load_final_test_results, load_test_results_single_participant
+from .utils.__plots import (
+    plot_exposure_rate,
+    plot_final_ability_estimates,
+    plot_icc,
+    plot_iif,
+    plot_exposure_rate,
+    plot_test_information,
+    plot_theta_estimation_trace
+)

{adaptivetesting-1.1.5 → adaptivetesting-1.2}/adaptivetesting/data/__csv_context.py

@@ -3,7 +3,8 @@ import csv
 import pathlib
 from ..models.__test_result import TestResult
 from ..services.__test_results_interface import ITestResults
-from dataclasses import fields
+import json
+import ast
 
 
 class CSVContext(ITestResults):
@@ -47,22 +48,34 @@ class CSVContext(ITestResults):
             file.close()
 
     def load(self) -> List[TestResult]:
-        """Loads test results from a CSV file for a specific participant and simulation.
-        Reads the CSV file located at `data/{simulation_id}/{participant_id}.csv`,
-        parses each row into a `TestResult` object,
-        and returns a list of these objects.
-        
-        Returns:
-            List[TestResult]: A list of `TestResult` objects loaded from the CSV file.
+        """Loads results from the database.
+        The implementation of this method is required
+        by the interface. However, it does not have
+        any implemented functionality and will throw an error
+        if used.
+
+        Returns: List[TestResult]
         """
         foldername = f"data/{self.simulation_id}"
         
-        fieldnames = list(fields(TestResult))
         test_results: list[TestResult] = []
         with open(f"{foldername}/{self.participant_id}.csv", "r", encoding="utf-8") as file:
-            reader = csv.DictReader(file, fieldnames=fieldnames)
+            reader = csv.DictReader(file)
+            next(reader, None) # skip header row
             for row in reader:
                 test_result = TestResult.from_dict(row)
+                # showed_item is read as a string representation of a Python
+                # literal (e.g. a dict). Use ast.literal_eval to safely parse
+                # it back into a dict. Fallback to a JSON-style conversion
+                # if literal_eval fails.
+                try:
+                    test_result.showed_item = ast.literal_eval(str(test_result.showed_item))
+                except Exception:
+                    json_string = str(test_result.showed_item).replace("'", '"').replace("None", "null")
+                    try:
+                        test_result.showed_item = json.loads(json_string)
+                    except Exception:
+                        test_result.showed_item = {}
                 test_results.append(test_result)
             file.close()
         return test_results

adaptivetesting-1.2/adaptivetesting/data/__read_prev_items_exp_cont.py

@@ -0,0 +1,56 @@
+from typing import Literal
+from warnings import deprecated
+from ..models.__test_item import TestItem
+from ..models.__test_result import TestResult
+from .__csv_context import CSVContext
+from .__pickle_context import PickleContext
+
+
+def read_prev_items(format: Literal["CSV", "PICKLE"],
+                    test_id: str,
+                    participant_ids: list[str]) -> list[TestItem]:
+    """Read previously administered items.
+    This function is internally used to perform exposure control.
+
+    Args:
+        format (Literal["CSV", "PICKLE"]): The format of the results: CSV or PICKLE.
+        test_id (str): The test ID / simulation ID.
+        participant_ids (list[str]): The participant IDs.
+
+    Returns:
+        list[TestItem]: A list of TestItem objects.
+    """
+    all_shown_test_items = []
+    
+    for part_id in participant_ids:
+        test_results = read_single_participant(test_id, part_id, format)
+        items = [TestItem.from_dict(res.showed_item) for res in test_results]
+        
+        all_shown_test_items += items
+
+    return all_shown_test_items
+
+
+@deprecated("This function will be removed in future releases.")
+def read_single_participant(test_id: str, participant_id: str, format: Literal["CSV", "PICKLE"]) -> list[TestResult]:
+    """
+    Reads the test results of a particular participant.
+    Args:
+        test_id (str): The test ID / simulation ID.
+        participant_id (str): The participant ID.
+        format (Literal["CSV", "PICKLE"]): The format of the results: CSV or PICKLE.
+
+    Returns:
+        list[TestResult]: A list of TestResult objects.
+
+    Raises:
+        ValueError: If the format is not supported.
+    """
+    context: CSVContext | PickleContext
+    if format == "CSV":
+        context = CSVContext(test_id, participant_id)
+        return context.load()
+    if format == "PICKLE":
+        context = PickleContext(test_id, participant_id)
+        return context.load()
+    raise ValueError(f"Unknown format: {format}")

{adaptivetesting-1.1.5 → adaptivetesting-1.2}/adaptivetesting/implementations/__pre_test.py

@@ -1,4 +1,4 @@
-from typing import List
+from typing import List, cast
 import numpy as np
 from ..models.__test_item import TestItem
 import random
@@ -10,6 +10,7 @@ class PreTest:
         The pretest class can be used to draw items randomly from
         difficulty quantiles
         of the item pool.
+        This pretest can only be used with dichotomous IRT models and items.
 
         Args:
             items: Item pool
@@ -18,15 +19,21 @@ class PreTest:
                 If not, the item selection will be drawn randomly, and you will not be able
                 to reproduce the results.
 
+        Raises:
+            ValueError: Raised if the items are specified for polytomous IRT models.
+
         """
         self.items = items
         self.seed = seed
 
+        if any([isinstance(item.b, list) for item in items]):
+            raise ValueError("The pretest can only be used with dichotomous IRT models and items.")
+
     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]
+        difficulties: List[float] = [cast(float, item.b) for item in self.items]
 
         quantiles = np.array([])
         # calculate quantiles
@@ -50,7 +57,7 @@ class PreTest:
         """
         # select only items with difficulty in interval
         items_in_interval: List[TestItem] = [item for item in list(self.items)
-                                             if lower < item.b <= upper]
+                                             if lower < cast(float, item.b) <= upper]
         # draw one item randomly
         if self.seed is not None:
             random.seed(self.seed)