On this page:
1.1 Event Structures
1.2 Event Datum
1.3 Vectors of Events
eventkey
k  Event  Keys
make-event
make-zero-event
make-events-from-timestamps
set-event-preintervals
event-val
event-start
event-end
event-middle
event-magnitude
event-duration
event-busy
event-subevents-index
event-subevents-count
event-preinterval
event-set!
event-set-timestamp!
event-set-magnitude!
event-set-duration!
event-set-busy!
event-set-subevents-index!
event-set-subevents-count!
events->timestamps-list
sum-values
interval-start-to-start
interval-start-to-end
interval-end-to-start
interval-end-to-end
events-ref
events-count
events-first
events-last
events-proper-vector
nth-event
last-nth-event
n-events
last-n-events
events-within-events
scale-duration
scale-interevent
scale-busy
unscale-duration
unscale-interevent
unscale-busy
find-and-scale-interval
1.4 Event Records
make-event-record
make-extended-event-record
read-event-record-from-data
read-all-event-records-from-data
read-event-record-from-file
file->event-record
8.0

1 Events

Data structures and functions for sequences of behavioral events

    1.1 Event Structures

    1.2 Event Datum

    1.3 Vectors of Events

    1.4 Event Records

1.1 Event Structures

Behavioral events are discrete extensions of action through time, so that they have a discrete start time, duration, and endtime (although near-instantaneous events may have a duration indistinguiable from zero). Examples of event are a single lick, a discrete meal, a bodily movement such as a scratch, a burst of vocalization, or the lack of movement such as a rest period.

Events may also have a magnitude, depending on the type of behavior: a bout of licking consists of a certain magnitude (number) of licks, a meal may consist of a certain magnitude (grams) of food, a limb extension has a magnitude of distance traveled, or a magntiude of force exerted.

Furthermore, events are frequently hierarchical or decomposable, with the property that they are composed of subevents: a single liquid meal may be composed of 10 bouts of licking, with each bout containing between 100 to 1000 indiviudal licks, for example. Frequently the analysis of behavior requires reducing smaller units of events into larger units, eg. licks into meals.

Events are arranged in sequences across time, either as repetitions of the same event, or a sequence of varied event types interdigited and even co-extensive in time.

In BoutTime, event data (individual Event Datums) are collected into Vectors of Events, and packaged with metadata as Event Records.

There are multiple ways to represent and transform these time sequences, and to analyze and visualize them. See sections on Bout Analysis, Event Transitions, and Ethograms.

1.2 Event Datum

An event datum is an event that begins at a specific timestamp, posseses a magnitude, and persists for a duration. Every event specification requires a timestamp, but duration and magnitude are optional (and set to defaults of 0 and 1 respectively). The event is stored as a 5-vector. #(timestamp magnitude duration busy-time subeventsIndex subeventsCount)

An event can be 1 of 3 types (all represented by the same vector structure):

- An instantaneous (or very quick) event that occurs at a timestamp, but has no measurable (or recorded) duration. Each occurrence of the event has a fixed scalar magnitude of 1. An example might be a single lick recorded at timestamp 1138 ms. For convenience and efficiency, an instaneous event is stored as a single numeric timestamp eg 1138 as a durationless vector with magnitude 1, #(1138 1 0 0 0 0).

- An instantaneous event that occurs at a timestamp, and has no duration, but with a variable magnitude. This type of event could be stored as #(1138 3.14 0 0 0 0).

- A extended event, which has occurs (starts) at a timestamp, endures for a certain length of time (ie it has a duration), and has a variable scalar magnitude. An extended event is stored as a 3-vector #( timestamp magnitude duration). An example might be a foodjar-feeding bout recorded by an electronic balance as 3.14 g intake beginning at timestamp 43200 s across a duration of 300 s, stored as #(43200 3.14 300 0 0 0).

An event datum is an event that begins at a specific timestamp, posseses a magnitude, and persists for a duration. Every event specification requires a timestamp, but duration and magnitude are optional (and set to defaults of 0 and 1 respectively). The event is stored as a 5-vector.

Individual events are represented by a short vector:

'#(<timestamp> <magnitude> <duration> <busy-time> <subevents-count> <subevents-index>)

Events typically are of 1 of 3 types:

