ethoscope.core package

Module contents

This module is the core of the ethoscope. It defines the building bricks at the basis of the package.

Overview:

  • Monitor is the most important class. It glues together all the other elements of the package in order to perform (video tracking, interacting , data writing and drawing).
  • TrackingUnit are internally used by monitor. They forces to conceptually treat each ROI independently.
  • ROI formalise and facilitates the use of Region Of Interests.
  • variables are custom types of variables that result from tracking and interacting.
  • DataPoint stores efficiently Variables.

ethoscope.core.monitor module

class ethoscope.core.monitor.Monitor(camera, tracker_class, rois=None, stimulators=None, *args, **kwargs)[source]

Bases: object

Class to orchestrate the tracking of multiple objects. It performs, in order, the following actions:

  • Requesting raw frames (delegated to BaseCamera)
  • Cutting frame portions according to the ROI layout (delegated to TrackingUnit).
  • Detecting animals and computing their positions and other variables (delegated to BaseTracker).
  • Using computed variables to interact physically (i.e. feed-back) with the animals (delegated to BaseStimulator).
  • Drawing results on a frame, optionally saving video (delegated to BaseDrawer).
  • Saving the result of tracking in a database (delegated to ResultWriter).
Parameters:
  • camera (BaseCamera) – a camera object responsible of acquiring frames and associated time stamps
  • tracker_class (class) – The algorithm that will be used for tracking. It must inherit from BaseTracker
  • rois (list(ROI)) – A list of region of interest.
  • stimulators (list(BaseInteractor) – The class that will be used to analyse the position of the object and interact with the system/hardware.
  • args – additional arguments passed to the tracking algorithm
  • kwargs – additional keyword arguments passed to the tracking algorithm
last_frame_idx
Returns:The number of the last acquired frame.
Return type:int
last_positions
Returns:The last positions (and other recorded variables) of all detected animals
Return type:dict
last_time_stamp
Returns:The time, in seconds, since monitoring started running. It will be 0 if the monitor is not running yet.
Return type:float
run(result_writer=None, drawer=None)[source]

Runs the monitor indefinitely.

Parameters:
  • result_writer (ResultWriter) – A result writer used to control how data are saved. None means no results will be saved.
  • drawer (BaseDrawer) – A drawer to plot the data on frames, display frames and/or save videos. None means none of the aforementioned actions will performed.
stop()[source]

Interrupts the run method. This is meant to be called by another thread to stop monitoring externally.

ethoscope.core.tracking_unit module

class ethoscope.core.tracking_unit.TrackingUnit(tracking_class, roi, stimulator=None, *args, **kwargs)[source]

Bases: object

Class instantiating a tracker(BaseTracker), and linking it with an individual ROI(ROI) and stimulator(BaseStimulator). Typically, several TrackingUnit objects are built internally by a Monitor(Monitor).

Parameters:
  • tracker_class (class) – The algorithm that will be used for tracking. It must inherit from BaseTracker
  • roi (ROI.) – A region of interest.
  • stimulator (BaseStimulator.) – an object used to physically interact with the detected animal.
  • args – additional arguments passed to the tracking algorithm.
  • kwargs – additional keyword arguments passed to the tracking algorithm.
get_last_positions(absolute=False)[source]

The last position of the animal monitored by this TrackingUnit

Parameters:absolute – Whether the position should be relative to the top left corner of the raw frame (true), or to the top left of the used ROI (false).
Returns:A container with the last variable recorded for this roi.
Return type:DataPoint
roi
Returns:A reference to the roi used by this TrackingUnit
Return type:ROI
stimulator
Returns:A reference to the stimulator used by this TrackingUnit
Return type:BaseStimulator
track(t, img)[source]

Uses the whole frame acquired, along with its time stamp to infer position of the animal. Also runs the stimulator object.

Parameters:
  • t (int) – the time stamp associated to the provided frame (in ms).
  • img (ndarray) – the entire frame to analyse
Returns:

The resulting data point
Return type:

DataPoint

ethoscope.core.roi module

class ethoscope.core.roi.ROI(polygon, idx, value=None, orientation=None, regions=None)[source]

Bases: object

Class to define a region of interest(ROI). Internally, ROIs are single polygons. At the moment, they cannot have any holes. The polygon defining the ROI is used to draw a mask to exclude off-target pixels (so cross-ROI info).

Parameters:
  • polygon (ndarray) – An array of points
  • idx (int) – the index of this ROI
  • value – an optional value to be save for this ROI (e.g. to define left and right side)
  • orientation – Optional orientation Not implemented yet
  • regions – Optional sub-regions within the ROI. Not implemented yet
apply(img)[source]

Cut an image where the ROI is defined.

Parameters:img (ndarray) – An image. Typically either one or three channels uint8.
Returns:a tuple containing the resulting cropped image and the associated mask (both have the same dimension).
Return type:(ndarray, ndarray)
bounding_rect()[source]
get_feature_dict()[source]
Returns:A dictionary of freatures for this roi. It containes the folowing fields:
  • “x”
  • “y”
  • “w”
  • “h”
  • “value”
  • “idx”
Return type:dict
idx
Returns:The index of this ROI
Return type:int
longest_axis
Returns:the value of the longest axis (w or h)
Return type:float
mask()[source]
Returns:The mask as a single chanel, uint8 image.
Return type:ndarray
offset
Returns:the x,y offset of the ROI compared to the frame it was build on.
Return type:(int,int)
polygon
Returns:the internal polygon defining the ROI.
Return type:ndarray
rectangle
Returns:The upright bounding rectangle to the ROI formatted (x,y,w,h). Where x and y are to coordinates of the top left corner
Return type:(int,int,int,int)
set_value(new_val)[source]
Parameters:new_val – assign a nex value to a ROI
value
Returns:the value of a ROI

ethoscope.core.variables module

class ethoscope.core.variables.BaseBoolVariable[source]

Bases: ethoscope.core.variables.BaseIntVariable

Abstract type encoding boolean values. Internally stored as int as bool type cannot be derived.

functional_type = 'bool'
sql_data_type = 'BOOLEAN'
class ethoscope.core.variables.BaseDistanceIntVar[source]

Bases: ethoscope.core.variables.BaseIntVariable

Abstract type encoding variables representing distances.

functional_type = 'distance'
class ethoscope.core.variables.BaseIntVariable[source]

Bases: int

Template class for defining arbitrary variable types. Each class derived from this one should at least define the three following attributes:

  • sql_data_type, The MySQL data type. This allows to use minimal space to save data points.
  • header_name, The name of this variable. this will be used as the column name in the result table, so it must be unique.
  • functional_type, A keyword defining what type of variable this is. For instance “distance”, “angle” or “proba”. this allow specific post-processing per functional type.
functional_type = None
header_name = None
sql_data_type = 'SMALLINT'
class ethoscope.core.variables.BaseRelativeVariable[source]

Bases: ethoscope.core.variables.BaseDistanceIntVar

Abstract type encoding distance variables that can be expressed relatively to an origin. They converted to absolute using information form the ROI.

to_absolute(roi)[source]

Converts a positional variable from a relative (to the top left of a ROI) to an absolute (e.i. top left of the parent image).

Parameters:roi (ROI.) – a region of interest
Returns:A new variable
Return type:BaseRelativeVariable
class ethoscope.core.variables.HeightVariable[source]

Bases: ethoscope.core.variables.BaseDistanceIntVar

Type storing the height of a detected object.

header_name = 'h'
class ethoscope.core.variables.IsInferredVariable[source]

Bases: ethoscope.core.variables.BaseBoolVariable

Type encoding whether a data point is inferred (from past values) or observed; 0 or 1, respectively.

header_name = 'is_inferred'
class ethoscope.core.variables.Label[source]

Bases: ethoscope.core.variables.BaseIntVariable

Type encoding a discrete label when several objects, in the same ROI, are detected.

functional_type = 'label'
header_name = 'label'
class ethoscope.core.variables.PhiVariable[source]

Bases: ethoscope.core.variables.BaseIntVariable

Type encoding the angle of a detected object, in degrees.

functional_type = 'angle'
header_name = 'phi'
class ethoscope.core.variables.WidthVariable[source]

Bases: ethoscope.core.variables.BaseDistanceIntVar

Type storing the width of a detected object.

header_name = 'w'
class ethoscope.core.variables.XPosVariable[source]

Bases: ethoscope.core.variables.BaseRelativeVariable

Type storing the X position of a detected object.

header_name = 'x'
class ethoscope.core.variables.XYDistance[source]

Bases: ethoscope.core.variables.BaseIntVariable

Type storing distance moved between two consecutive observations. Log10 x 1000 is used so that floating point distance is stored as an int.

functional_type = 'relative_distance_1e6'
header_name = 'xy_dist_log10x1000'
class ethoscope.core.variables.YPosVariable[source]

Bases: ethoscope.core.variables.BaseRelativeVariable

Type storing the Y position of a detected object.

header_name = 'y'
class ethoscope.core.variables.mLogLik[source]

Bases: ethoscope.core.variables.BaseIntVariable

Type representing a log likelihood. It should be multiplied by 1000 to be stored as an int.

functional_type = 'proba'
header_name = 'mlog_L_x1000'

ethoscope.core.data_point module

class ethoscope.core.data_point.DataPoint(data)[source]

Bases: collections.OrderedDict

A container to store variables. It derived from OrderedDict. Variables are accessible by header name, which is an individual identifier of a variable type (see BaseIntVariable):

>>> from ethoscope.core.variables import DataPoint, XPosVariable, YPosVariable, HeightVariable
>>> y = YPosVariable(18)
>>> x = XPosVariable(32)
>>> data = DataPoint([x,y])
>>> print data["x"]
>>> h = HeightVariable(3)
>>> data.append(h)
>>> print data
Parameters:data (list(BaseIntVariable)) – a list of data points
append(item)[source]

Add a new variable in the DataPoint The order is preserved.

Parameters:
Returns:
copy()[source]

Deep copy a data point. Copying using the = operator will simply create an alias to a DataPoint object (i.e. allow modification of the original object).

Returns:a copy of this object
Return type:DataPoint