repetition module

repetition

The repetition module is the primary interface into the spaced package. The repetition module provides access to a LearningTracker class which can be used to build student training goals, to track their progress and output a schedule which reacts to their behaviour. From this schedule, predictions can be made about their future performance.

Example(s):

Here is how you can build a learning tracker, input some student feedback and graph its predictions about a student’s future performance:

from datetime import datetime
from repetition import LearningTracker

lt = LearningTracker(epoch=datetime.now())
for d, r in zip(
  [0,    0.8,  1.75, 3.02, 4.8,  7.33],
  [0.40, 0.44, 0.64, 0.76, 0.83, 0.89],
):
  # r: result
  # d: days since training epoch
  lt.learned(result=r, when=d)

with lt.graphs(
  stop=43,
  show=True,
  control_handle=True,
  filename="module_docstring_example.svg") as ch:
   
    moments = lt.range_for(curve=1, stop=43, day_step_size=0.5)
    predictions = [
      lt.predict_result(moment, curve=1) for moment in moments
    ]
    ch.plot(moments, predictions, color='xkcd:azure')

The repetition module provides a lot of features which can be read about in the full spaced-package documentation

class repetition.ControlData(object_handle, *args, **kwargs)

Bases: object

domain
long_term_potentiation_graph
o
range
class repetition.LearningTracker(*args, **kwargs)

Bases: object

add_event(feedback_moment, result)

Adds a training event to the learning tracker.

Args:
feedback_moment (int, float): moment as time offset in days from epoch
result (float): how well the student performed (0.0-1.0)
animate(name_of_mp4=None, student=None, time_per_event_in_seconds=None, stop=None)

Creates an mp4 video of a student’s training up to the moment indicated by the stop input argument.

Note:
This function uses the animation feature of the matplotlib library.
Args:
name_of_mp4=None (string): name and path of the resulting output video
student=None (string): name of the student to be placed on the video
time_per_event_in_seconds=None (int): time per frame event
stop=None (int, float, datetime): when to stop the video. If an

int or float provided, this indicates the number of days since the training epoch.

days_from_epoch(time)

Converts a datetime object into a number representing the days since the training epoch.

Args:
time (int, float): days since the training epoch
Returns:
(float): days since training epoch
discovered_fdecay0()

Returns the control’s discovered fdecay0 parameter.

discovered_fdecaytau()

Returns the control’s discovered fdecaytau parameter.

discovered_plasticity_denominator_offset()

Returns the control’s discovered denominator_offset parameter.

discovered_plasticity_root()

Returns the control’s discovered plasticity_root parameter.

epoch_fdecay0()

Returns the reference’s fdecay0 parameter.

epoch_fdecaytau()

Returns the reference’s fdcecaytau parameter.

epoch_plasticity_denominator_offset()

Returns the reference’s plasticity_denominator_offset parameter.

epoch_plasticity_root()

Returns the reference’s plasticity_root parameter.

feedback(time_format=None)

Returns a list of the feedback events seen by this learning tracker.

Args:
time_format(None) (TimeFormat): OFFSET or DATE_TIME
Returns:
(list): moment of feedback in the specified format.
graphs(stop, filename=None, reference_handle=False, feedback_handle=False, error_handle=False, control_handle=False, show=False)
Writes graphs, yields the requested graph handles, writes to file
and automatically closes the graph handlers all within a context manager.
Args:
stop (datetime, float, int): when to stop graphing
filename="None" (string): The file name and extension (defining how it will be saved)
reference_handle="False" (bool): Reference graph handle needed?
feedback_handle="False" (bool): Feedback graph handle needed?
error_handle="False" (bool): Error graph handle needed?
control_handle="False" (bool): Control graph handle needed?
Yields:
(tuple): graphs handles as described by input args

Example(s):

from datetime import datetime
from spaced import LearningTracker

lt = LearningTracker(epoch=datetime.now())

moments = lt.range_for(curve=1, stop=43, day_step_size=0.5)
predictions = [
  lt.recollect_scalar(moment, curve=1) for 
  moment in momemts]

with lt.graphs(stop=43, filename='contenxt_demo.pdf') as c_hdl:
  c_hdl.plot(moments, predictions, color='xkcd:azure')

