Skip to content

event.py

Events are linked to Trials

activate(schema_name, *, create_schema=True, create_tables=True, linking_module=None)

Activate this schema.

Parameters:

Name Type Description Default
schema_name str

schema name on the database server

 required
create_schema bool

when True (default), create schema in the database if it does not yet exist.

 True
create_tables str

when True (default), create schema tables in the database if they do not yet exist.

 True
linking_module str

a module (or name) containing the required dependencies.

 None

Dependencies:

Upstream tables

Session: parent table to BehaviorRecording, identifying a recording session. Project: the project with which experimental sessions are associated Experimenter: the experimenter(s) participating in a given session To supply from element-lab add Experimenter = lab.User to your workflow/pipeline.py before session.activate()

Functions

get_experiment_root_data_dir(): Retrieve the root data director(y/ies) with behavioral recordings (e.g., bpod files) for all subject/sessions, returns a string for full path to the root data directory. get_session_directory(session_key: dict): Retrieve the session directory containing the recording(s) for a given Session, returns a string for full path to the session directory

Source code in element_event/event.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def activate(
    schema_name, *, create_schema=True, create_tables=True, linking_module=None
):
    """Activate this schema.

    Args:
        schema_name (str): schema name on the database server
        create_schema (bool): when True (default), create schema in the database if it
                            does not yet exist.
        create_tables (str): when True (default), create schema tables in the database
                             if they do not yet exist.
        linking_module (str): a module (or name) containing the required dependencies.

    Dependencies:
    Upstream tables:
        Session: parent table to BehaviorRecording, identifying a recording session.
        Project: the project with which experimental sessions are associated
        Experimenter: the experimenter(s) participating in a given session
                      To supply from element-lab add `Experimenter = lab.User`
                      to your `workflow/pipeline.py` before `session.activate()`
    Functions:
        get_experiment_root_data_dir(): Retrieve the root data director(y/ies) with
                                        behavioral recordings (e.g., bpod files) for
                                        all subject/sessions, returns a string for
                                        full path to the root data directory.
        get_session_directory(session_key: dict): Retrieve the session directory
                                                containing the recording(s) for a
                                                given Session, returns a string for
                                                full path to the session directory
    """

    if isinstance(linking_module, str):
        linking_module = importlib.import_module(linking_module)
    assert inspect.ismodule(linking_module), (
        "The argument 'dependency' must" + " be a module or module name"
    )

    schema.activate(
        schema_name,
        create_schema=create_schema,
        create_tables=create_tables,
        add_objects=linking_module.__dict__,
    )

get_experiment_root_data_dir()

Pulls relevant func from parent namespace to specify root data dir(s).

It is recommended that all paths in DataJoint Elements stored as relative paths, with respect to some user-configured "root" director(y/ies). The root(s) may vary between data modalities and user machines. Returns a full path string to behavioral root data directory or list of strings for possible root data directories.

Returns:

Name Type Description
Paths list

List of path(s) to root directories for event data
Source code in element_event/event.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
def get_experiment_root_data_dir() -> list:
    """Pulls relevant func from parent namespace to specify root data dir(s).

    It is recommended that all paths in DataJoint Elements stored as relative
    paths, with respect to some user-configured "root" director(y/ies). The
    root(s) may vary between data modalities and user machines. Returns a
    full path string to behavioral root data directory or list of strings
    for possible root data directories.

    Returns:
        Paths (list): List of path(s) to root directories for event data
    """
    return _linking_module.get_experiment_root_data_dir()

get_session_directory(session_key)

Pulls relative function from parent namespace.

Retrieves the session directory containing the recorded data for a given Session. Returns a string for full path to the session directory.

Returns:

Name Type Description
Session_dir str

Relative path to session directory
Source code in element_event/event.py 
75
76
77
78
79
80
81
82
83
84
85
def get_session_directory(session_key: dict) -> str:
    """Pulls relative function from parent namespace.

    Retrieves the session directory containing the recorded data for a given
    Session. Returns a string for full path to the session directory.

    Returns:
        Session_dir (str): Relative path to session directory
    """

    return _linking_module.get_session_directory(session_key)

EventType

Bases: dj.Lookup

Set of unique events present within a recording session

Attributes:

Name Type Description
event_type varchar(16)

Unique event type.
event_type_description varchar(256)

Event type description.
Source code in element_event/event.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
@schema
class EventType(dj.Lookup):
    """Set of unique events present within a recording session

    Attributes:
        event_type ( varchar(16) ): Unique event type.
        event_type_description ( varchar(256) ): Event type description.
    """

    definition = """
    event_type                : varchar(16)
    ---
    event_type_description='' : varchar(256)
    """

BehaviorRecording

Bases: dj.Manual

Behavior Recordings

Attributes:

Name Type Description
Session foreign key

Session primary key.
recording_start_time datetime

Start time of recording.
recording_duration float

Duration of recording.
recording_notes varchar(256)

