move documentation

README.md

@@ -38,4 +38,4 @@ retaining full compatability with the packages' functionality.
 ![Schematic overview of the Semi-Adaptive implementation](/images/semi-adaptive.svg)
 
 ## Documentation
-Extensive documentation of all programm code is available at ....
+Extensive documentation of all programm code is available at [`/documentation`](/documentation).

documentation/adaptivetesting.data.txt

@@ -0,0 +1,69 @@
+adaptivetesting.data package
+****************************
+
+
+adaptivetesting.data.PickleContext
+==================================
+
+class adaptivetesting.data.PickleContext(simulation_id: str, participant_id: int)
+
+   Bases: "ITestResults"
+
+   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
+
+   load() -> 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]
+
+   save(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
+
+
+adaptivetesting.data.SQLiteContext
+==================================
+
+class adaptivetesting.data.SQLiteContext(simulation_id: str, participant_id: int)
+
+   Bases: "ITestResults"
+
+   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
+
+   load() -> 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]
+
+   save(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

documentation/adaptivetesting.implementations.txt

@@ -0,0 +1,131 @@
+adaptivetesting.implementations package
+***************************************
+
+
+adaptivetesting.implementations.DefaultImplementation
+=====================================================
+
+class adaptivetesting.implementations.DefaultImplementation(item_pool: ItemPool, simulation_id: str, participant_id: int, true_ability_level: float, initial_ability_level: float = 0, simulation=True, debug=False)
+
+   Bases: "AdaptiveTest"
+
+   This class represents the Default implementation using Maximum
+   Likelihood Estimation and Urry’s rule during the test.
+
+   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
+
+   estimate_ability_level(answered_items_difficulties: List[float]) -> 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]*).
+
+      Args:
+         answered_items_difficulties (List[float]): List of difficulty
+         values of the answered items
+
+      Returns:
+         estimation: ability estimation
+
+
+adaptivetesting.implementations.PreTest
+=======================================
+
+class adaptivetesting.implementations.PreTest(items: List[TestItem], seed: int = None)
+
+   Bases: "object"
+
+   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.
+
+   calculate_quantiles() -> ndarray
+
+      Calculates quantiles 0.25, 0.5, 0.75
+
+   select_item_in_interval(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_random_item_quantile() -> List[TestItem]
+
+      Selects a random item from the 0.25, 0.5 and 0.75 quantiles.
+
+      Returns:
+         List[TestItem]: Selected item.
+
+
+adaptivetesting.implementations.SemiAdaptiveImplementation
+==========================================================
+
+class adaptivetesting.implementations.SemiAdaptiveImplementation(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)
+
+   Bases: "AdaptiveTest"
+
+   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.
+
+   estimate_ability_level(answered_items_difficulties: List[float]) -> 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]*).
+
+      Args:
+         answered_items_difficulties (List[float]): List of difficulty
+         values of the answered items
+
+      Returns:
+         estimation: ability estimation
+
+   pre_test()
+
+      Runs pretest

documentation/adaptivetesting.math.txt

@@ -0,0 +1,89 @@
+adaptivetesting.math package
+****************************
+
+
+adaptivetesting.math.MLEstimator
+================================
+
+class adaptivetesting.math.MLEstimator(response_pattern: List[int], item_difficulties: List[float])
+
+   Bases: "object"
+
+   This class can be used to estimate the current ability level of a
+   respondent given the response pattern and the corresponding item
+   difficulties. The estimation is based on maximum likelihood
+   estimation and the Rasch model.
+
+   Args:
+      response_pattern (List[int]): list of response patterns (0:
+      wrong, 1:right)
+
+      item_difficulties (List[float]): list of item difficulties
+
+   d1_log_likelihood(ability: ndarray) -> float
+
+      First derivative of the log-likelihood function.
+
+      Args:
+         ability (np.ndarray): ability level
+
+      Returns:
+         float: log-likelihood value of given ability value
+
+   get_maximum_likelihood_estimation() -> float
+
+      Estimate the current ability level by searching for the maximum
+      of the likelihood function. A line-search algorithm is used.
+
+      Returns:
+         float: ability estimation
+
+
+adaptivetesting.math.standard_error
+===================================
+
+adaptivetesting.math.standard_error(answered_items: List[float], estimated_ability_level: float) -> float
+
+   Calculates the standard error using the test information function.
+
+   Args:
+      answered_items (List[float]): List of answered items
+
+      estimated_ability_level (float): Currently estimated ability
+      level
+
+   Returns:
+      float: Standard error
+
+
+adaptivetesting.math.test_information_function
+==============================================
+
+adaptivetesting.math.test_information_function(item_difficulties: ndarray, ability_level: ndarray) -> float
+
+   Calculates test information.
+
+   Args:
+      item_difficulties (np.ndarray): List of answered items
+
+      ability_level (np.ndarray): Currently estimated ability level
+
+   Returns:
+      float: test information
+
+
+adaptivetesting.math.urrys_rule
+===============================
+
+adaptivetesting.math.urrys_rule(items: List[TestItem], ability: float) -> TestItem
+
+   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