Skip to main content

Implemented the SM-2 algorithm for spaced repetition learning.

Project description

SuperMemo2

Python Version Build Coverage Download

A package that implemented the spaced repetition algorithm SM-2 for you to quickly calculate your next review date for whatever you are learning.

📌  Note: The algorithm SM-2 doesn't equal to the computer implementation SuperMemo2. In fact, the 3 earliest implementations (SuperMemo1, SuperMemo2 and SuperMemo3) all used algorithm SM-2. I didn't notice that when I first published the package on PyPI, and I can't change the package name.

📦  PyPI page

Table of Contents

Motivation

The goal was to have an efficient way to calculate the next review date for studying/learning. Removes the burden of remembering the algorithm, equations, and math from the users.

Installation and Supported Versions

Package Install

Install and upate the package using pip:

pip3 install -U supermemo2

To Play Around with the Code

Download the code:

git clone https://github.com/alankan886/SuperMemo2.git

Install dependencies to run the code:

pip3 install -r requirements.txt

supermemo2 supports Python 3+

A Simple Example

from supermemo2 import SMTwo

# first review
# using quality=4 as an example, read below for what each value from 0 to 5 represents
# review date would default to date.today() if not provided
review = SMTwo.first_review(4, "2021-3-14")
# review prints SMTwo(easiness=2.36, interval=1, repetitions=1, review_date=datetime.date(2021, 3, 15))

# second review
review = SMTwo(review.easiness, review.interval, review.repetitions).review(4, "2021-3-14")
# review prints similar to example above.

Features

📣  Calculates the review date of the task following the SM-2 algorithm.
📣  The first_review method to calculate the review date at ease without having to know the initial values.

What is SM-2?

🎥  If you are curious of what spaced repetition is, check this short video out.

📌  A longer but interactive article on spaced repetition learning.

📎  The SM-2 Algorithm

What are the "values"?

The values are the:

  • Quality: The quality of recalling the answer from a scale of 0 to 5.
    • 5: perfect response.
    • 4: correct response after a hesitation.
    • 3: correct response recalled with serious difficulty.
    • 2: incorrect response; where the correct one seemed easy to recall.
    • 1: incorrect response; the correct one remembered.
    • 0: complete blackout.
  • Easiness: The easiness factor, a multipler that affects the size of the interval, determine by the quality of the recall.
  • Interval: The gap/space between your next review.
  • Repetitions: The count of correct response (quality >= 3) you have in a row.

Code Reference

class supermemo2.SMTwo(easiness, interval, repetitions)

Parameters:

  • easiness (float) - the easiness determines the interval.
  • interval (int) - the interval between the latest review date and the next review date.
  • repetitions (int) - the count of consecutive reviews with quality larger than 2.

first_review( quality, review_date=None, date_fmt=None )

      Static method that calcualtes the next review date for the first review without having to know the initial values, and returns a dictionary containing the new values.

Parameters:

  • quality (int) - the recall quality of the review.
  • review_date (str or datetime.date) - optional parameter, the date of the review.
  • date_fmt (string) - optional parameter, the format of the review_date. Formats like year_mon_day, mon_day_year and day_mon_year.

Returns: dictionary containing values like quality, easiness, interval, repetitions and review_date.

Return Type: Dict

Usage:

from supermemo2 import SMTwo, mon_day_year
# using default date date.today()
SMTwo.first_review(3)

# providing string date in Year-Month-Day format
SMTwo.first_review(3, "2021-12-01")

# providing string date in Month-Day-Year format
SMTwo.first_review(3, "12-01-2021", mon_day_year)

# providing date object date
from datetime import date
d = date(2021, 12, 1)
SMTwo.first_review(3, d)

review( quality, review_date=None, date_fmt=None )

      Calcualtes the next review date based on previous values, and returns a dictionary containing the new values.

Parameters:

  • quality (int) - the recall quality of the review.
  • review_date (str or datetime.date) - optional parameter, the date of the review.
  • date_fmt (string) - optional parameter, the format of the review_date. Formats like year_mon_day, mon_day_year and day_mon_year.

Returns: dictionary containing values like quality, easiness, interval, repetitions and review_date.

Return Type: Dict

Usage:

from supermemo2 import SMTwo, mon_day_year
# using previous values from first_review call
r = SMTwo.first_review(3)

# using default date date.today()
SMTwo(r.easiness, r.interval, r.repetitions).review(3)

# providing string date in Year-Month-Day format
SMTwo(r.easiness, r.interval, r.repetitions).review(3, "2021-12-01")

# providing string date in Month-Day-Year format
SMTwo(r.easiness, r.interval, r.repetitions).review(3, "12-01-2021", mon_day_year)

# providing date object date
from datetime import date
d = date(2021, 12, 1)
SMTwo(r.easiness, r.interval, r.repetitions).review(3, d)

Testing

Assuming you dowloaded the code and installed requirements.

Run the tests

pytest tests/

Check test coverages

pytest --cov

Check coverage on Codecov.

Changelog

2.0.0 (2021-03-28): Major changes/rebuild, Update recommended

  • Rebuilt and simplfied the package.

1.0.3 (2021-01-30): Minor bug fix, Update recommended

  • Re-evaluate the default date argument to first_review() on each call.

1.0.2 (2021-01-18): Major and Minor bug fix, Update recommended

  • Add required attrs package version to setup.py.
  • Allow users to access SMTwo model.
  • Fix E-Factor calculation when q < 3.

1.0.1 (2021-01-02): Fix tests, update README and add Github actions, Update not required

  • Add missing assertions to test_api.py.
  • Update README badges and fix format.
  • Add Github actions to run tests against Python versions 3.6 to 3.9 in different OS, and upload coverage to Codecov.

1.0.0 (2021-01-01): Complete rebuild, Update recommended

  • Build a new SMTwo class using the attrs package.
  • Provide API methods to quickly access the SMTwo class.
  • Develop 100% coverage integration and unit tests in a TDD manner.
  • Write new documentation.

0.1.0 (2020-07-14): Add tests, Update not required

  • Add passing unit tests with a coverage of 100%.

0.0.4 (2020-07-10): Minor bug fix, Update recommended

  • Fix interval calculation error when q < 3.

0.0.3 (2020-07-06): Documentation Update, Update not required

  • Add new section about SM-2 in documentation, and fix some formats in README.

0.0.2 (2020-07-05): Refactor feature, Update recommended

  • Refactor the supermemo2 algorithm code into a simpler structure, and remove unnecessary methods in the class.

0.0.1 (2020-07-02): Feature release

  • Initial Release

Credits

  1. pytest
  2. The SM-2 Algorithm

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

supermemo2-2.0.0.tar.gz (6.1 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page