Fragment#

Warning

The code reference is a work in progress and may contain inconsistencies.

class idtrackerai.Fragment(fragment_identifier: int, start_frame: int, end_frame: int, images: list[int] | ndarray, centroids: list[tuple[float, float]], episodes: list[int] | ndarray, is_an_individual: bool, exclusive_roi: int)[source]#

A collection of Blob s that belong to the same animal or to the same crossing.

The Fragment class represents a sequence of images (or blobs) that are believed to belong to the same animal or to a group of animals that are crossing paths. It contains various attributes and methods to manage and analyze these sequences, including their positions, velocities, identities, and other properties.

P1_vector: ndarray#: Numpy array indicating the P1 probability of each of the possible identities

coexisting_individual_fragments: Sequence[Fragment]#: list of fragment objects representing and individual (i.e. not representing a crossing where two or more animals are touching) and coexisting (in frame) with self. Doesn’t include self.

loaded_images: ndarray#: Fragment’s actual images, in uint8. Intended to be used outside idtrackerai

groundtruth_identity: int#: Groundtruth identity assigned externally after validating

acceptable_for_training: bool | None = None#: Boolean to indicate that the fragment was identified sufficiently well and can in principle be used for training. See also the accumulation_manager.py module.

temporary_id: int | None = None#: Integer indicating a temporary identity assigned to the fragment during the cascade of training and identification protocols. From 0 to n_animals-1

accumulable: bool | None = None#: Boolean indicating whether the fragment can be accumulated, i.e. it can potentially be used for training.

is_in_a_global_fragment: bool = False#: Indicates whether the fragment is part of a global fragment

certainty: float = 0.0#: Indicates the certainty of the identity

P2_vector: ndarray | None = None#: Numpy array indicating the P2 probability of each of the possible identities. See also compute_P2_vector()

identity: int | None = None#: Identity assigned to the fragment during the cascade of training and identification protocols or during the residual identification. From 1 to n_animals

non_consistent: bool = False#: Boolean indicating whether the fragment identity is consistent with coexisting fragment

ambiguous_identities: ndarray | None = None#: Identities that would be ambiguously assigned during the residual identification process. See also the assigner.py module

used_for_training: bool = False#: Boolean indicating whether the images in the fragment were used to train the identification network during the cascade of training and identification protocols. See also the accumulation_manager.py module.

accumulation_step: int | None = None#: Integer indicating the accumulation step at which the fragment was accumulated. See also the accumulation_manager.py module.

identities_corrected_closing_gaps: list[int] | None = None#: Identity of the fragment assigned during the interpolation of the gaps produced by the crossing fragments. See also the assign_them_all.py module.

identity_corrected_solving_jumps: int | None = None#: Identity of the fragment assigned during the correction of imposible (unrealistic) velocity jumps in the trajectories. See also the correct_impossible_velocity_jumps.py module.

identity_is_fixed: bool = False#: Boolean indicating whether the identity is fixed and cannot be modified during the postprocessing. This attribute is given during the residual identification (see assigner.py module)

accumulated_globally: bool = False#: Boolean indicating whether the fragment was accumulated in a global accumulation step of the cascade of training and identification protocols. See also the accumulation_manager.py module.

accumulated_partially: bool = False#: Boolean indicating whether the fragment was accumulated in a partial accumulation step of the cascade of training and identification protocols. See also the accumulation_manager.py module.

forced_crossing: bool = False#: Indicates if the crossing attribute has been forced by set_individual_with_identity_0_as_crossings()

__init__(fragment_identifier: int, start_frame: int, end_frame: int, images: list[int] | ndarray, centroids: list[tuple[float, float]], episodes: list[int] | ndarray, is_an_individual: bool, exclusive_roi: int) → None[source]#

images: ndarray#: Indices of Fragment’s images in the hdf5 files

episodes: ndarray#: Episode where each Fragment images belongs to. It determined the hdf5 file where the image is.

exclusive_roi: int = -1#: Exclusive ROI where the fragment belongs to. -1 for disabled exclusive ROIs

frame_by_frame_velocity: ndarray#: Instant speed (in each frame) of the blob in the fragment

start_position: tuple[float, float]#: X and Y position of the blob’s centroid at the start of the fragment

end_position: tuple[float, float]#: X and Y position of the blob’s centroid at the end of the fragment

__str__() → str[source]#: Return str(self).

property distance_travelled: float#: The distance traveled by the individual in the fragment. It is based on the position of the centroids in consecutive images.

reset(roll_back_to: Literal['fragmentation', 'accumulation'], number_of_animals: int) → None[source]#

