Zone Occupancy Analysis¶

This tool analyzes and summarizes zone occupancy based on the center of the tracked bounding box and user-defined zones to output the following metrics:

• Total Time in Zone: The cumulative time the subject spent in each zone, calculated from the number of frames spent in each zone.
• Zone area: Calculates the areas of the annotated zones within the FOV (Field of view).
• Occupancy Score: Occupation score is a metric that reflects zone preference independentof zone area¹.
• Number of Zone Entries and exits: The number of times the subject entered and exited each zone.
• Length of Zone Occupancy Events: Duration of continuous periods of zone occupancy.
• Average Speed in Zone: The average speed of the subject in each zone.
• Instantaneous speed in zone: Calculated from the distance between consecutive keypoint estimates

Parameters¶

Details¶

Inputs¶

The tool expects two inputs. The first input is a tracking.csv file, which is in the IDEAS experiment annotations format. This format requires annotations to be structured in a table with one time-point (i.e., frame) per row, and one or more columns for annotations (e.g., x and y). This tool expects the following columns:

• Tracking point X: The x coordinate of the center of the bounding box.
• Tracking point Y: The y coordinate of the center of the bounding box.
• Frame Timestamp: A time reference for each frame.

An example of a table that can be used as input to this tool is shown below:

The second input is a zones.csv file, which is a table with one row per zone and columns for the zone name, and the zone vertices. The vertices can be specified as a list of x and y coordinates for each vertex, or as a center and major and minor axis for an ellipse. This tool expects the following columns:

• Name: The name of the zone.
• Type: The type of the zone, this will be rectangle, polygon, or ellipse.
• X # and Y #: A series of columns representing the X coordinates of the zone. If the type is ellipse, then the columns will be X 0, Y 0, for the centerpoint. If the type is rectangle, then the columns will be X 0, Y 0 through X 3, Y 3. If the type is polygon, then the columns will be X 0, Y 0 through X n, Y n.
• Major & Minor Axis: The major and minor axis diameters of the ellipse.
• Angle: The angle of the major axis of the ellipse.

An example of a table that can be used as input to this tool is shown below:

Valid tracking.csv and the zones.csv file can be generated from an .isxb file using Extract Tracking Data From nVision Movie.

Valid Inputs¶

Methodology¶

The tool calculates the following metrics:

Zone Occupancy detection¶

If no zone column name is provided, the tool will compute the zone occupancy using the Tracking point X and Y data.

At each frame, the tool will check the tracking XY coordinate against each zone.

• Polygons (including rectangle): The tool will check if the XY coordinate is within the polygon using the MatPlotLib's contains_point function
• Ellipse: The tool will check if the XY coordinate is within the ellipse bounds using the Ellipse equation

Total Time in Zone¶

Total time for each zone is calculated by summing the number of frames spent in that zone.

Zone Area¶

Zone area is calculated for each zone the following way:

• Polygons (including rectangle): are calculated using the shoelace formula
• Ellipse: \(\pi \times \text{major axis} \times \text{minor axis}\)

Occupancy Score¶

Occupation score, also known as the enrichment score,¹ is a metric that reflects zone preference independent of zone area. It is defined as the actual zone occupation / expected zone occupation. Where the expected zone occcupation is derived from the proportional area of the zone, the duration of the recording, and the assumption that all zones are visited with uniform probability. The occupation score for any given zone is calculated as follows:

Occupation scores greater than 1 represent zone preference higher than if the subject spent uniform time in every zone relative to its area.

Number of Zone Entries and exits¶

The number of times the subject entered or exited each zone.

Length of Zone Occupancy Events¶

The length of continuous periods for each zone.

Instantaneous Speed Calculation¶

Instantaneous speed is calculated from keypoint estimates by computing the Euclidean distance between consecutive tracking coordinates and dividing by the time difference between consecutive frames. If the Pixels Per Cm parameter is specified, then the speed is converted from px/s to cm/s.

Outputs¶

Trajectory With Zones Preview¶

Preview showing the trajectory of the subject overlaid with the zones. The zones are shown in different colors.

Zone Summary¶

The summary table is a .csv file which contains the results of the zone occupancy analysis. An example of a zone summary table is shown below:

Zone Summary Previews¶

Zone Occupancy Overview:

Summary of subject zone occupancy. Top panel shows zone occupation as a function of time. Bottom panel shows occupancy score as a function of time.

Total Occupancy Score:

The cumulative occupancy score across the entire session.

Total Time Spent in Each Zone:

The cumulative time (in seconds) the subject spent in each zone

Instantaneous Speeds:

Box plots with strip plot overlaid showing the distributions of instantaneous speeds for each zone. Each dot represents an instantaneous speed computed from a single time point.

Number of Zone Entries:

Summary showing the number of times the subject entered each zone.

Zone Events¶

The Events table is a .h5 in the event time stamps format and returns the timestamps of zone entries and exits.

An example of the table is shown below:

Zone Events Previews¶

Event Periods:

Raster plot of event entrance and exit timings for each zone. Each row represents a unique zone event, and each dot represents an event.

Length of Zone Occupancy Events:

Box plots with strip plot overlaid showing the distribution of durations the subject spent continuously in each zone. Each dot represents a single period.

Time Series Results¶

The speed table is a .csv in the experiment annotations format and returns the instantaneous speed for each frame. Some example rows from an output are shown in the table below:

Time Series Results Previews¶

Speed Time Series:

A plot of the instantaneous speed as a function of time. The colored sections of the line represent different zone occupancy.

Instantaneous Speeds:

Box plots with strip plot overlaid showing the distributions of instantaneous speeds for each zone. Each dot represents an instantaneous speed computed from a single time point.

Next Steps¶

After running this tool, the outputs of this tool can be used as inputs to other tools.

The zone_events.h5 output can be used to compare neural activity surrounding zone events using:

1. Peri-Event Analysis Workflow

The time_series_data.csv can be synchronized to a corresponding .isxd file using Map Annotations To ISXD Data, which can then be used as input to the following tools to observe differences in neural activity in different zones:

1. Compare Neural Activity Across States
2. Compare Neural Circuit Correlations Across States