- An instantaneous (or very quick) event that occurs at a timestamp, but has no measurable (or recorded) duration. Each occurrence of the event has a fixed scalar magnitude of 1. An example might be a single lick recorded at timestamp 1138 ms. For convenience and efficiency, an instaneous event is stored as a single numeric timestamp eg 1138 as a durationless vector with magnitude 1, #(1138 1 0 0 0 0).

- An instantaneous event that occurs at a timestamp, and has no duration, but with a variable magnitude. This type of event could be stored as #(1138 3.14 0 0 0 0).

- A extended event, which has occurs (starts) at a timestamp, endures for a certain length of time (ie it has a duration), and has a variable scalar magnitude. An extended event is stored as a 3-vector #( timestamp magnitude duration). An example might be a foodjar-feeding bout recorded by an electronic balance as 3.14 g intake beginning at timestamp 43200 s across a duration of 300 s, stored as #(43200 3.14 300 0 0 0).

Events are constructed by

"(make-event #:timestamp   #:magnitude  #:duration   #:busy   #:subevents-index  #:subevents-count #:preinterval )",

or when a sequence of timestamped events is loaded from a datafile by ...

The values of an individual event can be accessed using getters (eg "(event-timestamp theEvent), (event-duration theEvent)", etc., and set with setters "(event-timestamp-set! theEvent 86400)". See XXXX for the list of setters and getters.

1.3 Vectors of Events

 (require "../event-series.rkt") package: base

struct

(struct eventkey (name symbol value description))

  name : string?
  symbol : symbol?
  value : integer?
  description : string?
desc-expr ...

value

kEventKeys : (listof eventkey?)

A list of the keys for referencing components of an event.
  • "kTimestampKey"

  • "kMagnitudeKey"

  • "kDurationKey"

  • "kBusyKey"

  • "kSubEventsKey"

  • "kSubEventsCountKey"

  • "kPreIntervalKey"

procedure

(make-event #:timestamp ts    
  [#:magnitude mag    
  #:duration dur    
  #:busy busy    
  #:subevents-index se    
  #:subevents-count sec    
  #:preinterval preint])  vector?
  ts : nonnegative-integer?
  mag : number? = 1
  dur : nonnegative-integer? = 0
  busy : nonnegative-integer? = dur
  se : (or/c  #f nonnegative-integer?) = kNotFoundKey
  sec : nonnegative-integer? = 0
  preint : (or/c boolean? rational?) = #f
convert a timestamp ts in milliseconds, create an event (represented as a vector). Elements of the event vector can be referenced using the pre-defined "kEventKeys": "kTimestampKey", "kMagnitudeKey", "kDurationKey", "kSubEventsKey", "kSubEventsCountKey", or by using the setters and getters below.

procedure

(make-zero-event)  vector?

make an event of vector with all elements set to zero.

procedure

(make-events-from-timestamps #:timestamps timestamps    
  [#:duration duration    
  #:starttime starttime])  vector?
  timestamps : (vectorof nonnegative-integer?)
  duration : nonnegative-integer? = 0
  starttime : (or/c #f nonnegative-integer?) = #f
given a vector of time stamps, make a vector of events of magnitude 1 and given duration (or default to 0) (the defaults for an event). starttime should be start time of data recording, used to calculate latency of first event (which otherwise defaults to #f

procedure

(set-event-preintervals #:events events 
  [#:starttime starttime]) 
  (vectorof vector?)
  events : (vectorof vector?)
  starttime : (or/c #f nonnegative-integer?) = #f
given a vector of events, set the intervals between the events (event start to end of previous event (event start + duration)). Mutates events in place, and returns original events with the new intervals incorporated. This usually needs to be done after an event vector is constructed, because hard to find intervals when instantiating event vector in the first place. The preinterval of the first event is either the latency from starttime, or, if not start is not provided, set to #f (to indicate unknown latency)

procedure

(event-val event index)  (or/c boolean? number?)

  event : vector?
  index : integer?
convenience function to look up values of an event; get the "index" element of the "event" vector.

procedure

(event-start event)  nonnegative-integer?

  event : vector?
wrapper for "(event-val event kTimestampKey)"

procedure

(event-end event)  nonnegative-integer?

  event : vector?
derived from event-start and event-duration

procedure

(event-middle event)  nonnegative-integer?

  event : vector?
derived from event-start and event-duration

procedure

(event-magnitude event)  number?

  event : vector?
wrapper for "(event-val event kMagnitudeKey)"

procedure

(event-duration event)  nonnegative-integer?

  event : vector?
wrapper for "(event-val event kDurationKey)"

procedure

(event-busy event)  nonnegative-integer?

  event : vector?
wrapper for "(event-val event kBusyKey)"

procedure

(event-subevents-index event)  (or/c #f nonnegative-integer?)

  event : vector?
wrapper for "(event-val event kSubEventsIndexKey)"

procedure

(event-subevents-count event)  nonnegative-integer?

  event : vector?
wrapper for "(event-val event kSubEventsCountKey)"

procedure

(event-preinterval event)  (or/c #f nonnegative-integer?)

  event : vector?
wrapper for "(event-val event kPreIntervalKey)"

procedure

(event-set! event index val)  any

  event : vector?
  index : integer?
  val : number?
convenience function to set the value of an event; set the "index" element of the "event" vector.

procedure

(event-set-timestamp! event val)  any

  event : vector?
  val : nonnegative-integer?
wrapper for "(event-set! event kTimestampKey val)"

procedure

(event-set-magnitude! event val)  any

  event : vector?
  val : number?
wrapper for "(event-set! event kMagnitudeKey val)"

procedure

(event-set-duration! event val)  any

  event : vector?
  val : nonnegative-integer?
wrapper for "(event-set! event kDurationKey val)"

procedure

(event-set-busy! event val)  any

  event : vector?
  val : nonnegative-integer?
wrapper for "(event-set! event kBusyKey val)"

procedure

(event-set-subevents-index! event val)  any

  event : vector?
  val : (or/c #f nonnegative-integer?)
wrapper for "(event-set! event kSubEventsIndexKey val)"

procedure

(event-set-subevents-count! event val)  any

  event : vector?
  val : nonnegative-integer?
wrapper for "(event-set! event kSubEventsCountKey val)"

procedure

(events->timestamps-list events)  list?

  events : vector?
return the timestamps of the events as a regular list

procedure

(sum-values #:value-key key    
  #:event1 e1    
  #:event2 e2)  number?
  key : integer?
  e1 : vector?
  e2 : vector?
return the sum of the values at the given key for two events

procedure

(interval-start-to-start #:event1 e1    
  #:event2 e2)  nonnegative-integer?
  e1 : vector?
  e2 : vector?
get the interval time between two events; depending on where you measure the start/end of the interval

procedure

(interval-start-to-end #:event1 e1    
  #:event2 e2)  nonnegative-integer?
  e1 : vector?
  e2 : vector?

procedure

(interval-end-to-start #:event1 e1    
  #:event2 e2)  nonnegative-integer?
  e1 : vector?
  e2 : vector?

procedure

(interval-end-to-end #:event1 e1    
  #:event2 e2)  nonnegative-integer?
  e1 : vector?
  e2 : vector?

procedure

(events-ref events index)  vector?

  events : vector?
  index : nonnegative-integer?

procedure

(events-count events)  nonnegative-integer?

  events : vector?

procedure

(events-first events)  vector?

  events : vector?

procedure

(events-last events)  vector?

  events : vector?

procedure

(events-proper-vector events #:key key)  vector?

  events : vector?
  key : integer?
returns a "proper" (sorted) vector sort events as ascending series based on value of key

procedure

(nth-event #:events events #:n n)  vector?

  events : vector?
  n : nonnegative-integer?
1 indexed, so n=1 is first event

procedure

(last-nth-event #:events events #:n n)  vector?

  events : vector?
  n : nonnegative-integer?
1 indexed from end of event vector, so n=1 is last event

procedure

(n-events #:events events #:n n)  vector?

  events : vector?
  n : nonnegative-integer?
returns a vector containing the first n events in the events vector

procedure

(last-n-events #:events events #:n n)  vector?

  events : vector?
  n : nonnegative-integer?
returns a vector containing the last n events in the events vector

procedure

(events-within-events sub-events    
  super-events)  (vectorof vector?)
  sub-events : (vectorof vector?)
  super-events : (vectorof vector?)
given two event vectors, return only those sub-events that occur during the super-events only include sub-events that start and end completely within a super-event does NOT include sub-events that start before super-event (but end within super event duration), and does NOT sub-events that start within super-event (but end after super event duration)

  sub-events: ---xxxx----xxxx---xxxxx----xx---xx----x----xxx-xxxx-x-xxx-xx--xxxx---xxx-
super-events: -----ssssssssssssssssssss----------------sssssssssssssssssssssss---------
    filtered: -----------xxxx---xxxxx--------------------xxx-xxxx-x-xxx-xx-------------

procedure

(scale-duration dur)  (or/c #f nonnegative-integer?)

  dur : (or/c #f nonnegative-integer?)

procedure

(scale-interevent dur)  (or/c #f nonnegative-integer?)

  dur : (or/c #f nonnegative-integer?)

procedure

(scale-busy dur)  (or/c #f nonnegative-integer?)

  dur : (or/c #f nonnegative-integer?)

procedure

(unscale-duration dur)  (or/c #f nonnegative-integer?)

  dur : (or/c #f nonnegative-integer?)

procedure

(unscale-interevent dur)  (or/c #f nonnegative-integer?)

  dur : (or/c #f nonnegative-integer?)

procedure

(unscale-busy dur)  (or/c #f nonnegative-integer?)

  dur : (or/c #f nonnegative-integer?)

procedure

(find-and-scale-interval last-timestamp 
  current-timestamp) 
  (or/c boolean? rational?)
  last-timestamp : (or/c #f nonnegative-integer?)
  current-timestamp : (or/c #f nonnegative-integer?)

1.4 Event Records

 (require "../event-record.rkt") package: base

procedure

(make-event-record #:name name    
  #:events events    
  #:color color    
  [#:file-start-time file-start-time    
  #:subrecord subrecord    
  #:type type])  hash?
  name : string?
  events : vector?
  color : string?
  file-start-time : integer? = 0
  subrecord : vector? = null
  type : string? = "recorder"
event record

a hash with

’events: vector of events ’name: name of events ’color: color to use when plotting this event series ’subrecord: the event-record containing the subevents, if events are devired from the sequence of subevents ’min-size [min-size 0] ’min-ibi ’binsize

’file-start-time taken from the data file

extended event record includes a bunch of derived

’bouts – events vector using find-bouts

derived, using kMagnitudeKey as the event quantity

’binned – events vector using binned-event-vals ’cumul – events vector using cumulative-events ’sum – sum-of-events ’mean – mean-of-events ’max – max-of-events ’min – min-of-events ’max-density – max-density-of-events

’start-time – min-of-events using kTimestampKey ’end-time – max-of-events using kTimestampKey

procedure

(make-extended-event-record #:name name 
  #:events events 
  #:color color 
  #:min-ibi ibi 
  [#:file-start-time file-start-time 
  #:subrecord subrecord 
  #:type type 
  #:min-size min-size 
  #:binsize binsize]) 
  hash?
  name : string?
  events : vector?
  color : string?
  ibi : nonnegative-integer?
  file-start-time : (or/c #f nonnegative-integer?) = #f
  subrecord : vector? = null
  type : string? = "recorder"
  min-size : number? = 0
  binsize : nonnegative-integer? = 300000
extended event record

precalculate cumulative, binned, and summary stats..

procedure

(read-event-record-from-data file-rows    
  #:eventname type    
  #:expt expt)  hash?
  file-rows : list?
  type : string?
  expt : list?
read event-record of specific eventname type from rows of a data file

procedure

(read-all-event-records-from-data file-rows    
  #:expt expt)  (listof hash?)
  file-rows : list?
  expt : list?
return a list of all event-records (regardless of event type) extracted from rows of a data file

procedure

(read-event-record-from-file data-file-path    
  #:eventname type    
  #:expt expt)  hash?
  data-file-path : string?
  type : string?
  expt : list?
read event-record of specific eventname type from data file, containing comment rows, a header line, and timestamped data points

procedure

(file->event-record #:filename filename    
  #:name name    
  #:color color    
  #:min-ibi ibi    
  #:binsize binsize)  hash?
  filename : string?
  name : string?
  color : string?
  ibi : nonnegative-integer?
  binsize : nonnegative-integer?