# the ordering of the handles provided by the context manager
# matches the graph ordering.
# 1 - reference
# 2 - feedback
# 3 - error
# 4 - control
with lt.graphs(stop=43, filename='contenxt_demo.pdf',
  control_handle=True, reference_handle=True) as (r_dl, c_hdl):

  c_hdl.plot(moments, predictions, color='xkcd:azure')
learned(when, result)

Tells the learning tracker about something the student has learned.

Args:
when (int, float, datetime): moment as either time offset in days from epoch, or the moment of training represented by a datetime object
result (float): how well the student performed (0.0-1.0)
next()

Returns the next suggested time to study as a datetime object

Returns:
(datetime): next suggested lesson
next_offset()
Returns the next suggested time to study as a float, representing the
number of days since the training epoch.
Returns:
(float): next suggested lesson [days since training epoch]
plot_graphs(stop)

Plots the reference, feedback, error and control data points on one graph.

Args:
stop (datetime, float, int): when to stop graphing
Returns:
(tuple): (PlotPaneData, dict)
predict_result(moment, curve=None)

(alias for recollect_scalar) Predicts a student’s recollection ability, at a specified time, on a specifiy forgetting curve.

Args:
moment (float, int, datetime, timedelta): see note
curve=None (int): Which forgetting curve to use in the prediction

Note:

The moment input can be one of these types:

  • float - representing the number of days since epoch (when the
    spaced_repetition algorithm started to track)
  • datetime - a datetime object, which must be after epoch
  • timedelta - the difference in time from when the client wants to know
    something and epoch
Returns:
(float): a number between 0 and 1. 0 means the idea is completely forgotten and 1 means the idea is perfectly remembered.
range_for(stop, curve=None, day_step_size=1)

Returns a list of useful datetime values for a given curve, up to, but not including the stop value, in increments of day_step_size.

Args:
stop (datetime, float, int): datetime or offset from epoch in days
curve=None (type1): default: which forgetting curve, starting at 1
day_step_size=1 (type1): step size of the result (unit of days)
Returns:
(list): list of datetimes that can be used in another query
recollect_scalar(moment, curve=None)

Predicts a student’s recollection ability, at a specified time, on a specifiy forgetting curve.

Args:
moment (float, int, datetime, timedelta): see note
curve=None (int): Which forgetting curve to use in the prediction

Note:

The moment input can be one of these types:

  • float - representing the number of days since epoch (when the
    spaced_repetition algorithm started to track)
  • datetime - a datetime object, which must be after epoch
  • timedelta - the difference in time from when the client wants to know
    something and epoch
Returns:
(float): a number between 0 and 1. 0 means the idea is completely forgotten and 1 means the idea is perfectly remembered.
save_figure(filename=None)

Save the graph plotted by the plot_graphs method to file.

Args:
filename="spaced.pdf" (string): The file name and extension (defining how it will be saved)
Notes:
This method uses the matplotlib library, which will automatically save the plot in the format indicated by the file name’s extension.
schedule(stop)

Returns a schedule as of datetimes, up-until and possibily-including the datetime or offset represented by the stop argument.

Args:
stop (float, int, datetime): at what point do you want the schedule

information to stop. If stop is an int or a float it will be interpreted as the number of days-from-epoch at which you would like this function to stop providing information. If stop is a datetime, the output schedule will include all of the schedule suggestions up until that time.

Returns:
(list of datetime objects): The schedule
schedule_as_offset(stop)

Return a schedule as a list of offsets measured in days from the training epoch, up-until and possibily-including the datetime or offset reprented by the stop argument.

Args:
stop (float, int, datetime): at what point do you want the schedule

information to stop. If stop is an int or a float it will be interpreted as the number of days-from-epoch at which you would like this function to stop providing information. If stop is a datetime, the output schedule will include all of the schedule suggestions up until that time.

Returns:
(list of floats): The schedule as offset from the training epoch
show()
class repetition.SpaceRepetition(*args, **kwargs)

Bases: object

Default_Samples = 100
Horizontal_Axis = ''
Vertical_Axis = ''
datetime_to_days_offset_from_epoch(datetime_)

Convert a datetime object into a float, representing the number of days difference between that datetime and when epoch.

