Linking Tracking Data

Note

All examples assumes the py_fort_myrmidon module to be included as:

import py_fort_myrmidon as fm

When working with fort-myrmidon the first steps is to link a .myrmidon file with some tracking data, generally created with fort-leto from the FORT system. These consist of folder with the tracking data, alongside video stream and close-up files of the detected tags.

In fort-myrmidon these Tracking Data Directories (TDD) must be assigned to a Space [2]. A Space is a 2D Cartesian space on its own, meaning that two coordinates from different Space should never be compared. This is useful with experiment with a different camera for the nest and foraging area, where positions should not be mixed together.

Manipulating Experiment files

In order to do so, one should first create [4] a new Experiment [1] associated with a file path. Then this file can then be saved [5]. While saving, the target file can be renamed, but must remain in the same directory to keep the relative links working.

# python
e = fm.Experiment('<exp_path>.myrmidon') # no file saved yet
e.Save('<exp_path>.myrmidon') # file now exists

# R
e <- fmExperimentCreate('<exp_path>.myrmidon') # no file created yet
e$save('<exp_path>.myrmidon') # file now exists

// C++
#include <fort/myrmidon/Experiment.hpp>

// will not create file yet
auto e = fort::myrmidon::Experiment::Create("<exp_path>.myrmidon");
e->Save("<exp_path>.myrmidon"); // file now exists

Warning

If you modify an experiment object, modifications are not reflected automatically on the file system, you must save them explicitly.

Defining Spaces

The next step is to create a Space [6] in that experiment. This Space has an ID and a name that will be used to report coordinates. There are no restriction on the Space name.

# python
s = e.CreateSpace(name = "nest")
print("Space '%s' has ID: %d" %(s.Name,s.ID))
# outputs: Space 'nest' has ID: 1

# R
s <- e$createSpace('nest')
printf("Space '%s' has ID: %d\n",s$name,s$ID)
# outputs: Space 'nest' has ID: 1

// C++
#include <fort/myrmidon/Experiment.hpp>

auto s = e->CreateSpace("nest");
std::cerr << "Space '" << s->Name() << "' has ID: " << s->ID() << std::endl;
// outputs: Space 'nest' has ID: 1

Note

For efficient data report, many objects such Space or Ant [3] are uniquely identified with a unique Identifier for that type. fort-myrmidon uses Identifier starting at 1 and growing, and search to group these identifiers together for a given type, to avoid missing identifier in a sequence. You cannot choose explicitly the value for these IDs, excepting by defining objects in the same order.

Linking Tracking Data Directories

Finally, we can add a Tracking Data Directory (TDD) [7] some data to the experiment. This will return to us an URI used to identify this particular TDD, especially to eventually remove [8] them or to report [9] tracking data statistics they contain.

#python
tddURI = e.AddTrackingDataDirectory(s.ID,"my_exp.0000")
# e.RemoveTrackingDataDirectory(tddURI)

#R
tddURI <- e$addTrackingDataDirectory(s$ID,"my_exp.0000")
# e$removeTrackingDataDirectory(tddURI)

//C++
#include <fort/myrmidon/Experiment.hpp>

auto tddURI = e->AddTrackingDataDirectory(s->ID(),"my_exp.0000")
// e->RemoveTrackingDataDirectory(tddURI)

TDD consistency

Internally, fort-myrmidon ensure the following invariant and will raise exception if :

  • A TDD is assigned to multiple spaces.

  • In a space, two TDDs contains data overlapping in space

  • If all the TDDs are not using the same tag family.