Queries And Matchers

py_fort_myrmidon.Query

class py_fort_myrmidon.Query

static CollideFrames(experiment: py_fort_myrmidon.Experiment, *, start: py_fort_myrmidon.Time = {Time:-∞}, end: py_fort_myrmidon.Time = {Time:+∞}, collisionsIgnoreZones: bool = False, singleThreaded: bool = False, reportProgress: bool = True) → list

Gets Ant collision in video frames.

Parameters:

experiment (Experiment) – the experiment to query
start (Time) – the first video acquisition time to consider
end (Time) – the last video acquisition time to consider
singleThreaded (bool) – limits computation to happen in a single thread.
collisionsIgnoreZones (bool) – collision detection ignore zones definition

Returns:

the detected position and collision of the Ants in video frames in [start;**end**[

Return type:

List[Tuple[IdentifiedFrame,CollisionFrame]]

static ComputeAntInteractions(experiment: py_fort_myrmidon.Experiment, *, start: py_fort_myrmidon.Time = {Time:-∞}, end: py_fort_myrmidon.Time = {Time:+∞}, maximumGap: py_fort_myrmidon.Duration = <py_fort_myrmidon.Duration object at 0x7fe4a1963d70>, matcher: py_fort_myrmidon.Matcher = None, collisionsIgnoreZones: bool = False, reportFullTrajectories: bool = True, segmentOnMatcherValueChange: bool = False, singleThreaded: bool = False, reportProgress: bool = True) → tuple

Conputes Ant Interctions between two times.

Parameters:

experiment (Experiment) – the experiment to query
start (Time) – the first video acquisition time to consider
end (Time) – the last video acquisition time to consider
maximumGap (Duration) – maximum tracking gap allowed in AntInteraction or AntTrajectory objects.
matcher (Matcher) – a Matcher that reduces down the query to more specific use case.
reportFullTrajectories (bool) – if true, full AntTrajectories will be computed and returned. Otherwise, none will be returned and only the average Ants position will be returned in AntTrajectorySegment.
singleThreaded (bool) – limits computation to happen in a single thread.
segmentOnMatcherValueChange (bool) – if True, when a combined matcher ( “behavior” == “grooming” || “behavior” = “sleeping” ) value change, create a new trajectory.

Returns:

a list of all AntTrajectory taking place in [start;end[ given the matcher criterion and maximumGap if reportFullTrajectories is true. Otherwise it will be an empty list.
a list of all AntInteraction taking place in [start;end[ given the matcher criterion and maximumGap

Return type:

Tuple[List[AntTrajectory],List[AntInteraction]]

static ComputeAntTrajectories(experiment: py_fort_myrmidon.Experiment, *, start: py_fort_myrmidon.Time = {Time:-∞}, end: py_fort_myrmidon.Time = {Time:+∞}, maximumGap: py_fort_myrmidon.Duration = <py_fort_myrmidon.Duration object at 0x7fe4a18e6c70>, matcher: py_fort_myrmidon.Matcher = None, computeZones: bool = False, segmentOnMatcherValueChange: bool = False, singleThreaded: bool = False, reportProgress: bool = True) → list

Conputes Ant Trajectories between two times.

Parameters:

experiment (Experiment) – the experiment to query
start (Time) – the first video acquisition time to consider
end (Time) – the last video acquisition time to consider
maximumGap (Duration) – maximum tracking gap allowed in a AntTrajectory object.
matcher (Matcher) – a Matcher that reduces down the query to more specific use case.
computeZones (bool) – computes the zone of the Ant. Otherwise 0 will always be returned.
singleThreaded (bool) – limits computation to happen in a single thread.
segmentOnMatcherValueChange (bool) – if True, when a combined matcher ( “behavior” == “grooming” || “behavior” = “sleeping” ) value change, create a new trajectory.

Returns:

a list of all AntTrajectory taking place in [start;**end**[ given the matcher and maximumGap criterions.

Return type:

List[AntTrajectory]

static ComputeMeasurementFor(experiment: py_fort_myrmidon.Experiment, *, antID: int, measurementTypeID: int) → List[py_fort_myrmidon.ComputedMeasurement]

Computes Ant manual measurement in millimeters.

Computes the list of manual measurements made in fort-studio for a given Ant in millimeters.

Parameters:

experiment (Experiment) – the experiment to query
antID (int) – the Ant to consider
measurementTypeID (int) – the kind of measurement to consider

Returns:

the list of measurement for antID and measurementTypeID

Return type:

List[Measurement]

static ComputeTagStatistics(experiment: py_fort_myrmidon.Experiment, fixCorruptedData: bool = False) → Dict[int, py_fort_myrmidon.TagStatistics]

Computes tag detection statistics in an experiment.

Parameters:

experiment (Experiment) – the experiment to query.
fixCorruptedData (bool) – if True will silently fix any data corruption error found. This may lead to the loss of large chunck of tracking data. Otherwise, a RuntimeError will be raised.

Returns:

the list of TagStatistics indexed by TagID.

Return type:

Dict[int,TagStatistics]

Raises:

RuntimeError – in vase of data corruption if fixCorruptedData == False

static FindVideoSegments(experiment: py_fort_myrmidon.Experiment, *, space: int = 1, start: py_fort_myrmidon.Time = {Time:-∞}, end: py_fort_myrmidon.Time = {Time:+∞}) → py_fort_myrmidon.VideoSegmentList

Finds VideoSegment in a time range

Parameters:

experiment (Experiment) – the Experiment to query
space (int) – the SpaceID to ask videos for
start (Time) – the first time to query a video frame
end (Time) – the last time to query a video frame

Returns:

list of VideoSegment in space that covers [start;**end**].

Return type:

VideoSegmentList

static GetDataInformations(experiment: py_fort_myrmidon.Experiment) → py_fort_myrmidon.ExperimentDataInfo

static GetMetaDataKeyRanges(experiment: py_fort_myrmidon.Experiment, *, key: str, value: bool | int | float | str | py_fort_myrmidon.Time) → List[Tuple[int, py_fort_myrmidon.Time, py_fort_myrmidon.Time]]

Gets the time ranges where metadata key has a given value

Parameters:

experiment (Experiment) – the Experiment to query
key (str) – the metadata key to test
value (str) – the value to test for equality

Returns:

time ranges for each AntID where key == value

Return type:

List[Tuple[int,Time,Time]]

Raises:

IndexError – if key is not defined in Experiment
ValueError – if value is not the right type for key

static GetTagCloseUps(experiment: py_fort_myrmidon.Experiment, fixCorruptedData: bool = False) → object

Gets the tag close-up in this experiment

Parameters:

experiment (Experiment) – the Experiment to quer
fixCorruptedData (bool) – if True, data corruption will be silently fixed. In this case a few close-up may be lost. Otherwise it will raise an error.

Raises:

RuntimeError – in case of data corruption and if fixCorruptedData == False.

Returns:

the close-up data in the experiment

Return type:

pandas.DataFrame

static IdentifyFrames(experiment: py_fort_myrmidon.Experiment, *, start: py_fort_myrmidon.Time = {Time:-∞}, end: py_fort_myrmidon.Time = {Time:+∞}, singleThreaded: bool = False, computeZones: bool = False, reportProgress: bool = True) → list

Gets Ant positions in video frames.

Parameters:

experiment (Experiment) – the experiment to query
start (Time) – the first video acquisition time to consider
end (Time) – the last video acquisition time to consider
singleThreaded (bool) – limits computation to happen in a single thread.
computeZones (bool) – computes the zone for the Ant, otherwise 0 will always be returned for the ants’ current ZoneID.

Returns:

the detected position of the Ant in video frames in [start;**end**[

Return type:

List[IdentifiedFrame]

py_fort_myrmidon.Matcher

class py_fort_myrmidon.Matcher

A Matcher helps to build complex Query by adding one or several constraints.

Matchers works either on single Ant for trajectory computation, or on a pair of Ant when considering interactions. Some matcher have no real meaning outside of interaction (i.e. InteractionType()) and would match any trajectory.

One would use the following function to get a Matcher :

AntID() : one of the considered Ant in the trajectory or interaction should match a given AntID

AntMetaData() : one of the key-value meta-data for one of the considered Ant should match.

AntDistanceSmallerThan(), AntDistanceGreaterThan() : for interaction queries only, ensure some criterion for the distance between the two considered ants.

AntAngleSmallerThan(), AntAngleGreaterThan() : for interaction queries only, ensure that angle between Ant meets some criterion.

InteractionType() : considers only interaction of a given type.

AntDisplacement(): matches interaction were the displacement of either of the Ant is kept under a threshold.

Using And() or Or(), one can combine several Matcher together to build more complex criterion. .. rubric:: Examples

import py_fort_myrmidon as fm
# m will match ant 001 or 002
m = fm.Matcher.Or(fm.Matcher.AntID(1),fm.Matcher.AntID(2))

static And(*args) → py_fort_myrmidon.Matcher

Combines several Matcher together in conjuction

Parameters:: *args (Matcher) – several other Matcher
Returns:: a Matcher that matches when all passed matcher also matches.
Return type:: Matcher

static AntAngleGreaterThan(angle: float) → py_fort_myrmidon.Matcher

A Matcher that matches ant angles.

In the case of trajectories, it matches anything

Parameters:: angle (float) – the angle in radians
Returns:: a Matcher that matches when the two Ant are facing directions which are greater appart than angle.
Return type:: Matcher

static AntAngleSmallerThan(angle: float) → py_fort_myrmidon.Matcher

A Matcher that matches ant angles.

In the case of trajectories, it matches anything

Parameters:: angle (float) – the angle in radians
Returns:: a Matcher that matches when the two Ant are facing the same direction within angle
Return type:: Matcher

static AntDisplacement(under: float, minimumGap: py_fort_myrmidon.Duration = <py_fort_myrmidon.Duration object at 0x7fe4a18e65b0>) → py_fort_myrmidon.Matcher

A Matcher that rejects large ants displacement.

Discards any trajectories and interactions where an Ant shows a displacement from one detected position to another larger than under. If minimumGap is larger than 0s, this check is enforced only if there are more than minimumGap time ellapsed between two tracked positions.

Parameters:

under (float) – maximum allowed Ant displacement in pixels
minimumGap (Duration) – minimum tracking time between positions to enable the check.

Returns:

A Matcher that matches small Ant displacement.

Return type:

Matcher

static AntDistanceGreaterThan(distance: float) → py_fort_myrmidon.Matcher

A Matcher that matches ant distance.

In the case of trajectories, it matches anything

Parameters:: distance (float) – the distance in pixel to match
Returns:: a Matcher that matches when the two Ant are further than distance.
Return type:: Matcher

static AntDistanceSmallerThan(distance: float) → py_fort_myrmidon.Matcher

A Matcher that matches ant distance.

In the case of trajectories, it matches anything

Parameters:: distance (float) – the distance in pixel to match
Returns:: a Matcher that matches when the two Ant are within distance.
Return type:: Matcher

static AntID(antID: int) → py_fort_myrmidon.Matcher

Matches a given AntID.

In case of interaction, matches any interaction with one of the Ant having antID.

Parameters:: antID (int) – the AntID to match against.
Returns:: a matcher that matches antID.
Return type:: Matcher

static AntMetaData(key: str, value: bool | int | float | str | py_fort_myrmidon.Time) → py_fort_myrmidon.Matcher

Matches a given user meta data value.

In case of interaction, matches any interaction where at least one of the Ant meets the criterion.

Parameters:

key (str) – the key to match from
value (str) – the value for key. Should be a bool, int, float, str or Time

Returns:

a Matcher that matches Ant who current key meta data value matches value.

Return type:

Matcher

static InteractionType(type1: int, type2: int) → py_fort_myrmidon.Matcher

Matches InteractionType (type1,type2) and (type2,type1).

In the case of trajectories it matches anything.

Parameters:

type1 (int) – the first AntShapeTypeID to match
type2 (int) – the second AntShapeTypeID to match

Returns:

A Matcher that matches interactions (type1,type2) or (type2,type1).

Return type:

Matcher

static Or(*args) → py_fort_myrmidon.Matcher

Combines several Matcher together in disjunction

Parameters:: *args (py_fort_myrmidon.Matcher) – several other Matcher
Returns:: a Matcher that matches when any of the passed matcher matches.
Return type:: Matcher

Queries’ result structures

py_fort_myrmiond.AntTrajectory

class py_fort_myrmidon.AntTrajectory

An Ant trajectory represents a continuous spatial trajectory of an Ant

property Ant

the AntID of the Ant

Type:: int

End(self: py_fort_myrmidon.AntTrajectory) → py_fort_myrmidon.Time

Computes the End time of the AntTrajectory.

Returns:: the last Time found in this trajectory
Return type:: Time

property Positions

a N row array of position. Columns are (t,x,y,angle,zone), where t is the offset from Start in seconds.

Type:: numpy.ndarray

property Space

the SpaceID where the trajectory takes place.

Type:: int

property Start

the starting time of this trajectory.

Type:: Time

py_fort_myrmidon.AntInteraction

class py_fort_myrmidon.AntInteraction

Represent an interaction between two Ant

property End

the end Time of the interaction.

Type:: Time

property IDs

the AntIDs of the two Ant interaction

Type:: Tuple[int,int]

property Space

the SpaceID of the Space the interaction takes place.

Type:: int

property Start

the start Time of the interaction.

Type:: Time

property Trajectories

The two section of trajectory for the two Ant during this interaction. Either the segments or their summaries.

Type:: Union[Tuple[AntTrajectorySegment,AntTrajectorySegment],Tuple[AntTrajectorySummary,AntTrajectorySummary]]

property Types

The AntShapeTypeID that were in contact during the interaction. Any body part interacting at least once will add a row in this array. The first column refers to the first Ant, and the second column to the other Ant.

Type:: numpy.ndarray

py_fort_myrmidon.AntTrajectorySegment

class py_fort_myrmidon.AntTrajectorySegment

Represents a section of an AntTrajectory.

property Begin

the first index in Trajectory this segment refers to.

Type:: int

property End

the last index+1 in Trajectory this segment refers to.

Type:: int

EndTime(self: py_fort_myrmidon.AntTrajectorySegment) → py_fort_myrmidon.Time

Computes the ending Time of the AntTrajectorySegment

Returns:: the ending Time of the AntTrajectorySegment.
Return type:: Time

StartTime(self: py_fort_myrmidon.AntTrajectorySegment) → py_fort_myrmidon.Time

Computes the starting Time of the AntTrajectorySegment

Returns:: the starting Time of the AntTrajectorySegment.
Return type:: Time

property Trajectory

the AntTrajectory it refers to.

Type:: Trajectory

py_fort_myrmidon.AntTrajectorySummary

class py_fort_myrmidon.AntTrajectorySummary

Represents a summary of an AntTrajectory section.

property Mean

the AntTrajectory it refers to.

Type:: Trajectory

property Zones

all the ZoneID the trajectory crossed.

Type:: List[int]

py_fort_myrmidon.IdentifiedFrame

class py_fort_myrmidon.IdentifiedFrame

An IdentifiedFrame holds ant detection information associated with one video frame.

At(self: py_fort_myrmidon.IdentifiedFrame, index: int) → Tuple[int, numpy.ndarray[numpy.float64[3, 1]], int]

Returns ant information for a given row.

Parameters:: index (int) – the index in Positions
Returns:: the AntID, a vector with its (x,y,theta) position, and its current zone.
Return type:: Tuple[int,numpy.ndarray,int]
Raises:: IndexError – if index >= len(Positions)

Contains(self: py_fort_myrmidon.IdentifiedFrame, antID: int) → bool

Tests if the frame contains a given antID

Parameters:: antID (int) – the AntID to test for.
Returns:: True if antID is present in this frame
Return type:: bool

property FrameTime

acquisition time of the frame

Type:: Time

property Height

height in pixel of the original video frame

Type:: int

property Positions

a N row array of (antID,x,y,angle,zone) row vectors for each detected ant in the frame. if Zone is undefined or non-computed, zone will be 0.

Type:: numpy.ndarray

property Space

the SpaceID of the Space this frame comes from

Type:: int

property Width

width in pixel of the original video frame

Type:: int

py_fort_myrmidon.CollisionFrame

class py_fort_myrmidon.CollisionFrame

A CollisionFrame regroups all Collision that happen in a video frame

property Collisions

the list of Collision in the frame

Type:: List[Collision]

property FrameTime

the Time the video frame was acquired

Type:: Time

property Space

the Space the video frame belongs to

Type:: int

class py_fort_myrmidon.Collision

A Collision describe an instantaneous contact between two ants

property IDs

the AntIDs of the two ants. IDs are always ordered from smaller to higher.

Type:: Tuple[int,int]

property Types

an N row array describing the colliding AntShapeTypeID. First column refers to shape type of the first Ant, which are colliding with a part of the second Ant in the second column.

Type:: numpy.ndarray

property Zone

the ZoneID where the collision happens

Type:: int

py_fort_myrmidon.ComputedMeasurement

class py_fort_myrmidon.ComputedMeasurement

A manual fort-studio measurement and its estimated value in millimeters.

property LengthMM

its length in millimeters.

Type:: float

property LengthPixel

its length in pixel.

Type:: float

property Time

the Time of the close-up this measurement.

Type:: Time

py_fort_myrmidon.TagStatistics

class py_fort_myrmidon.TagStatistics

Tag detection statistics for a given TagID

property Counts

histogram of detection gaps (int, size[N,1])

Type:: numpy.ndarray

property FirstSeen

first time the tag was seen

Type:: Time

property ID

the TagID it refers to

Type:: int

property LastSeen

last time the tag was seen

Type:: Time

py_fort_myrmidon.ExperimentDataInfo

class py_fort_myrmidon.ExperimentDataInfo

Tracking Data information summary for an Experiment

property End

the Time of the first frame available in this Experiement.

Type:: Time

property Frames

Total number of Frames accessible in this Experiment.

Type:: int

property Spaces

the SpaceDataInfo indexed by SpaceId.

Type:: Dict[int,SpaceDataInfo]

property Start

the Time of the first frame available in this Experiement.

Type:: Time

class py_fort_myrmidon.SpaceDataInfo

Tracking Data information summary for a Space.

property End

the Time of the last frame available in this space.

Type:: Time

property Frames

Total number of frame found in this Space

Type:: int

property Name: The name of the space

property Start

the Time of the first frame available in this space.

Type:: Time

property TrackingDataDirectories

The TrackingDataDirectoryInfo present in this Space

Type:: List[TrackingDataDirectoryInfo]

property URI: The internal URI for the Space

class py_fort_myrmidon.TrackingDataDirectoryInfo

Tracking Data informations summary for a Tracking Data Directory.

property AbsoluteFilePath

Absolute filepath of the Tracking Data Directory on the system

Type:: str

property End

The Time plus a nanosecond, of the last frame found in This Tracking Data Directory

Type:: Time

property Frames

Number of frames found in this Tracking Data Directory

Type:: int

property Start

The Time of the first frame found in this Tracking Data Directory.

Type:: Time

property URI

The internal URI for the Tracking Data Directory

Type:: str