Args:
datetime_ (datetime)
Returns:
(float): datetime_ - datetime of training epoch
days_from_epoch(time)

Converts a datetime object into a number representing the days since the training epoch.

Args:
time (int, float, datetime): days since the training epoch
Returns:
(float): days, as an offset, since the training epoch
days_from_start(time)

(alias for days_from_epoch) Converts a datetime object into a number representing the days since the training epoch.

Args:
time (int, float): days since the training epoch
Returns:
(float): days since training epoch
days_offset_from_epoch_to_datetime(offset_)

Convert a days-offset-from-epoch into a datetime object.

Args:
offset_ (int, float): days since training epoch
Returns:
(datetime): datetime of the moment which was offset_ days since the training epoch
days_to_time(days)

Converts a time [offset in days from epoch] into a datetime object.

Args:
days (int, float): days since epoch
Returns:
(datetime): datetime of epoch plus days
forgetting_curves(scale, offset)

Returns two other functions which have the values of scale and offset enclosed within them.

Args:
scale (int, float): enclosed parameter
offset (int, float): enclosed parameter
Returns:
(tuple): fn, fn0

The returned functions are:

  • fn(x): the falling-exponential forgetting curve profile
  • fn0(x, y): y - fn(x)

Where fn(x) is:

e^(scale*(x-offset))

scale determines how fast the forgetting curve falls

offset determines how far to shift the curve to the right

scale = -0.7
offset = 10


1096 |                                                        
     |                                                        
     |  .                                                     
     |                                                        
     |   .                                                    
     |    .                                                   
     |                                                        
     |     .                                                  
 548 | -----\-------------------------------------------------
     |       \                                                
     |        \                                               
     |         \                                              
     |          ..                                            
     |            \                                           
     |             ...                                        
     |                ...                                     
     |                   .....                                
1.13 |                        ................................
          0                      5                          10
make_stickleback_data_for_plot(forgetting_functions, solutions, stop_day_as_offset)

Creates the data set that can be used to graph the stickleback curve.

Args:
forgetting_functions (list): forgetting_functions
solutions (list): x values where forgetting function intersects the plasticity curve
stop_day_as_offset (float, int): days after epoch to stop construction of stickleback
Returns:
(list of two lists): x and y values of stickleback data
plasticity_functions(denominator_offset, root)

Returns three other functions which have the values of denominator_offset and root enclosed within them.

Args:
denominator_offset (int, float): enclosed parameter
root (int, float): enclosed parameter
Returns:
(tuple): fn(x), fn0(x, y), invfn(y)

These returned functions are:

  • fn(x): the plasticity curve for the student
  • fn0(x, y): y - fn(x), needed to find intersection with this curve and another
  • invfn(y): returns the x value which provides y from fn(x)

Where fn(x) is:

             x^(1/root)
------------------------------------ for x > shift
 (x + denominator_offset)^(1/root)

0 for x <= shift

example:
  root = 1.8
  denominator_offset = 1.0


  0.94754 |                          ...........................
          |                 .........                           
          |            .....                                    
          |         ...                                         
          |       ..                                            
          |      /                                              
          |     /                                               
          |    /                                                
  0.47377 | --.-------------------------------------------------
          |                                                     
          |                                                     
          |  .                                                  
          |                                                     
          |                                                     
          |                                                     
          |                                                     
          |                                                     
        0 | .                                                   
            0                      5                          10

Where fn0(x,y) is:

y - fn(x)

Where invfn(y) is:

                             y^(root)
-1 *denominator_offset * --------------- for 0 <= y <= 1
                            y^(root) - 1

example
  root = 1.8
  denominator_offset = 1.0

  6.89791 |                                                    
          |                                                    
          |                                                    
          |                                                    
          |                                                    
          |        .                                           
          |                                                    
          |         ...                                        
  0.77734 | -----------........................................
          |                                                    
          | ....                                               
          |                                                    
          |     .                                              
          |                                                    
          |                                                    
          |                                                    
          |                                                    
  -5.3432 |      .                                             
            0                      5                          10
tune_decay_of_decay(initial, tau)

Returns a tuned-decay_of_decay function. The decay_of_decay, function can be called over and over again with greater values of t, and it will return a set of scalars which can be used to build, less and less agressive forgetting curves.

