Simulator Configuration Extraction - open-spaced-repetition/fsrs-rs GitHub Wiki

This document outlines the algorithm for extracting personalized simulator configuration parameters from a user's review log (Revlog). The algorithm analyzes a user's historical behavior to generate a set of statistics that reflect their unique learning and review habits.

Core Methodology

The core of the algorithm is the aggregation of discrete review entries into meaningful "daily review sessions." A daily review session is defined as the collection of all review actions performed by the user on a single card within a single calendar day. This aggregation forms the basis for all subsequent probability and cost calculations.

Parameter Calculation

1. state_rating_costs

This parameter estimates the user's average time (i.e., "cost") for pressing each rating button in different contexts.

• Definition: A 3x4 matrix where state_rating_costs[state][rating] represents the average time in seconds a user takes to press a specific rating button (0-Again, 1-Hard, 2-Good, 3-Easy) in a given state (0-Learning, 1-Review, 2-Relearning).
• Calculation:
  1. All review log entries are traversed.
  2. The time taken for each review (taken_millis) is grouped according to its state (review_kind) and the rating chosen (button_chosen).
  3. For each group (e.g., all "Good" ratings in the "Review" state), the average time is calculated.
  4. This average time is converted from milliseconds to seconds and stored as the corresponding cost value in the matrix.

2. first_rating_prob

This parameter describes the probability distribution of a user's very first rating when encountering a new card.

• Definition: A 4-element array representing the probabilities of choosing Again, Hard, Good, or Easy during the first interaction of a "Learning" session.
• Calculation:
  1. All "Learning" sessions (i.e., sessions where a card was first studied) are identified.
  2. The number of times Again, Hard, Good, and Easy were pressed as the first rating in these sessions is counted.
  3. These counts are normalized by dividing each by the total count, yielding the probability distribution.

3. review_rating_prob

This parameter describes a user's rating preference during a regular review, given that they successfully recalled the card.

• Definition: A 3-element array representing the conditional probabilities of choosing Hard, Good, or Easy in a "Review" session, given that the card was successfully recalled (i.e., "Again" was not pressed).
• Calculation:
  1. All "Review" sessions are identified.
  2. The number of times Hard, Good, and Easy were pressed as the first rating in these sessions is counted. Note: "Again" ratings are excluded from this calculation.
  3. The counts for Hard, Good, and Easy are normalized by dividing each by the sum of just these three counts, yielding the conditional probability distribution.

4. learning_step_transitions & relearning_step_transitions

These parameters model a user's sequential rating behavior within a single "Learning" or "Relearning" session as a Markov chain. They describe the probability of pressing one button immediately after another.

• Definition: Two 3x4 transition matrices where matrix[prev_rating][next_rating] represents the probability of pressing next_rating immediately after having pressed prev_rating within the same session.
  • learning_step_transitions is for "Learning" sessions.
  • relearning_step_transitions is for "Relearning" sessions (i.e., review sessions that begin with an "Again" rating).
• Calculation:
  1. Identify Sequences: The full sequence of ratings for each relevant session type is collected (e.g., [1, 3, 4] for a session where the user pressed Again, then Good, then Easy).
  2. Count Transitions: For all collected sequences, the transitions between ratings are counted. For [1, 3, 4], one 1 -> 3 transition and one 3 -> 4 transition are recorded.
  3. Calculate Probabilities: The transition counts are normalized to form a probability matrix. For example, P(3 | 1) = (count of 1 -> 3 transitions) / (total count of all transitions originating from 1).

Final Smoothing

To prevent statistical bias arising from sparse data (e.g., a user rarely uses a certain button), a final smoothing step is performed.

• Principle: Uses Linear Interpolation (Lerp) to blend all parameters calculated from the user's data with a set of pre-defined, generic default parameters.
• Weighting: The weight of the blend is determined by the volume of data available for that parameter.
  • If the data volume is large (e.g., thousands of "Good" ratings), the weight is close to 1.0, and the personalized data is used almost exclusively.
  • If the data volume is small (e.g., only a few "Hard" ratings), the weight is low, and the final result will be closer to the generic default.

This step ensures that the resulting simulator configuration is robust and reasonable, even when user data is limited.