NAME

Schedule::Activity::Annotation - Schedule around other events

SYNOPSIS

my $annotation=Schedule::Activity::Annotation->new(
  message=>Schedule::Activity::Message configuration,
  nodes  =>qr/.../,
  before =>{
    min=>30,
    max=>90,
  }
  between=>120,
  p      =>1.00,
  limit  =>3,
  attributes=>{...},
);

my @notes=$annotation->annotate(@{$schedule{activities}});
@{$schedule{activities}}=sort {$$a[0]<=>$$b[0]} @{$schedule{activities}},@notes;

# or as a single step (not yet supported)
$annotation->insert($schedule{activities});

DESCRIPTION

A scheduling annotation is a secondary event to be attached to an existing schedule. The given message will be inserted around the matching action keynames (nodes), with probability p, and may be inserted throughout the schedule up to limit times. Inserted messages will be min to max seconds before the matching nodes, if the annotation can be placed directly adjacent to the matching node, and the spacing between different instances of the annotation must be at least between.

Annotations permit the scheduling of messages that are not directly associated with activities/actions and can often be helpful to provide the user with reminders, warning messages, or to set the mood, pace, and so forth. In the example of an exercise schedule where the actions are exercise sets, annotations can be used to choose the music or provide positive/supportive messages.

EXPERIMENTAL: This syntax is subject to change.

CONFIGURATION

The message, required, should match any form supported in Schedule::Activity.

The nodes, required, is a regular expression that specifies the matching activity/action key names. Use alternation to match against more than one candidate key. Since activities always start and finish with specific nodes, an annotation is unlikely to be needed for an event that follows/precedes each. One benefit of annotations in such a case is the ability to leverage different annotation configurations with the same scheduling configuration.

The default before values are one, which means an annotation will be placed 1sec before the matching node if there is space in the schedule. Within a configured range, an annotation will only be placed adjacent to the matching action. A minimum can be used to ensure the user has time to hear/read the message and react. Negative values can be used to place the annotation after the matching node.

The between value, default 1sec, limits the total number of annotations based on the proximity of the matching actions. No more than one annotation will be attached to each action.

The rate p is the probability of the annotation being attached to a matching node. Default 1.

The limit specifies the maximum number of annotations to attach. limit=0 or undefined is unlimited.

ATTRIBUTES

Attributes can be attached to the annotation itself and/or within the message object. Note that the annotate and insert helpers only provide updates to the schedule. The caller must update any attribute statistics within the schedule as well as the summary statistics for the overall schedule. Future improvements in insert may support a setting/callback for updating statistics, but there is a benefit to keeping annotation schedules separate from the main list of activities: Multiple annotations are easier to recompute when not attached to the main schedule, permitting easier adjustment toward attribute goals.