FSRS Optimizer

The FSRS Optimizer is a Python library capable of utilizing personal spaced repetition review logs to refine the FSRS algorithm. Designed with the intent of delivering a standardized, universal optimizer to various FSRS implementations across numerous programming languages, this tool is set to establish a ubiquitous standard for spaced repetition review logs. By facilitating the uniformity of learning data among different spaced repetition softwares, it guarantees learners consistent review schedules across a multitude of platforms.

Delve into the underlying principles of the FSRS Optimizer's training process at: https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-mechanism-of-optimization

Explore the mathematical formula of the FSRS model at: https://github.com/open-spaced-repetition/fsrs4anki/wiki/The-Algorithm

Review Logs Schema

The review_logs table captures the review activities performed by users. Each log records the details of a single review instance. The schema for this table is as follows:

Column Name	Data Type	Description	Constraints
card_id	integer or string	The unique identifier of the flashcard being reviewed	Not null
review_time	timestamp in miliseconds	The exact moment when the review took place	Not null
review_rating	integer	The user's rating for the review. This rating is subjective and depends on how well the user believes they remembered the information on the card	Not null, Values: {1 (Again), 2 (Hard), 3 (Good), 4 (Easy)}
review_state	integer	The state of the card at the time of review. This describes the learning phase of the card	Optional, Values: {0 (New), 1 (Learning), 2 (Review), 3 (Relearning)}
review_duration	integer	The time spent on reviewing the card, typically in miliseconds	Optional, Non-negative

Extra Info:

• timezone: The time zone of the user when they performed the review, which is used to identify the start of a new day.
• day_start: The hour (0-23) at which the user starts a new day, which is used to separate reviews that are divided by sleep into different days.

Notes:

• All timestamp fields are expected to be in UTC.
• The card_id should correspond to a valid card in the corresponding flashcards dataset.
• review_rating should be a reflection of the user's memory of the card at the time of the review.
• review_state helps to understand the learning progress of the card.
• review_duration measures the cost of the review.
• timezone should be a string from the IANA Time Zone Database (e.g., "America/New_York"). For more information, refer to this list of IANA time zones.
• day_start determines the start of the learner's day and is used to correctly assign reviews to days, especially when reviews are divided by sleep.

Please ensure your data conforms to this schema for optimal compatibility with the optimization process.

Optimize FSRS with your review logs

Installation

Install the package with the command:

python -m pip install fsrs-optimizer

You should upgrade regularly to make sure you have the most recent version of FSRS-Optimizer:

python -m pip install fsrs-optimizer --upgrade

Opimization

If you have a file named revlog.csv with the above schema, you can run:

python -m fsrs_optimizer "revlog.csv"

Expected Functionality