Queries And Matchers

fort_myrmidon.Query

class fort_myrmidon.Query

static CollideFrames(experiment: fort_myrmidon._fort_myrmidon.Experiment, *, start: fort_myrmidon._fort_myrmidon.Time = -∞, end: fort_myrmidon._fort_myrmidon.Time = +∞, zoneDepth: int = 1, zoneOrder: fort_myrmidon._fort_myrmidon.ZonePriority = <ZonePriority.PREDECENCE_LOWER: 0>, collisionsIgnoreZones: bool = False, singleThreaded: bool = False, reportProgress: bool = True, onEachFrame: Optional[Callable[[tuple[fort_myrmidon._fort_myrmidon.IdentifiedFrame, fort_myrmidon._fort_myrmidon.CollisionFrame]], None]] = None) → list | None

Gets Ant collision in tracked frames. There is two modes of operation: using a onEachFrame callback, that will allow you to perform computation on each tracked frame, or using the return value. The latter may require a lot of memory, so it will be safer to only query a small time subset.

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.
zoneDepth (int) – number of zones that will be computed for each ant.
zoneOrder (fort_myrmidon.ZonePriority) – priority of zone in case of conflict.
collisionsIgnoreZones (bool) – collision detection ignore zones definition
onNewFrame (Callable[Tuple[fort_myrmidon.IdentifiedFrame,fort_myrmidon.CollisionFrame],None]) – a callback function to get the result for each frames. If specified, this function will return None. It could be used to reduce the memory pressure of parsing large datasets.

Returns:

If onNewFrame is None, the detected position and collision of the Ants in tracked frames in [ start ; end [.

Return type:

List[Tuple[IdentifiedFrame,CollisionFrame]] | None

static ComputeAntInteractions(experiment: fort_myrmidon._fort_myrmidon.Experiment, *, start: fort_myrmidon._fort_myrmidon.Time = -∞, end: fort_myrmidon._fort_myrmidon.Time = +∞, maximumGap: fort_myrmidon._fort_myrmidon.Duration = 1s, matcher: fort_myrmidon._fort_myrmidon.Matcher = None, zoneDepth: int = 1, zoneOrder: fort_myrmidon._fort_myrmidon.ZonePriority = <ZonePriority.PREDECENCE_LOWER: 0>, collisionsIgnoreZones: bool = False, reportFullTrajectories: bool = True, segmentOnMatcherValueChange: bool = False, reportSmall: bool = False, singleThreaded: bool = False, reportProgress: bool = True, onNewTrajectory: Optional[Callable[[fort_myrmidon._fort_myrmidon.AntTrajectory], None]] = None, onNewInteraction: Optional[Callable[[fort_myrmidon._fort_myrmidon.AntInteraction], None]] = None) → tuple[list, list] | None

Computes Ant Interactions between two times. There is two modes of operation: using a onNewTrajectory and/or onNewInteraction callbacks, that will allow you to perform computation on each type of result as they are queried, or using the return value. The latter may require a lot of memory, so it will be safer to only query a small time subset.

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.
zoneDepth (int) – number of zones that will be computed for each ant.
zoneOrder (fort_myrmidon.ZonePriority) – priority of zone in case of conflict.
collisionsIgnoreZones (bool) – collision detection ignore zones definition
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.
reportSmall (bool) – Reports trajectories and interactions with a single time point.
onNewTrajectory (Callable[fort_myrmidon.AntTrajectory,None]) – If specified, this query will return None, and any discovered trajectory will be passed to this callback as they are computed.
onNewInteraction (Callable[fort_myrmidon.AntInteraction,None]) – If specified, this query will return None, and any discovered interactions will be passed to this callback as they are computed.

Returns:

If neither onNewTrajectory, nor onNewInteraction is specified, it will return:

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]] | None

static ComputeAntTrajectories(experiment: fort_myrmidon._fort_myrmidon.Experiment, *, start: fort_myrmidon._fort_myrmidon.Time = -∞, end: fort_myrmidon._fort_myrmidon.Time = +∞, maximumGap: fort_myrmidon._fort_myrmidon.Duration = 1s, matcher: fort_myrmidon._fort_myrmidon.Matcher = None, zoneDepth: int = 1, zoneOrder: fort_myrmidon._fort_myrmidon.ZonePriority = <ZonePriority.PREDECENCE_LOWER: 0>, segmentOnMatcherValueChange: bool = False, reportSmall: bool = False, singleThreaded: bool = False, reportProgress: bool = True, onNewTrajectory: Optional[Callable[[fort_myrmidon._fort_myrmidon.AntTrajectory], None]] = None) → list | None

Conputes Ant Trajectories between two times. There is two modes of operation: using a onNewTrajectory callback, that will allow you to perform computation on each computed trajectories, or using the return value. The latter may require a lot of memory, so it will be safer to only query a small time subset.

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.
zoneDepth (int) – number of zones that will be computed for each ant.
zoneOrder (fort_myrmidon.ZonePriority) – priority of zone in case of conflict.
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.
reportSmall (bool) – Reports trajectories with a single time point.
onNewTrajectory (Callable[fort_myrmidon.AntTrajectory,None]) – If specified, no data will be returned, but this callabled will be called for each results. It allows to reduce memory pressure when only a few metrics are needed from the results.

Returns:

