yupiwrap

This repository contains functions to simplify the conversion of Trajectory data among yupi and other useful software libraries designed for analyzing trajectories.

Standing for Yet Underused Path Instruments, yupi is a set of tools designed for collecting, generating and processing trajectory data. The structure of yupi aims to standardize the usage and storage of general purpose trajectories independently of its dimensions. We believe it is useful to be able to convert, when possible, yupi trajectories to the data structures used by other libraries to empower our users with the tools offered by third parties. With the same spirit, we offer the possibility of converting data from other libraries to yupi trajectories.

Installation

Current recommended installation method is via the pypi package:

pip install yupiwrap

It will install required dependencies such as yupi package from pypi.

Compatible libraries

traja

The Traja Python package is a toolkit for the numerical characterization and analysis of the trajectories of moving animals. It provides several machine learning tools that are not yet implemented in yupi. Even when it is limited to two-dimensional trajectories, there are many resources that traja can offer when dealing with 2D Trajectories in yupi.

Converting a yupi.Trajectory into a traja DataFrame

Let's create a trajectory with yupi:

from yupi import Trajectory

x = [0, 1.0, 0.63, -0.37, -1.24, -1.5, -1.08, -0.19, 0.82, 1.63, 1.99, 1.85]
y = [0, 0, 0.98, 1.24, 0.69, -0.3, -1.23, -1.72, -1.63, -1.01, -0.06, 0.94]

track = Trajectory(x=x, y=y, traj_id="Spiral")

We can convert it to a traja DataFrame simply by:

from yupiwrap import yupi2traja

traja_track = yupi2traja(track)

⚠️ Only yupi.Trajectory objects with two dimensions can be converted to traja DataFrame due to traja limitations.

Converting a traja DataFrame into a yupi.Trajectory

If you have a traja DataFrame you can always convert it to a yupi.Trajectory by using:

from yupiwrap import traja2yupi

yupi_track = traja2yupi(traja_track)

tracktable

Tracktable provides a set of tools for handling 2D and 3D trajectories as well as Terrain trajectories. The core data structures and algorithms on this package are implemented in C++ for speed and more efficient memory use.

Converting a yupi.Trajectory into a tracktable trajectory

Let's create a trajectory with yupi:

from yupiwrap.tracktable import yupi2tracktable, tracktable2yupi
from yupi import Trajectory

# Creating a yupi trajectory representing terrain coordinates
points = [[-82.359415, 23.135012],[-82.382116, 23.136252]]
track_1 = Trajectory(points=points, traj_id="ter_track")

# Creating a 2D yupi trajectory
points = [[0, 0], [1.0, 0], [0.63, 0.98], [-0.37, 1.24], [-1.24, 0.69],
          [-1.5, -0.3], [-1.08, -1.23], [-0.19, -1.72], [0.82, -1.63],
          [1.63, -1.01], [1.99, -0.06], [1.85, 0.94]]
track_2 = Trajectory(points=points, traj_id="2d_track")

# Creating a 3D yupi trajectory
points = [[0,0,0], [1,1,3], [3,2,5]]
track_3 = Trajectory(points=points, traj_id="3d_track")

We can convert these tracks to tracktable trajectories simply by:

tracktable_track_1 = yupi2tracktable(track_1, is_terrestrial=True)
tracktable_track_2 = yupi2tracktable(track_2)
tracktable_track_3 = yupi2tracktable(track_3)

⚠️ If a 3D yupi trajectory is converted to a tracktable trajectory with is_terrestrial=True then the z axis values are stored as a property called 'altitude' for each point.

⚠️ Only yupi.Trajectory objects with two or three dimensions can be converted to tracktable trajectories due to tracktable limitations.

Converting a tracktable trajectory into a yupi.Trajectory

If you have a tracktable trajectory you can always convert it to a yupi.Trajectory by using:

# Converting the trajectory from tracktable to yupi
yupi_track_1 = tracktable2yupi(tracktable_track_1)