To make this function tunable, you can enclose the initial and tau parameters within it.

Args:
initial (float): enclosed parameter
tau (float): enclosed parameter
Returns:
(function): fn(x), a curve which reaches an asymptote of 0, but is clamped to -1*self.long_term_clamp before it gets there.

fn(x) is:

-1 * initial * e^(-x/tau) clamped to -1*self.long_term_clamp

initial determines where to start the curve. It is negated by the function, its value determines at what negative y value to start.

tau determines how fast the forgetting curves should transition from a fast state of forgetting to a slower state of forgetting.

        |
        | ---------------------------- self.long_term_clamp -
-0.0003 |                     ...............................
        |                .....                               
        |             ...                                    
        |           ..                                       
        |          /                                         
        |         /                                          
        |        /                                           
        |       /                                            
-0.7001 | -----/---------------------------------------------
        |     .                                              
        |                                                    
        |    .                                               
        |                                                    
        |   .                                                
        |                                                    
        |  .                                                 
        |                                                    
   -1.4 | .   
          0                      5                        10
class repetition.SpaceRepetitionController(*args, **kwargs)

Bases: repetition.SpaceRepetition

DECAY_INITIAL_VALUE_KD = 0.03
DECAY_INITIAL_VALUE_KI = 0.1
DECAY_INITIAL_VALUE_KP = 0.5
DECAY_TAU_KD = 0.04
DECAY_TAU_KI = 0.1
DECAY_TAU_KP = 0.5
LONG_TERM_CLAMP = 5e-05
control(control_x=None)

Runs the space repetition control system.

Args:
control_x=None (int, float): offset in days where to start control

system. This value defaults to the last time the student provided feedback.

datetime_for(curve=None)

Returns the datetime of a specified training suggestion.

The moment of this suggestion is represented by the curve input argument. The curve numbers are indexed from 1, not 0. The curve is the forgetting curve for which you want the start-date of.

Args:
curve=None (int): The number of the forgetting curve. The curves

are indexed from 1, not 0. If no argument is provided, the curve number will be set to 1.

Returns:
(datetime): The suggested training moment.
error(x)

Build an error signal event given x.

The error signal is the result of the reference-plasticity-function(x), minus the feedback-plasticity-function(x).

Args:
x (int, float): offset in days from epoch
Returns:
(float): reference plasticity result - feedback plasticity result
a positive error means we need to push harder
a negative error means we are pushing too hard
initialize_feedback(feedback, stop=None)

Initializes the controller’s feedback information.

Args:
feedback (SpaceRepetitionFeedback): feedback object
stop=None (int, float): days offset since epoch
next()

Returns the next suggested time to study as a datetime object

Returns:
(datetime): next suggested lesson
next_offset()
Returns the next suggested time to study as a float, representing the
number of days since the training epoch.
Returns:
(float): next suggested lesson [days since training epoch]
plot_control(stop, plot_pane_data=None, panes=None)

Plots the control data.

Args:
stop (datetime, float, int): when to stop graphing
plot_pane_data=None (int, float): plot handle
panes=None (type1): number of sub-plot panes to make
Returns:
(tuple): (PlotPaneData, dict)
plot_error(stop, plot_pane_data=None, panes=None)

Plots the error signal.

Args:
stop (datetime, float, int): when to stop graphing
plot_pane_data=None (int, float): plot handle
panes=None (type1): number of sub-plot panes to make
Returns:
(tuple): (PlotPaneData, dict)
plot_graphs(stop=None)

Plots the reference, feedback, error and control data points on one graph.

Args:
stop (datetime, float, int): when to stop graphing
Returns:
(tuple): (PlotPaneData, dict)
predict_result(moment, curve=None)

(alias for recollect_scalar) Predicts a student’s recollection ability at a specified time on a specified forgetting curve.

Args:
moment (float, int, datetime, timedelta): see note
curve=None (int): Which forgetting curve to use in the prediction

Note:

The moment input can be one of these types:

  • float - representing the number of days since epoch (when the
    spaced_repetition algorithm started to track)
  • datetime - a datetime object, which must be after epoch
  • timedelta - the difference in time from when the client wants to know
    something and epoch