a list of all AntTrajectory taking place in [ start ; end [ given the matcher and maximumGap criterions. If onNewTrajectory is specified, it will return None.

Return type:

List[AntTrajectory]|None

static ComputeMeasurementFor(experiment: fort_myrmidon._fort_myrmidon.Experiment, *, antID: int, measurementTypeID: int) → list[fort_myrmidon._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: fort_myrmidon._fort_myrmidon.Experiment, fixCorruptedData: bool = False) → dict[int, fort_myrmidon._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: fort_myrmidon._fort_myrmidon.Experiment, *, space: int = 1, start: fort_myrmidon._fort_myrmidon.Time = -∞, end: fort_myrmidon._fort_myrmidon.Time = +∞) → fort_myrmidon._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: fort_myrmidon._fort_myrmidon.Experiment) → fort_myrmidon._fort_myrmidon.ExperimentDataInfo

static GetMetaDataKeyRanges(experiment: fort_myrmidon._fort_myrmidon.Experiment, *, key: str, value: bool | int | float | str | fort_myrmidon._fort_myrmidon.Time) → list[tuple[int, fort_myrmidon._fort_myrmidon.Time, fort_myrmidon._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: fort_myrmidon._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: fort_myrmidon._fort_myrmidon.Experiment, *, start: fort_myrmidon._fort_myrmidon.Time = -∞, end: fort_myrmidon._fort_myrmidon.Time = +∞, singleThreaded: bool = False, zoneDepth: int = 1, zoneOrder: fort_myrmidon._fort_myrmidon.ZonePriority = <ZonePriority.PREDECENCE_LOWER: 0>, reportProgress: bool = True, onEachFrame: Optional[Callable[[fort_myrmidon._fort_myrmidon.IdentifiedFrame], None]] = None) → list | None

Gets Ant positions in tracked frames.There is two modes of operation: using a onEachFrame callback, that will allow you to perform computation on each tracked frame, or using the return value. The latter may require a lot of memory, so it will be safer to only query a small time subset.

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.
zoneDepth (int) – number of zones that will be computed for each ant.
zoneOrder (fort_myrmidon.ZonePriority) – priority of zone in case of conflict.
onEachFrame (Callable[fort_myrmidon.IdentifiedFrame,None]) – a callback function for each Identified frames. If specified, IdentifyFrames() will return None. If you only care about a few informations, this callback can be used to remove memory pressure.

Returns:

the detected position of the Ant in video frames in [ start ; end [ when onEachFrame is None.

Return type:

List[IdentifiedFrame] | None

fort_myrmidon.Matcher

class 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 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) → fort_myrmidon._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) → fort_myrmidon._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) → fort_myrmidon._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: fort_myrmidon._fort_myrmidon.Duration = 0s) → fort_myrmidon._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) → fort_myrmidon._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) → fort_myrmidon._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) → fort_myrmidon._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

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 (bool|int|float|str|fort_myrmidon.Time|None) – the value for key. If none is passed, it will only works on interaction, and make sure the two individuals value for key are the same values.

Returns:

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

Return type:

Matcher

static InteractionType(type1: int, type2: int) → fort_myrmidon._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) → fort_myrmidon._fort_myrmidon.Matcher

Combines several Matcher together in disjunction

Parameters:: *args (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 fort_myrmidon.AntTrajectory

An Ant trajectory represents a continuous spatial trajectory of an Ant

property Ant

the AntID of the Ant

Type:: int

property Duration_s

the duration (including last frame duration) of this trajectory.

Type:: float

End(self: fort_myrmidon._fort_myrmidon.AntTrajectory) → fort_myrmidon._fort_myrmidon.Time

Computes the End time of the AntTrajectory.

Returns:: the last Time found in this trajectory. It does not contains Duration.
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

fort_myrmidon.AntInteraction

class fort_myrmidon.AntInteraction

Represent an interaction between two Ant

property End

the end Time of the interaction.

Type:: Time

HasInteractionType(self: fort_myrmidon._fort_myrmidon.AntInteraction, arg0: int, arg1: int) → bool

Tests if interaction contains a given interaction type.

Parameters:

type1 (int) – The first type to test again.
type2 (int) – The second type to test again.

Returns:

True if the interaction type (type1,type2) is present. Note that order matter.

Return type:

bool

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

fort_myrmidon.AntTrajectorySegment

class 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: fort_myrmidon._fort_myrmidon.AntTrajectorySegment) → fort_myrmidon._fort_myrmidon.Time

Computes the ending Time of the AntTrajectorySegment

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

StartTime(self: fort_myrmidon._fort_myrmidon.AntTrajectorySegment) → fort_myrmidon._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

fort_myrmidon.AntTrajectorySummary

class 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]

fort_myrmidon.IdentifiedFrame

class fort_myrmidon.IdentifiedFrame

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

At(self: fort_myrmidon._fort_myrmidon.IdentifiedFrame, index: int) → tuple[int, numpy.ndarray[numpy.float64[3, 1]], numpy.ndarray[numpy.float64[m, 1]]]

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: fort_myrmidon._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

fort_myrmidon.CollisionFrame

class 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 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

fort_myrmidon.ComputedMeasurement

class 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

fort_myrmidon.TagStatistics

class 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

fort_myrmidon.ExperimentDataInfo

class 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 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 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