Reset attributes of the fragment to a specific part of the algorithm.

Parameters:: roll_back_to (str) – Reset all the attributes up to the process specified in input. ‘fragmentation’, ‘accumulation’, ‘assignment’

property assigned_identities: list[int] | list[int | None]#

Assigned identities (list) by the algorithm considering the identification process and the postprocessing steps (correction of impossible velocity jumps and interpolation of crossings).

The fragment can have multiple identities if it is a crossing fragment.

property n_images: int[source]#: Number images (or blobs) in the fragment.

property is_certain: bool#: Whether the fragment is certain enough to be accumulated.

property has_enough_accumulated_coexisting_fragments: bool#

Whether the fragment has enough coexisting and already accumulated fragments (the threshold is half of them).

This property is used during the partial accumulation. See also the accumulation_manager.py module.

__getstate__() → dict[str, Any][source]#: Helper for pickle.

compute_border_velocity(other: Fragment | None) → float | None[source]#

Velocity necessary to cover the space between two fragments.

Note that these velocities are divided by the number of frames that separate self and other fragment.

Parameters:: other (Fragment) – Another fragment
Returns:: Returns the speed at which an individual should travel to be present in both self and other fragments.
Return type:: float

coexist_with(other: Fragment) → bool[source]#

Boolean indicating whether the given fragment coexists in time with another fragment.

Parameters:: other (Fragment) – A second fragment
Returns:: True if self and other coexist in time in at least one frame.
Return type:: bool

is_inconsistent_with_coexistent_fragments(temporary_id) → bool[source]#

Check that the temporary identity assigned to the fragment is consistent with respect to the identities already assigned to the fragments coexisting (in frame) with it.

Parameters:: temporary_id (int) – Temporary identity assigned to the fragment.
Returns:: True if the identification of self with temporary_id does not cause any duplication of identities.
Return type:: bool

set_identification_statistics(predictions_per_img: ndarray, probabilities_per_img: ndarray, n_animals: int) → None[source]#

Computes the statistics necessary for the identification of the fragment.

Parameters:

predictions_per_img (numpy array) – Array of shape (number_of_images_in_fragment,)
probabilities_per_img (numpy array) – Array of shape (number_of_images_in_fragment,)
n_animals (int) – Number of animals.

assign_identity(number_of_animals: int, id_to_roi: list[int] | ndarray) → None[source]#

Assigns the identity to the fragment by considering the fragments coexisting with it.

If the certainty of the identification is high enough it sets the identity of the fragment as fixed and it won’t be modified during the postprocessing.

compute_P2_vector(number_of_animals: int) → None[source]#

Computes the P2_vector of the fragment.

The flag only_non_identified is to save computational resources when Assigning identities after accumulation

property certainty_P2: float[source]#: Indicating the certainty of the identity following the P2

set_P1_from_frequencies(frequencies: ndarray) → None[source]#

Given the frequencies of a individual fragment computer the P1 vector.

P1 is the softmax of the frequencies with base 2 for each identity. Numpy array indicating the number of images assigned with each of the possible identities

get_neighbour_fragment(fragments: Sequence[Fragment], scope: Literal['to_the_past', 'to_the_future']) → Fragment | None[source]#

If it exist, gets the fragment in the list of all fragment whose identity is the identity assigned to self and whose starting frame is the ending frame of self + 1, or ending frame is the starting frame of self - 1

Parameters:

fragments (Sequence[Fragment]) – List of all the fragments in the video
scope (Literal["to_the_past", "to_the_future"]) – If “to_the_future” looks for the consecutive fragment wrt self, if “to_the_past” looks for the fragment the precedes self

Returns:

The neighbor fragment with respect to self in the direction specified by scope if it exists. Otherwise None

Return type:

Fragment | None

set_partially_or_globally_accumulated(accumulation_strategy) → None[source]#

Sets accumulated_globally and accumulated_partially according to accumulation_strategy.

Parameters:: accumulation_strategy (Literal["global", "partial"]) – Can be “global” or “partial”

property used_for_pretraining#: Used for pretraining

Deprecated since version 6.0.0.

compute_identification_statistics(*args)[source]#: Compute identification statistics

Deprecated since version 6.0.0: Use set_identification_statistics() instead

static compute_median_softmax()[source]#: Compute median softmax

Deprecated since version 6.0.0: This method is included in set_identification_statistics()

set_certainty_of_individual_fragment()[source]#: Set certainty of individual fragment

Deprecated since version 6.0.0: This method is included in set_identification_statistics()

property properties#: Properties

Deprecated since version 6.0.0: Use summary() instead