Returns:
(float): a number between 0 and 1. 0 means the idea is completely forgotten and 1 means the idea is perfectly remembered.
prediction(moment, curve=None)

(alias for recollect_scalar) Predicts a student’s recollection ability at a specified time on a specified forgetting curve.

Args:
moment (float, int, datetime, timedelta): see note
curve=None (int): Which forgetting curve to use in the prediction

Note:

The moment input can be one of these types:

  • float - representing the number of days since epoch (when the
    spaced_repetition algorithm started to track)
  • datetime - a datetime object, which must be after epoch
  • timedelta - the difference in time from when the client wants to know
    something and epoch
Returns:
(float): a number between 0 and 1. 0 means the idea is completely forgotten and 1 means the idea is perfectly remembered.
range_for(stop, curve=None, day_step_size=1)

Returns a list of useful datetime values for a given forgetting-curve, up to, but not including the stop value, in increments of day_step_size.

Args:
stop (datetime, float, int): datetime or offset from epoch in days
curve=None (type1): default: which forgetting curve, starting at 1
day_step_size=1 (type1): step size of the result (unit of days)
Returns:
(list): list of datetimes that can be used in another query
recollect_scalar(moment, curve=None)

Predicts a student’s recollection ability at a specified time on a specified forgetting curve.

Args:
moment (float, int, datetime, timedelta): see note
curve=None (int): Which forgetting curve to use in the prediction

Note:

The moment input can be one of these types:

  • float - representing the number of days since epoch (when the
    spaced_repetition algorithm started to track)
  • datetime - a datetime object, which must be after epoch
  • timedelta - the difference in time from when the client wants to know
    something and epoch
Returns:
(float): a number between 0 and 1. 0 means the idea is completely forgotten and 1 means the idea is perfectly remembered.
save_figure(filename='spaced.pdf')

Saves a graph made with the plot_graphs method, to file.

Args:
filename="spaced.pdf" (string): The file name and extension (defining how it will be saved)
Notes:
This method uses the matplotlib library, which will automatically save the plot in the format indicated by the file name’s extension.
schedule(stop)

Returns the learning schedule.

This list will contain the recommended training moments up to, and possibly including the date described by the stop input argument.

Args:
stop (int, float, datetime): At what point to stop the schedule
if stop is an int or float it represents the days since the training epoch
Returns:
(list): list of datetime objects containing the recommended training schedule.
schedule_as_offset(stop)
Returns the learning schedule as a list offsets measure in days since
they training epoch.

This list will contain the recommended training moments up to, and possibly including the date described by the stop input argument.

Args:
stop (int, float, datetime): At what point to stop the schedule
if stop is an int or float it represents the days since the training epoch
Returns:
(list): list of floats containing a the recommended schedule in days
since the training epoch
show()

Show the graph you have plotted using the plot_graphs method.

class repetition.SpaceRepetitionDataBuilder(*args, **kwargs)

Bases: object

class repetition.SpaceRepetitionFeedback(*args, **kwargs)

Bases: repetition.SpaceRepetition

LongTermPotentiationColor = 'xkcd:teal'
StickleBackColor = 'xkcd:red'
Title = 'Spaced Memory Feedback\n'
Vertical_Axis = 'observed'
add_event(feedback_moment, result)

Adds a feedback moment to the feedback dataset.

Args:
feedback_moment (int, float, datetime): the self examination moment
result (type1): how well they did 0.0 to 1,0
Returns:

(list) [plasticity curve, discovered_plasticity_root, discovered_plasticity_denominator_offset]

  • fn: the plasticity curve that matches what the student is actually doing
  • discovered_plasticity_root: can be fed into

plasticity_functions of the reference object to make a reference plasticty curve that matches this one. * discovered_plasticity_denominator_offset: can be fed into the plasticity_functions of the reference object to make a reference plasticity curve that matches this one.

plasticity_functions()

Returns the observed plasticity function and two discovered plasticity parameters.

Returns:

(list): fn, discovered_plasticity_root, discovered_plasticity_denominator_offset

  • fn: the plasticity curve that matches what the student is actually doing
  • discovered_plasticity_root: can be fed into

