supermemo2 1.0.3

Implemented the SuperMemo-2/SM-2 algorithm for spaced repetition learning.

SuperMemo2

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
• Installing and Supported Versions
• A Simple Example
• Features
  • Potential Features
• What is SuperMemo-2?
• API Reference
  • Main Interface
  • Exceptions
  • Lower-Level Classes
• Testing
• Changelog
• Credits

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.6+ and requires attrs >= 20.1.0.

A Simple Example

We start with a recall quality of 3, and the review date defaults to today (let's pretend it's 2021-01-01).

Using the current values from the first review can help us calculate for the second review.

Grab the current values from the first review, and update the recall quality. Then calculate the next review date.

>>> from supermemo2 import first_review
>>> smtwo = first_review(3)
>>> print(smtwo.review_date)
2021-01-02
>>> record = smtwo.as_dict(curr=True)
>>> record["quality"] = 5
>>> smtwo.calc(**record)
>>> print(smtwo.review_date)
2021-01-08

Features

📣  Calculates the next review date of the task following the SuperMemo-2/SM-2 algorithm.
📣  The first_review method to create a new instance at ease without having to know the initial values.
📣  The modify method to modify existing instance values that recalculates the new values.
📣  The json and dict methods to export the instance values and to help calculate the next review date.

Potential Features

• Allow users to pass the review date as a string in many formats.

What is SuperMemo-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 SuperMemo-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.

API Reference

Main Interface

supermemo2.first_review(quality, review_date=datetime.date.today())

      Calcualtes next review date without having to know the initial values, and returns an SMTwo object with new values.

      Parameters:

• quality(int) - the quality of the response/recall from a scale of 0 to 5.
• review_date (Optional[datetime.date]) - the last review date.

      Returns: SMTwo object

      Return Type: supermemo2.SMTwo

      Usage:

>>> from supermemo2 import first_review
>>> from datetime import date
>>> smtwo = first_review(3, date(2021, 1, 1))
>>> print(smtwo.review_date)
2021-01-02

supermemo2.modify(instance, quality=None, easiness=None, interval=None, repetitions=None, review_date=None)

      Modifies previously inserted values.

      Parameters:

• instance (SMTwo) - the SMTwo instance to modify.
• quality (Optional[int]) - the quality value to replace the previous quality value.
• easiness (Optional[float])- the easiness value to replace the previous easiness value.
• interval (Optional[int]) - the interval value to replace the previous interval value.
• repetitions (Optional[int]) - the repetitions value to replace the previous reptitions value.
• review_date (Optional[datetime.date]) - the review date to replace the previous review date.

      Returns: None

      Return Type: None

      Usage:

>>> from supermemo2 import first_review, modify
>>> smtwo = first_review(3)
>>> print(smtwo.quality)
3
>>> modify(smtwo, quality=5)
>>> print(smtwo.quality)
5

Exceptions

exception supermemo2.exceptions.CalcNotCalledYet

      Other methods are called before the values are calculated.

Lower-Level Classes

class supermemo2.SMTwo()

      Generates all the instances and contains the tools.

      I would not recommend directly generating an instance from this class.

calc(quality, easiness, interval, repetitions, review_date)

      Calculates the values. For the first review, the initial/previous values would be 2.5 for easiness, 1 for interval and 1 for repetitions.

      Parameters:

• quality (Optional[int]) - the quality value received from the last calculation.
• easiness (Optional[float])- the easiness value received from the last calculation.
• interval (Optional[int]) - the interval value received from the last calculation.
• repetitions (Optional[int]) - the repetitions value received from the last calculation.
• review_date (Optional[datetime.date]) - the review date received from the last calculation.

      Returns: None

      Return Type None

      Usage:

>>> from supermemo2 import SMTwo
>>> from datetime import date
>>> smtwo = SMTwo()
>>> smtwo.calc(3, 2.5, 1, 1, date(2021, 1, 1))
>>> print(smtwo.review_date)
2021-01-02

json(prev=None, curr=None)

      Returns a string of the values in JSON format.

      Parameters:

• prev (Optional[bool]) - If true, export only previous values.
• curr (Optional[bool]) - If true, export only current values.

      Returns: String in JSON format

      Return Type String

      Usage:

>>> from supermemo2 import first_visit
>>> from datetime import date
>>> smtwo = first_visit(3, date(2021, 1, 1))
>>> print(smtwo.json())
'{"quality": 3, "prev_easiness": 2.5, "prev_interval": 1, "prev_repetitions": 1, "prev_review_date": datetime.date(2021, 1, 1),"easiness": 2.36, "interval": 2, "repetitions": 1, "review_date": datetime.date(2021, 1, 2)}'

dict(prev=None, curr=None)

      Returns a the values in dictionary format.

      Parameters:

• prev (Optional[bool]) - If true, export only previous values.
• curr (Optional[bool]) - If true, export only current values.

      Returns: Dictionary

      Return Type Dict

      Usage:

>>> from supermemo2 import first_visit
>>> from datetime import date
>>> smtwo = first_visit(3, date(2021, 1, 1))
>>> print(smtwo.dict())
'{"quality": 3, "prev_easiness": 2.5, "prev_interval": 1, "prev_repetitions": 1, "prev_review_date": datetime.date(2021, 1, 1),"easiness": 2.36, "interval": 2, "repetitions": 1, "review_date": datetime.date(2021, 1, 2)}'

class supermemo2.SMTwo.Prev(easiness, interval, repetitions, review_date)

      Stores the previous values.

      Parameters:

• easiness (float)- the previous easiness value.
• interval (int) - the previous interval value.
• repetitions (int) - the previous repetitions value.
• review_date (datetime.date) - the previous review date.

Testing

Assuming you dowloaded the code and installed requirements.

Run the tests

pytest tests/

Check test coverages

pytest --cov=supermemo2

Check coverage on Codecov.

Changelog

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 SuperMemo-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. attrs
2. pytest
3. The SuperMemo-2 Algorithm