Optional recording related notes.
Source code in element_event/event.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
@schema
class BehaviorRecording(dj.Manual):
    """Behavior Recordings

    Attributes:
        Session (foreign key): Session primary key.
        recording_start_time (datetime): Start time of recording.
        recording_duration (float): Duration of recording.
        recording_notes ( varchar(256) ): Optional recording related notes.
    """

    definition = """
    -> Session
    ---
    recording_start_time=null : datetime
    recording_duration=null   : float
    recording_notes=''     : varchar(256)
    """

    class File(dj.Part):
        """File IDs and paths associated with a behavior recording

        Attributes:
            BehaviorRecording (foreign key): Behavior recording primary key.
            filepath ( varchar(64) ): file path of video, relative to root data dir.
        """

        definition = """
        -> master
        filepath              : varchar(64)
        """

File

Bases: dj.Part

File IDs and paths associated with a behavior recording

Attributes:

Name Type Description
BehaviorRecording foreign key

Behavior recording primary key.
filepath varchar(64)

file path of video, relative to root data dir.
Source code in element_event/event.py 
126
127
128
129
130
131
132
133
134
135
136
137
class File(dj.Part):
    """File IDs and paths associated with a behavior recording

    Attributes:
        BehaviorRecording (foreign key): Behavior recording primary key.
        filepath ( varchar(64) ): file path of video, relative to root data dir.
    """

    definition = """
    -> master
    filepath              : varchar(64)
    """

Event

Bases: dj.Imported

Automated table with event related information

WRT: With respect to

Attributes:

Name Type Description
BehaviorRecording foreign key

Behavior recording primary key.
EventType foreign key

EventType primary key.
event_start_time decimal(10, 4

Time of event onset in seconds, WRT recording start.
event_end_time float

Optional. Seconds WRT recording start.
Source code in element_event/event.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
@schema
class Event(dj.Imported):
    """Automated table with event related information

    WRT: With respect to

    Attributes:
        BehaviorRecording (foreign key): Behavior recording primary key.
        EventType (foreign key): EventType primary key.
        event_start_time (decimal(10, 4)): Time of event onset in seconds, WRT recording start.
        event_end_time (float): Optional. Seconds WRT recording start.
    """

    definition = """
    -> BehaviorRecording
    -> EventType
    event_start_time          : decimal(10, 4)  # (second) relative to recording start
    ---
    event_end_time=null       : float  # (second) relative to recording start
    """

    def make(self, key):
        """Populate based on unique entries in BehaviorRecording and EventType."""
        raise NotImplementedError("For `insert`, use `allow_direct_insert=True`")

make(key)

Populate based on unique entries in BehaviorRecording and EventType.

Source code in element_event/event.py 
161
162
163
def make(self, key):
    """Populate based on unique entries in BehaviorRecording and EventType."""
    raise NotImplementedError("For `insert`, use `allow_direct_insert=True`")

AlignmentEvent

Bases: dj.Manual

Table designed to provide a mechanism for performing event-aligned analyses

To use entries from trial.Trial, trial_start_time and trial_end_time must be entered in the Event table. WRT = With respect to

Attributes alignment_name ( varchar(32) ): Unique alignment name. alignment_description ( varchar(1000) ): Optional. Longer description. alignment_event_type (foreign key): Event type to align to. alignment_time_shift (float): Seconds WRT alignment_event_type start_event_type (foreign key): Event before alignment event type start_time_shift (float): Seconds WRT start_event_type end_event_type (foreign key): Event after alignment event type end_time_shift (float): Seconds WRT end_event_type

Source code in element_event/event.py 
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
@schema
class AlignmentEvent(dj.Manual):
    """Table designed to provide a mechanism for performing event-aligned analyses

    To use entries from trial.Trial, trial_start_time and trial_end_time must be entered
    in the Event table. WRT = With respect to

    Attributes
        alignment_name ( varchar(32) ): Unique alignment name.
        alignment_description ( varchar(1000) ): Optional. Longer description.
        alignment_event_type (foreign key): Event type to align to.
        alignment_time_shift (float): Seconds WRT alignment_event_type
        start_event_type (foreign key): Event before alignment event type
        start_time_shift (float): Seconds WRT start_event_type
        end_event_type (foreign key): Event after alignment event type
        end_time_shift (float): Seconds WRT end_event_type

    """

    definition = """ # time_shift is seconds to shift with respect to (WRT) a variable
    alignment_name: varchar(32)
    ---
    alignment_description='': varchar(1000)  
    -> EventType.proj(alignment_event_type='event_type') # event type to align to
    alignment_time_shift: float                      # (s) WRT alignment_event_type
    -> EventType.proj(start_event_type='event_type') # event before alignment_event_type
    start_time_shift: float                          # (s) WRT start_event_type
    -> EventType.proj(end_event_type='event_type')   # event after alignment_event_type
    end_time_shift: float                            # (s) WRT end_event_type
    """