plasticity_functions of the reference object to make a reference plasticty curve that matches this one. * discovered_plasticity_denominator_offset: can be fed into the plasticity_functions of the reference object to make a reference plasticity curve that matches this one.

plot_graph(plot_pane_data=None, panes=None, stop=None)

Plots the feedback data.

Args:
stop (datetime, float, int): when to stop graphing
plot_pane_data=None (int, float): plot handle
panes=None (type1): number of sub-plot panes to make
Returns:
(type): SpaceRepetitionPlot, dict
show()

Shows the feedback plot after the plot_graph method is call.

class repetition.SpaceRepetitionReference(plot=None, *args, **kwargs)

Bases: repetition.SpaceRepetition

Default_Samples = 50

(int): The default number of samples to generate for the reference graph

Forgetting_Decay_Initial_Value = 1.4
Forgetting_Decay_Tau = 1.2
Horizontal_Axis = ''

(string): The title of the horizontal axis of the reference graph

Initial_Forgetting_Offset = 0.0
LongTermPotentiationColor = 'xkcd:blue'

(string): The color of the reference graph’s plasticity curve

Max_Length = 100
PlasticityDenominatorOffset = 1.0
PlasticityRoot = 1.8
StickleBackColor = 'xkcd:orangered'

(string): The color of the skickleback forgetting curves

Title = 'Spaced Memory Reference\n'

(string): The title of the reference graph

Vertical_Axis = 'recommendation'

(string): The title of the vertical axis of the reference graph

plot_graph(stop, plot_pane_data=None, panes=None)

Plots the reference data.

Args:
stop (datetime, float, int): when to stop graphing
plot_pane_data=None (int, float): plot handle
panes=None (type1): number of sub-plot panes to make
Returns:
(tuple): (PlotPaneData, dict)
predict_result(moment, curve=None)

(alias for recollect_scalar) Provides a recollection prediction at a provided moment after a given schedule point.

The moment input can be one of these types:

  • float - representing the number of days since epoch (when the
    spaced_repetition algorithm started to track)
  • datetime - a datetime object, which must be after epoch
  • timedelta - the difference in time from when the client wants to know
    something and epoch

The moment must occur after the curve number has been activated

range_for(stop, curve=None, day_step_size=1)

Returns a list of useful datetime values for a given curve, up to, but not including the stop value, in increments of day_step_size.

Args:
stop (datetime, float, int): datetime or offset from epoch in days
curve=None (type1): default: which forgetting curve, starting at 1
day_step_size=1 (type1): step size of the result (unit of days)
Returns:
(list): list of datetimes that can be used in another query
recollect_scalar(moment, curve=None)

Provides a recollection prediction at a provided moment after a given schedule point.

The moment input can be one of these types:

  • float - representing the number of days since epoch (when the
    spaced_repetition algorithm started to track)
  • datetime - a datetime object, which must be after epoch
  • timedelta - the difference in time from when the client wants to know
    something and epoch

The moment must occur after the curve number has been activated

save_figure(filename='spaced.pdf')

Saves the file produced by the plot_graph method.

Args:
filename="spaced.pdf" (string): filename
schedule(stop)

Returns a training schedule as of datetimes up until and possibily including datetime or offset represented by stop.

Args:
stop (float, int, datetime): at what point do you want the schedule

information to stop. If stop is an int or a float it will be interpreted as the number of days-from-epoch at which you would like this function to stop providing information. If stop is a datetime, the output schedule will include all of the schedule suggestions up until that time.

Returns:
(list of datetime objects): The schedule
schedule_as_offset(stop)

Returns a training schedule as a list of offsets measured in days from the training epoch.

Args:
stop (float, int, datetime): at what point do you want the schedule

information to stop. If stop is an int or a float it will be interpreted as the number of days-from-epoch at which you would like this function to stop providing information. If stop is a datetime, the output schedule will include all of the schedule suggestions up until that time.

Returns:
(list of floats): The schedule as offset from the training epoch
show()

show the plot after a plot_graph method call

class repetition.SpacedKwargInterface(*args, **kwargs)

Bases: object

class repetition.TimeFormat

Bases: enum.Enum

An enumeration.

DATE_TIME = 2
OFFSET = (1,)
repetition.pp(thing)