adaptivetesting 1.1.4__tar.gz → 1.1.6__tar.gz

{adaptivetesting-1.1.4 → adaptivetesting-1.1.6}/.github/workflows/python-test.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v3
@@ -42,7 +42,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-          python-version: ["3.10", "3.11", "3.12"]
+          python-version: ["3.12", "3.13", "3.14"]
       
     steps:
       - uses: actions/checkout@v3

adaptivetesting-1.1.6/.python-version

@@ -0,0 +1 @@
+3.13

{adaptivetesting-1.1.4 → adaptivetesting-1.1.6}/CHANGELOG.md

@@ -1,3 +1,9 @@
+# Version 1.1.6
+- Bug Fig #49 (optimization interval issue in BayesModal)
+
+# Version 1.1.5
+- Bug Fix #46 (numerical stability issue concerning Bayesian ability estimation)
+
 # Version 1.1.4
 - Bug Fix #43 (optimization interval in `maximize_posterior` function)
 
@@ -7,4 +13,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.
+- Examples and the readme file have been updated accordingly.

{adaptivetesting-1.1.4 → adaptivetesting-1.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adaptivetesting
-Version: 1.1.4
+Version: 1.1.6
 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
@@ -9,14 +9,18 @@ Project-URL: Issues, https://github.com/condecon/adaptivetesting/issues
 Author-email: Jonas Engicht <dev@condecon.de>
 License-File: LICENSE
 Keywords: computerized-adaptive-testing,item-response-theory,psychology,statistics
-Requires-Python: >=3.10
+Requires-Python: >=3.12
+Requires-Dist: matplotlib>=3.9.0
 Requires-Dist: numpy>=2.0.0
-Requires-Dist: pandas>=2.2.0
-Requires-Dist: scipy>=1.15.0
-Requires-Dist: tqdm>=4.67.1
+Requires-Dist: pandas>=2.3.0
+Requires-Dist: scipy>=1.12.0
+Requires-Dist: tqdm>=4.66.0
 Description-Content-Type: text/markdown
 
 # adaptivetesting
+[![SPEC 0 — Minimum Supported Dependencies](docs/source/_static/SPEC-0.svg)](https://scientific-python.org/specs/spec-0000/)
+
+
 
 <img src="/docs/source/_static/logo.svg" style="width: 100%">
 </img>

{adaptivetesting-1.1.4 → adaptivetesting-1.1.6}/README.md

@@ -1,4 +1,7 @@
 # adaptivetesting
+[![SPEC 0 — Minimum Supported Dependencies](docs/source/_static/SPEC-0.svg)](https://scientific-python.org/specs/spec-0000/)
+
+
 
 <img src="/docs/source/_static/logo.svg" style="width: 100%">
 </img>

adaptivetesting-1.1.6/adaptivetesting/__init__.py

@@ -0,0 +1,42 @@
+from . import data
+from . import implementations
+from . import math
+from . import models
+from . import services
+from . import simulation
+from . import tests
+
+from .data.__csv_context import CSVContext
+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 .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.__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 .models.__adaptive_test import AdaptiveTest
+from .models.__algorithm_exception import AlgorithmException
+from .models.__item_pool import ItemPool 
+from .models.__item_selection_exception import ItemSelectionException
+from .models.__test_item import TestItem
+from .models.__test_result import TestResult
+from .models.__misc import ResultOutputFormat, StoppingCriterion
+
+from .services.__estimator_interface import IEstimator
+from .services.__test_results_interface import ITestResults
+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

{adaptivetesting-1.1.4 → adaptivetesting-1.1.6}/adaptivetesting/data/__csv_context.py

@@ -3,6 +3,7 @@ import csv
 import pathlib
 from ..models.__test_result import TestResult
 from ..services.__test_results_interface import ITestResults
+from dataclasses import fields
 
 
 class CSVContext(ITestResults):
@@ -46,12 +47,22 @@ class CSVContext(ITestResults):
             file.close()
 
     def load(self) -> List[TestResult]:
-        """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]
+        """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.
         """
-        raise NotImplementedError("This function is not implemented.")
+        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)
+            for row in reader:
+                test_result = TestResult.from_dict(row)
+                test_results.append(test_result)
+            file.close()
+        return test_results

{adaptivetesting-1.1.4 → adaptivetesting-1.1.6}/adaptivetesting/data/__pickle_context.py

@@ -40,12 +40,18 @@ class PickleContext(ITestResults):
             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]
+        """Loads and returns a list of TestResult objects for a specific participant and simulation.
+        The method reads a pickle file located at 'data/{simulation_id}/{participant_id}.pickle'
+        and deserializes its contents into a list of TestResult instances.
+        Returns:
+            List[TestResult]: The list of test results loaded from the pickle file.
+        Raises:
+            FileNotFoundError: If the specified pickle file does not exist.
+            pickle.UnpicklingError: If the file cannot be unpickled.
         """
-        raise NotImplementedError("This  function is not implemented.")
+        foldername = f"data/{self.simulation_id}"
+
+        with open(f"{foldername}/{self.participant_id}.pickle", "rb") as file:
+            test_results: list[TestResult] = pickle.load(file)
+            file.close()
+        return test_results

{adaptivetesting-1.1.4 → adaptivetesting-1.1.6}/adaptivetesting/math/estimators/__bayes_modal_estimation.py

@@ -62,7 +62,8 @@ class BayesModal(IEstimator):
                 self.c,
                 self.d,
                 self.response_pattern,
-                self.prior
+                self.prior,
+                self.optimization_interval
             )
         # else, we have to calculate the full posterior distribution
         # because the optimizers do not correctly identify the maximum of the function
@@ -91,7 +92,7 @@ class BayesModal(IEstimator):
                 ])
 
                 # add prior
-                unmarginalized_posterior = lik_values * self.prior.pdf(mu)
+                unmarginalized_posterior = lik_values * np.log(self.prior.pdf(mu))
                 # find argmin and return mu
                 estimate_index = np.argmin(unmarginalized_posterior)
                 return float(mu[estimate_index].astype(float))

{adaptivetesting-1.1.4 → adaptivetesting-1.1.6}/adaptivetesting/math/estimators/__functions/__bayes.py

@@ -1,8 +1,8 @@
 import numpy as np
 from scipy.optimize import minimize_scalar, OptimizeResult # type: ignore
-from .__estimators import likelihood
 from ..__prior import Prior
 from ....models.__algorithm_exception import AlgorithmException
+from .__estimators import probability_y0, probability_y1
 
 
 def maximize_posterior(
@@ -18,15 +18,15 @@ def maximize_posterior(
 
     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
@@ -34,15 +34,43 @@ def maximize_posterior(
     Returns:
         float: Bayes Modal estimator for the given parameters
     """
-    def posterior(mu) -> np.ndarray:
-        return likelihood(mu, a, b, c, d, response_pattern) * prior.pdf(mu)
-    
-    result: OptimizeResult = minimize_scalar(lambda mu: posterior(mu),
+    def log_posterior(mu) -> np.ndarray:
+        p1 = probability_y1(mu, a, b, c, d)
+        p0 = probability_y0(mu, a, b, c, d)
+
+        log_likelihood = np.sum(
+            (response_pattern * np.log(p1 + 1e-300)) + (
+                (1 - response_pattern) * np.log(p0 + 1e-300)
+            ))
+        log_prior = np.log(prior.pdf(mu) + 1e-300)
+
+        return log_likelihood + log_prior
+
+    result: OptimizeResult = minimize_scalar(lambda mu: -log_posterior(mu),
                                              bounds=optimization_interval,
                                              method="bounded") # type: ignore
-    
+
     if not result.success:
         raise AlgorithmException(f"Optimization failed: {result.message}")
-    
+
     else:
         return float(result.x)
+
+
+def likelihood(mu: np.ndarray,
+               a: np.ndarray,
+               b: np.ndarray,
+               c: np.ndarray,
+               d: np.ndarray,
+               response_pattern: np.ndarray
+               ):
+    
+    p1 = probability_y1(mu, a, b, c, d)
+    p0 = probability_y0(mu, a, b, c, d)
+
+    log_likelihood = np.sum(
+        (response_pattern * np.log(p1 + 1e-300)) + (
+            (1 - response_pattern) * np.log(p0 + 1e-300)
+        ))
+
+    return -np.exp(log_likelihood)

{adaptivetesting-1.1.4 → adaptivetesting-1.1.6}/adaptivetesting/models/__adaptive_test.py

@@ -2,7 +2,6 @@ from typing import List
 import abc
 import copy
 from .__test_item import TestItem
-from ..math.item_selection.__urrys_rule import urrys_rule
 from ..math.__gen_response_pattern import generate_response_pattern
 from .__test_result import TestResult
 from .__item_pool import ItemPool
@@ -114,8 +113,6 @@ class AdaptiveTest(abc.ABC):
             TestItem: selected item
         """
         raise NotImplementedError("This functionality is not implemented by default.")
-        item = urrys_rule(self.item_pool.test_items, self.ability_level)
-        return item
 
     @abc.abstractmethod
     def estimate_ability_level(self) -> tuple[float, float]:

{adaptivetesting-1.1.4 → adaptivetesting-1.1.6}/adaptivetesting/models/__item_pool.py

@@ -110,7 +110,9 @@ class ItemPool:
 
             simulated_responses (List[int]): simulated responses
 
-            ids (List[int]): item IDs
+            ids (List[int]): item IDs. If the argument is set to `None`
+                all items are numbered in the order in which they are
+                passed to the function.
 
         Returns:
             List[TestItem]: item pool
@@ -147,6 +149,9 @@ class ItemPool:
                 raise ValueError("Length of ids and b has to be the same.")
             for i, id_ in enumerate(ids):
                 items[i].id = id_
+        else:
+            for i in range(len(b)):
+                items[i].id = i
 
         item_pool = ItemPool(items)
         item_pool.simulated_responses = simulated_responses
@@ -169,7 +174,9 @@ class ItemPool:
         Args:
             source (dict[str, List[float]]): item pool dictionary
             simulated_responses (List[int]): simulated responses
-            ids (List[int]): item IDs
+            ids (List[int]): item IDs. If the argument is set to `None`
+                all items are numbered in the order in which they are
+                passed to the function.
 
         Returns:
             List[TestItem]: item pool
@@ -211,6 +218,8 @@ class ItemPool:
 
             if ids is not None:
                 item.id = ids[i]
+            else:
+                item.id = i
 
             items.append(item)
 
@@ -223,6 +232,13 @@ class ItemPool:
         """Creates item pool from a pandas DataFrame.
         Required columns are: `a`, `b`, `c`, `d`.
         Each column has to contain float values.
+        
+        A `id` column can be added to assign
+        each test item a unique identifier.
+        If there is no `id` column
+        all items are numbered in the order in which they are
+        passed to the function.
+
         A `simulated_responses` (int values) column can be added to
         the DataFrame to provide simulated responses.
 

adaptivetesting-1.1.6/adaptivetesting/tests/test_descriptives.py

@@ -0,0 +1,50 @@
+import unittest
+from unittest.mock import patch
+import numpy as np
+from adaptivetesting import rmse, bias, average_absolute_deviation, TestResult
+from adaptivetesting.models.__misc import ResultOutputFormat
+
+
+class DummyResult:
+    def __init__(self, ability_estimation, true_ability_level):
+        self.ability_estimation = ability_estimation
+        self.true_ability_level = true_ability_level
+
+
+class TestDescriptives(unittest.TestCase):
+    @patch('adaptivetesting.utils.__descriptives.load_final_test_results')
+    def test_bias(self, mock_load):
+        mock_load.return_value = [
+            TestResult(None, 1.0, None, None, None, 0.5), # type: ignore
+            TestResult(None, 2.0, None, None, None, 1.5), # type: ignore
+            TestResult(None, 3.0, None, None, None, 2.5), # type: ignore
+        ]
+        result = bias('sim1', ['p1', 'p2', 'p3'], ResultOutputFormat.CSV)
+        expected = np.mean([1.0 - 0.5, 2.0 - 1.5, 3.0 - 2.5])
+        self.assertAlmostEqual(result, expected) # type: ignore
+
+    @patch('adaptivetesting.utils.__descriptives.load_final_test_results')
+    def test_average_absolute_deviation(self, mock_load):
+        mock_load.return_value = [
+            TestResult(None, 1.0, None, None, None, 0.5), # type: ignore
+            TestResult(None, 2.0, None, None, None, 1.5), # type: ignore
+            TestResult(None, 3.0, None, None, None, 2.5), # type: ignore
+        ]
+        result = average_absolute_deviation('sim1', ['p1', 'p2', 'p3'], ResultOutputFormat.CSV)
+        expected = np.mean([abs(1.0 - 0.5), abs(2.0 - 1.5), abs(3.0 - 2.5)])
+        self.assertAlmostEqual(result, expected) # type: ignore
+
+    @patch('adaptivetesting.utils.__descriptives.load_final_test_results')
+    def test_rmse(self, mock_load):
+        mock_load.return_value = [
+            TestResult(None, 1.0, None, None, None, 0.5), # type: ignore
+            TestResult(None, 2.0, None, None, None, 1.5), # type: ignore
+            TestResult(None, 3.0, None, None, None, 2.5), # type: ignore
+        ]
+        result = rmse('sim1', ['p1', 'p2', 'p3'], ResultOutputFormat.CSV)
+        expected = np.sqrt(np.mean([(1.0 - 0.5) ** 2, (2.0 - 1.5) ** 2, (3.0 - 2.5) ** 2]))
+        self.assertAlmostEqual(result, expected)
+
+
+if __name__ == '__main__':
+    unittest.main()

adaptivetesting-1.1.6/adaptivetesting/tests/test_plots.py

@@ -0,0 +1,97 @@
+# type: ignore
+import unittest
+from unittest.mock import patch
+from adaptivetesting.utils import (
+    plot_final_ability_estimates,
+    plot_icc,
+    plot_iif,
+    plot_exposure_rate,
+    plot_test_information,
+    plot_theta_estimation_trace
+)
+from adaptivetesting.models.__test_item import TestItem
+from adaptivetesting.models.__misc import ResultOutputFormat
+import matplotlib
+
+
+class TestPlots(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.dummy_item = TestItem()
+        cls.dummy_item.id = 1
+        cls.dummy_item.a = 1.0
+        cls.dummy_item.b = 0.0
+        cls.dummy_item.c = 0.2
+        cls.dummy_item.d = 1.0
+        cls.dummy_items = [cls.dummy_item for _ in range(3)]
+        cls.simulation_id = 'sim1'
+        cls.participant_ids = ['p1', 'p2']
+        cls.output_format = ResultOutputFormat.CSV
+
+    @patch('adaptivetesting.utils.__plots.load_final_test_results')
+    def test_plot_final_ability_estimates(self, mock_load):
+        # Mock return value: list of objects with .ability_estimation and .true_ability_level
+        class DummyResult:
+            def __init__(self, est, true):
+                self.ability_estimation = est
+                self.true_ability_level = true
+        mock_load.return_value = [DummyResult(1.0, 1.2), DummyResult(0.5, 0.7)]
+        fig, ax = plot_final_ability_estimates(
+            self.simulation_id,
+            self.participant_ids,
+            self.output_format
+        )
+        self.assertIsInstance(fig, matplotlib.figure.Figure)
+        self.assertIsNotNone(ax)
+
+    def test_plot_icc(self):
+        fig, ax = plot_icc(self.dummy_item)
+        self.assertIsInstance(fig, matplotlib.figure.Figure)
+        self.assertIsNotNone(ax)
+
+    def test_plot_iif(self):
+        fig, ax = plot_iif(self.dummy_item)
+        self.assertIsInstance(fig, matplotlib.figure.Figure)
+        self.assertIsNotNone(ax)
+
+    @patch('adaptivetesting.utils.__plots.load_test_results_single_participant')
+    def test_plot_exposure_rate(self, mock_load):
+        # Mock return value: list of objects with .showed_item["id"]
+        class DummyResult:
+            def __init__(self, item_id):
+                self.showed_item = {"id": item_id}
+        mock_load.return_value = [
+            DummyResult("item1"), DummyResult("item2")
+        ]
+        fig, ax = plot_exposure_rate(
+            self.simulation_id,
+            self.participant_ids,
+            self.output_format
+        )
+        self.assertIsInstance(fig, matplotlib.figure.Figure)
+        self.assertIsNotNone(ax)
+
+    def test_plot_test_information(self):
+        fig, ax = plot_test_information(self.dummy_items)
+        self.assertIsInstance(fig, matplotlib.figure.Figure)
+        self.assertIsNotNone(ax)
+
+    @patch('adaptivetesting.utils.__plots.load_test_results_single_participant')
+    def test_plot_theta_estimation_trace(self, mock_load):
+        # Mock return value: list of objects with .true_ability_level and .ability_estimation
+        class DummyResult:
+            def __init__(self, true, est):
+                self.true_ability_level = true
+                self.ability_estimation = est
+        mock_load.return_value = [DummyResult(1.0, 0.9), DummyResult(1.2, 1.1)]
+        fig, ax = plot_theta_estimation_trace(
+            self.simulation_id,
+            self.participant_ids[0],
+            self.output_format
+        )
+        self.assertIsInstance(fig, matplotlib.figure.Figure)
+        self.assertIsNotNone(ax)
+
+
+if __name__ == "__main__":
+    unittest.main()

adaptivetesting-1.1.6/adaptivetesting/utils/__descriptives.py

@@ -0,0 +1,63 @@
+from ..models.__misc import ResultOutputFormat
+import numpy as np
+from .__funcs import load_final_test_results
+
+
+def bias(simulation_id: str, participant_ids: list[str], output_format: ResultOutputFormat) -> np.floating:
+    """
+    Calculates the bias of ability estimations for a set of participants in a simulation.
+    Bias is defined as the mean difference between estimated abilities and true ability levels.
+    Args:
+        simulation_id (str): Identifier for the simulation.
+        participant_ids (list[str]): List of participant identifiers.
+        output_format (ResultOutputFormat): Format in which the results are output.
+    Returns:
+        np.floating: The mean bias of ability estimations.
+    """
+    final_test_results = load_final_test_results(simulation_id, participant_ids, output_format)
+    estimations = np.array([result.ability_estimation for result in final_test_results], dtype=np.float64)
+    true_abilities = np.array([result.true_ability_level for result in final_test_results], dtype=np.float64)
+    
+    return np.mean(estimations - true_abilities)
+
+
+def average_absolute_deviation(simulation_id: str,
+                               participant_ids: list[str],
+                               output_format: ResultOutputFormat) -> np.floating:
+    """
+    Calculates the average absolute deviation between estimated abilities
+    and true ability levels for a set of participants.
+    
+    Args:
+        simulation_id (str): Identifier for the simulation run.
+        participant_ids (list[str]): List of participant identifiers.
+        output_format (ResultOutputFormat): Format in which the results are returned.
+    Returns:
+        np.floating: The mean absolute deviation between estimated and true abilities.
+    """
+    final_test_results = load_final_test_results(simulation_id, participant_ids, output_format)
+    estimations = np.array([result.ability_estimation for result in final_test_results], dtype=np.float64)
+    true_abilities = np.array([result.true_ability_level for result in final_test_results], dtype=np.float64)
+
+    return np.mean(np.abs(estimations - true_abilities))
+
+
+def rmse(simulation_id: str,
+         participant_ids: list[str],
+         output_format: ResultOutputFormat) -> np.floating:
+    """
+    Calculates the root mean squared error (RMSE) between
+    estimated abilities and true ability levels for a set of participants.
+    
+    Args:
+        simulation_id (str): Identifier for the simulation run.
+        participant_ids (list[str]): List of participant IDs to include in the calculation.
+        output_format (ResultOutputFormat): Format in which the test results are returned.
+    Returns:
+        np.floating: The RMSE value between estimated and true abilities.
+    """
+    final_test_results = load_final_test_results(simulation_id, participant_ids, output_format)
+    estimations = np.array([result.ability_estimation for result in final_test_results], dtype=np.float64)
+    true_abilities = np.array([result.true_ability_level for result in final_test_results], dtype=np.float64)
+
+    return np.sqrt(np.mean((estimations - true_abilities) ** 2))

adaptivetesting-1.1.6/adaptivetesting/utils/__funcs.py

@@ -0,0 +1,78 @@
+from ..models.__test_result import TestResult
+from ..data.__csv_context import CSVContext
+from ..data.__pickle_context import PickleContext
+from ..services.__test_results_interface import ITestResults
+from ..models.__misc import ResultOutputFormat
+
+
+def load_final_test_results(simulation_id: str,
+                            participant_ids: list[str],
+                            output_format: ResultOutputFormat) -> list[TestResult]:
+    """
+    Loads the final test results for a list of participants from the specified simulation or adaptive test.
+    Depending on the output format (CSV or PICKLE), this function initializes the appropriate context,
+    loads all test results for each participant, and selects the final result (assumed to be the last entry).
+    The final results are collected and returned as a list.
+    Args:
+        simulation_id (str): The identifier for the simulation from which to load results.
+        participant_ids (list[str]): A list of participant IDs whose results are to be loaded.
+        output_format (ResultOutputFormat): The format in which results are stored (CSV or PICKLE).
+    Returns:
+        list[TestResult]: A list containing the final test result for each participant.
+    Raises:
+        ValueError: If the output_format is not set to either ResultOutputFormat.CSV or ResultOutputFormat.PICKLE.
+    """
+    # load data
+    final_test_results: list[TestResult] = []
+    context: ITestResults
+
+    if output_format is ResultOutputFormat.CSV:
+        for id in participant_ids:
+            context = CSVContext(simulation_id, participant_id=id)
+            test_results = context.load()
+            # select final result
+            final_result = test_results[-1]
+            final_test_results.append(final_result)
+
+    if output_format is ResultOutputFormat.PICKLE:
+        for id in participant_ids:
+            context = PickleContext(simulation_id, participant_id=id)
+            test_results = context.load()
+            # select final result
+            final_result = test_results[-1]
+            final_test_results.append(final_result)
+    else:
+        raise ValueError("output_format is not correctly set to either PICKLE of CSV.")
+
+    return final_test_results
+
+
+def load_test_results_single_participant(simulation_id: str,
+                                         participant_id: str,
+                                         output_format: ResultOutputFormat) -> list[TestResult]:
+    """
+    Loads the test results for a participant from the specified simulation or adaptive test.
+    Depending on the output format (CSV or PICKLE), this function reads the available CSV or PICKLE files.
+
+    Args:
+        simulation_id (str): The identifier for the simulation from which to load results.
+        participant_id (str): Participant ID whose results are to be loaded.
+        output_format (ResultOutputFormat): The format in which results are stored (CSV or PICKLE).
+    Returns:
+        list[TestResult]: A list containing the test results for the participant.
+    Raises:
+        ValueError: If the output_format is not set to either ResultOutputFormat.CSV or ResultOutputFormat.PICKLE.
+    """
+    context: ITestResults
+
+    if output_format is ResultOutputFormat.CSV:
+        context = CSVContext(simulation_id=simulation_id,
+                             participant_id=participant_id)
+        return context.load()
+        
+    if output_format is ResultOutputFormat.PICKLE:
+        context = PickleContext(simulation_id=simulation_id,
+                                participant_id=participant_id)
+        return context.load()
+    else:
+        raise ValueError("output_format is not correctly set to either PICKLE of CSV.")

adaptivetesting-1.1.6/adaptivetesting/utils/__init__.py

@@ -0,0 +1,13 @@
+from .__descriptives import bias, average_absolute_deviation, rmse
+
+from .__funcs import load_final_test_results, load_test_results_single_participant
+
+from .__plots import (
+    plot_exposure_rate,
+    plot_final_ability_estimates,
+    plot_icc,
+    plot_iif,
+    plot_exposure_rate,
+    plot_test_information,
+    plot_theta_estimation_trace
+)