Data structure

[roaldarbol]

Hi @VioletteChiara!

I'm writing an R package for analysis of animal movement from an array of different sources (pose estimation, centroid tracking, trackball/treadmill) and would love to support AnimalTA. I write reader functions for each data source, along with some validator functions that ensures that the files really are in the format that the user thinks they are. I received some single-animal data from a friend that uses AnimalTA (I haven't had time to try AnimalTA myself), and I'm wondering whether that is also valid for multi-animal data? Or are the data headers different when there are multiple individuals? So whether it is something like Frame, Time, ID, x, y or rather Frame, Time, x_1, y_1, x_2, y_2 when there are two individuals?

Additionally, can I expect other column values inside an AnimalTA data frame?

The package is currently called trackballr, but will change name to animovement one of the following days. I collaborate with the team making the movement Python package, so once I've gotten the reader and validators implemented it would also be a smaller task for them to support it. :-)

All the best, Mikkel 😊

[roaldarbol]

Oh, and I can see that the x/y columns in the dataset I received are called X_Arena0_Ind0/Y_Arena0_Ind0. Should I take that to mean that there can be multiple arenas and individuals, and that they would be added as extra columns? Maybe if you have some sample data of a small range of use-cases you can share that with me? :-)

[VioletteChiara]

Hi! This seems to be a "raw coordinates" file with a single animal in a single arena. The notion of ROI is a bit confusing in AnimalTA because there are two kinds of ROIs. The first one is the "arena" kind, which defines where the targets can be (for instance if I record an ant inside a Petri dish, it will be the whole Petri dish). A file with "Frame;Time;X_Arena0_Ind0;Y_Arena0_Ind0" columns can be either a one-arena or a no-arena video. Indeed, by default, if no arena is indicated by the user the program will consider there is one big arena which includes the whole frame.

If there is one arena with one individual in each: Frame;Time;X_Arena0_Ind0;Y_Arena0_Ind0
If there is one arena with two individuals inside: Frame;Time;X_Arena0_Ind0;Y_Arena0_Ind0;X_Arena0_Ind1;Y_Arena0_Ind1

If there are two arenas with one individual in each: Frame;Time;X_Arena0_Ind0;Y_Arena0_Ind0;X_Arena1_Ind0;Y_Arena1_Ind0
If there are two arenas with two individuals in each: Frame;Time;X_Arena0_Ind0;Y_Arena0_Ind0;X_Arena0_Ind1;Y_Arena0_Ind1;X_Arena1_Ind0;Y_Arena1_Ind0;X_Arena1_Ind1;Y_Arena1_Ind1

After, there is what is called inside the program the "elements of interest" which are areas the user is especially interested in for the analyses. If I take again my ant example: the 1cm border inside the Petri dish could be an element of interest, or if there is a patch of food, the region around it, etc. The thing is that the elements of interest are drawn after tracking and so are not present in the raw coordinates files.

The relationship between the elements of interest and the coordinates are available in the "Detailed data" files that I described in a previous answer: "
3. The detailed coordinates:
This last data frame is the one including the coordinates of the target and a lot of the information the user added after the tracking/during corrections. It is very different from the others as there is one file per individual. In this file, the coordinates are not expressed in pixels anymore but in the international unit chosen by the user (if a scale is defined, if not we keep expressing them in pixels).
The basic columns are: Frame, X, Y, Speed, Moving, Distance.
If the user choose to smooth the data for the analysis, these coordinates are the result after smoothing and the column names become: Frame, X_smoothed, Y_smoothed, Speed, Moving, Distance.
If the user used the correction of perspective tool the coordinates are also transformed.
Speed is simply the movement speed, moving is whether the target is moving or not according to a movement threshold defined by the user. Distance is the distance traveled between the two frames.
But the number of column can later increase according to the situation: if there is more than one individual in the arena, the program will add one column per other individual and indicates in this column the inter-individual distance (column name: Dist_to_Ind43, but the individual ID may change if the user gave it a name). The user can also add elements of interest such as points, segments, borders, or arenas. There will be one column per element of interest (associated with the target arena) indicating the distance between the target and the element (name of the column: Dist_to_Point_0, but the "Point_0" part will change if the user gives it a name or according to the kind of element it is).
"

[roaldarbol]

Ah okay, I see thanks! I think I will focus on supporting just the first type for now - I am planning to add similar features (e.g. "elements of interest"), so it can be used on all data from all sources. However, I already implemented it for the "Detailed" file with just the basic columns - but I imagine issues would arise if it has more complicated columns (such as dist_to_point_0) where I don't know where the point is.

Anyway, I've finished implementing the reader and it's now available in v0.4.0 🥳 (and just for the record, the package is still in beta)😅

[roaldarbol]

The reference for the function is here: https://roald-arboel.com/animovement/reference/read_animalta.html
I'll change the parameter with_roi to detailed in a patch later today. 😊

[VioletteChiara]

Great! I will give it a try in the upcoming days :)
Thanks a lot for all your work!

[roaldarbol]

Sounds good! I made a patch now. Please let me know if something doesn't work well! There's a chance installation might be a bit tricky, and it would be great to know whether it is for you. :)