Fitts-FSRS Integration

This library integrates a Fitts-based memory model with an FSRS (Free Spaced Repetition Scheduler). The goal is to combine the predictive power of a Fitts memory model—which estimates recall performance based on review intervals, ease factors, and memory stability—with the robust scheduling features of FSRS.

Overview

Fitts Memory Model

The Fitts memory model in this library:

• Estimates Response Time:
  Based on the time since the last review, an ease factor (similar to SM-2), and memory stability (in days). The model uses a logarithmic transformation to compute a difficulty index and then a linear function to determine the estimated response time.
• Computes Retrievability:
  The probability of recalling the memory is calculated using the estimated response time. This value is normalized between 0 and 1.

The model can be trained using empirical review data (via MemoryReview records) with the provided fit_memory_model function.

FSRS Scheduler

FSRS is a spaced repetition scheduler that uses card parameters such as:

• Difficulty and Stability:
  These parameters affect the next review interval.
• Review Ratings:
  Common ratings include Again, Hard, Good, and Easy. FSRS leverages these ratings to adjust intervals, apply state transitions (e.g., Learning to Review), and incorporate fuzzing.

Integration: Fitts-FSRS

The integration layer (provided by the FittsFsrs struct) combines both systems:

1. Estimations from Fitts:
   It calculates the estimated response time and retrievability using the Fitts model.
2. Card Parameter Updates:
   It updates the card's difficulty and stability based on the difference between the estimated response time and a desired target (e.g., 1.5 seconds). This adjustment uses scaling factors that can be tuned.
3. Rating Adjustment:
   Based on the retrievability:
   • Low retrievability (< 0.5):
     • Easy → Good
     • Good → Hard
     • Hard → Again
     • Again remains unchanged
   • High retrievability (> 0.8):
     • Again → Hard
     • Hard → Good
     • Good → Easy
     • Easy remains unchanged
4. Full FSRS Scheduling:
   Finally, it calls FSRS’s next method with the updated card and adjusted rating, allowing FSRS to apply its complete scheduling logic (state transitions, interval calculation, etc.).

Features

• Fitts Memory Model:
  Provides methods to calculate the estimated response time and retrievability based on review metrics.
• Model Training:
  Train the Fitts model with empirical review data using a least-squares approach.
• Dynamic Card Updates:
  Adjusts card difficulty and stability based on deviations from a target response time.
• Comprehensive Rating Adjustment:
  Maps all four FSRS ratings based on retrievability, ensuring that scheduling decisions reflect actual performance.
• Seamless Integration with FSRS:
  Leverages FSRS’s advanced scheduling logic, including state management and interval fuzzing.

Installation

To include this library in your project, add it as a dependency in your Cargo.toml file. For example:

[dependencies]
# Assuming you have a local path to the fitts-fsrs integration library:
fitts_fsrs_integration = { path = "../fitts_fsrs_integration" }
rs_fsrs = { path = "../rs_fsrs" }

Alternatively, if the crate is published on crates.io, use its version number accordingly.

Usage

Below is an example of how to use the library in your project.

use chrono::Utc;
use fitts_fsrs_integration::{fit_memory_model, MemoryReview, FittsFsrs};
use rs_fsrs::{Card, FSRS, Parameters, Rating, State};

fn main() {
    // Simulate some review data to train the Fitts model.
    let reviews = vec![
        MemoryReview {
            interval_days: 1.0,
            ease: 2.3,
            stability: 1.0,
            response_time: 1.2,
        },
        MemoryReview {
            interval_days: 5.0,
            ease: 2.2,
            stability: 1.5,
            response_time: 1.7,
        },
        MemoryReview {
            interval_days: 12.0,
            ease: 2.0,
            stability: 2.5,
            response_time: 2.3,
        },
    ];
    let model = fit_memory_model(&reviews);

    // Create an instance of FSRS with default parameters.
    let parameters = Parameters::default();
    let fsrs_scheduler = FSRS::new(parameters);

    // Create the integration instance.
    let integration = FittsFsrs::new(model, fsrs_scheduler);

    // Create a sample card.
    let now = Utc::now();
    let card = Card {
        reps: 0,
        lapses: 0,
        state: State::New,
        due: now,
        last_review: now,
        scheduled_days: 0,
        elapsed_days: 0,
        difficulty: 1.0,
        stability: 1.0,
    };

    // Parameters for the Fitts model calculation.
    let interval_days = 10.0;
    let ease = 2.2;
    let stability = 2.0;

    // Assume the initial review rating is Good.
    let scheduling_info =
        integration.review_with_fitts(card, Rating::Good, now, interval_days, ease, stability);

    println!(
        "Next review scheduled on: {}",
        scheduling_info.card.due.to_rfc2822()
    );
    println!(
        "Adjusted review rating: {:?}",
        scheduling_info.review_log.rating
    );
}

Testing

The library includes tests to verify that the integration correctly adjusts card parameters and review ratings. To run tests, execute:

cargo test

The tests ensure that:

• The next review date is scheduled in the future.
• Ratings are adjusted based on both the estimated response time and retrievability.

Customization

You can tune the following parameters to better suit your application:

• Desired Response Time:
  The target response time (currently set at 1.5 seconds) can be adjusted.
• Scaling Factors:
  difficulty_adjustment_factor and stability_adjustment_factor control how strongly the Fitts model influences the card parameters.
• Rating Mapping:
  The mapping logic in the review_with_fitts method can be modified to adjust ratings differently based on retrievability.

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.

License

This project is licensed under the MIT License. See the LICENSE file for details.

This README provides a comprehensive guide on the purpose, functionality, and usage of the Fitts-FSRS integration library. If you have any questions or need further enhancements, please feel free to reach out!