Memory Utilities

PyRBIT defines several utilities that deal with memory models and experiments, of which we present here

The MemoryModel class

All memory models in PyRBIT inherit from the MemoryModel class, and have to redefine the update method (how is the state of the memory model update when item is shown at time) and the compute_probabilities method (computes the probability of recall for all items at time. If time is None, should use the last time where any item was presented.)

class MemoryModel:
    def __init__(self, nitems, seed=None, **kwargs):
        self.nitems = nitems
        self.rng = numpy.random.default_rng(seed=seed)

    @abstractmethod
    def update(self, item, time):
        raise NotImplementedError

    @abstractmethod
    def compute_probabilities(self, time=None):
        raise NotImplementedError

    def query_item(self, item, time):
        prob = self.compute_probabilities(time=time)[item]
        return (self.rng.random() < prob, prob)

Schedules

from pyrbit.mem_utils import Schedule, BlockBasedSchedule

items = [0, 1, 0, 1, 0, 1, 0, 0]
times = [0, 100, 126, 200, 252, 500, 4844, 5877]

# Building a schedule
schedule = Schedule(items, times)
# You can iterate over a schedule
for item, time in schedule:
    print(item, time)

# [block-schedule]
# You can create a block based schedule, where you specify a constant intertrial time (which includes execution time), interblock times (this also implicitly specifies the number of blocks), and whether items are repeated. You can also add some randomness by adding a random time for each item, drawn from a lognormal distribution with scale sigma_t.
schedule = BlockBasedSchedule(
    5, 5, [10, 20, 30, 30], repet_trials=2, seed=123, sigma_t=1
)
# you can print the schedule, which also shows block identifiers
schedule.print_schedule()

Trials

# You can apply a schedule to a memory model and gather queries using run_trials
from pyrbit.ef import ExponentialForgetting
from pyrbit.mem_utils import run_trials

ef = ExponentialForgetting(5, 0.01, 0.4, seed=123)
queries, ef = run_trials(ef, schedule, reset=True)
print(queries)
print(ef.counters)

# If you have learning blocks distinct from test blocks, you can use the test_blocks argument. This assumes that in a learning block the memory model is always updated, but not queried, while in a testing block, the memory model is always queried, and updated when that query is correct.
queries, ef = run_trials(ef, schedule, test_blocks=[1, 3], reset=True)
print(queries)
print(ef.counters)

Populations

# You can sample from a Gaussian population of memory models. Each memory model will have a different seed that spawns from the population's seed.
population_model = GaussianPopulation(
    ExponentialForgetting,
    mu=[0.01, 0.4],
    sigma=1e-3 * numpy.array([[0.1, 0], [0, 1]]),
    population_size=3,
    n_items=5,
    seed=123,
)
# you can iterate over a population
for p in population_model:
    print(p)

Experiments

# You can perform an experiment, by having members of the population perform trials. The data has shape (replication, 2, schedule_length, population_size); The dimension 2 is for (recall, recall_probability). Note that you can use a list of memory models rather than population objects.
data = experiment(population_model, schedule, replications=4)

population_model = GaussianPopulation(
    ExponentialForgetting,
    mu=[0.01, 0.4],
    sigma=1e-7 * numpy.array([[0.1, 0], [0, 1]]),
    population_size=4,
    n_items=5,
    seed=123,
)
data = experiment(population_model, schedule, replications=1)
data, trials = experiment(
    population_model,
    schedule,
    replications=1,
    test_blocks=[1, 3, 4],
    get_trial_info=True,
)
# You can also reshape the experiment data to have shape (replication, 2, nblocks, repet_trials, nitems, population_size)
rdata = reshape_experiment(data, 5, 2, 3)