tracktable.algorithms.boxiness module

Module contents

tracktable.algorithms.boxiness - Determine how close to a perfect square/box a trajectory is as well as determining how much a trajectory zigzags.

calculate_boxiness(), sort_boxiness(), calculate_zigzaginess() and sort_by_zigzaginess() are the main driver functions for determining boxiness or zigzaginess.

Warning

The calculate_zigzaginess() and sort_by_zigzaginess() functions may produce results that are not expected as this functions are not fully fleshed out.

The algorithm details for boxiness can be found in the Demo 2: Detecting “boxes” notebook.

tracktable.algorithms.boxiness.calculate_bearings_histogram(trajectory, scale_by_length=True, normalize=True, simplify_trajectory=False, error_tolerance=1e-05)[source]

Calculates a bearings histogram, which can use the usual binning method or bin by segment length, and can also be optionally normalized.

Parameters

trajectory (Tracktable trajectory) – The trajectory for which we will create a scaled relative bearings histogram.

Keyword Arguments

  • scale_by_length (bool) – If true, then instead of traditional bining (each bearing value counts as one), we add the length of the segment with the corresponding bearing to the bin. The histogram is normalized by dividing each bin by the length of the trajectory. (Default: True)

  • normalize (bool) – If true, will yield a relative histogram (bins sum to 1) instead of an absolute histogram. (Default: True)

  • simplify_trajectory (bool) – We can opt to smooth the trajectory using Tracktable’s simplify function. This can help if we have particularly noisy data, but should be used with caution, as oversmoothing can lower the boxiness scores of true boxes. (Default: False)

  • error_tolerance (float) – The simplify function will not exceed this positional error tolerance, measured in the trajectory’s native distance represeted in km. (Default: 0.00001)

Returns

Relative histogram of bearings, where dict keys define bins and dict values are percentages in each bin. Keys are degrees 0 through 359 (but will only exist for nonzero histogram values). Values are the sum of the length of every segment with this bearing (rounded to the nearest degree), divided by the length of the entire trajectory.

tracktable.algorithms.boxiness.calculate_boxiness(trajectories, window=5, simplify_trajectory=False, error_tolerance=1e-05, ignore_zero_degree_quartet=True)[source]

Calculates a boxiness score for each trajectory and appends it as a property, to be accessed as trajectory.property[‘boxiness’].

Note

In actuality, this score will be higher for trajectories that move primarily in four directions that are each nintey degrees apart, and this does not exclusively limit to boxes.

Parameters

trajectories (list of Tracktable trajectories) – We will score each of these trajectories for “boxiness” and store the score as a trajectory property.

Keyword Arguments

  • window (Odd int) – To account for imperfect boxes, we sum our quartet products over a window of this width (in degrees), centered at the peak quartet product. Note: Even integers will be rounded up to the nearest odd integer. (Default: 5)

  • simplify_trajectory (bool) – We can opt to smooth the trajectory using Tracktable’s simplify function. This can help if we have particularly noisy data, but should be used with caution, as oversmoothing can lower the boxiness scores of true boxes. (Default: False)

  • error_tolerance (float) – The simplify function will not exceed this positional error tolerance, measured in the trajectory’s native distance represented in km. (Default: 0.00001)

  • ignore_zero_degree_quartet (bool) – GPS rounding can cause trajectories that don’t move to create a box-like pattern (since GPS point round to a grid). To ignore these, we can opt to ignore all boxes on the north-south-east-west grid. WARNING: This may delete non-GPS rounding boxes! (Default: True)

tracktable.algorithms.boxiness.calculate_zigzaginess(trajectories, buffer=5)[source]

Calculates a zigzaginess score for each trajectory and appends it as a property, to be accessed as trajectory.property[‘zigzaginess’].

Parameters

trajectories (list of Tracktable trajectories) – We will score each of these trajectories for “boxiness” and store the score as a trajectory property.

Keyword Arguments

buffer (int) – To account for imperfect zigzags, we need to buffer for a given number of degrees the calculation of the zigzaginess score. (Default: 5)

tracktable.algorithms.boxiness.sort_by_boxiness(trajectories, calculate_boxiness=True, window=5, simplify_trajectory=False, error_tolerance=1e-05, ignore_zero_degree_quartet=True)[source]

Sorts a list of trajectories by boxiness.

Before sorting, boxiness will be calculated for each trajectory and stored as a property (trajectory.properties[‘boxiness’]). If boxiness has already been calculated and stored under properties, set calculate_boxiness to False to avoid unnecessary computation time.

Note

This boxiness score will be higher for trajectories that move primarily in four directions that are each ninety degrees apart, and this does not exclusively limit to boxes.

Parameters

trajectories (list of Tracktable trajectories) – We will score each of these trajectories for “boxiness” and store the score as a trajectory property.

Keyword Arguments

  • calculate_boxiness (bool) – Calculates boxiness as stores it as a property for each trajectory (trajectory.properties[‘boxiness’]). This property must be calculated and stored before the trajectories can be sorted. (Default: True)

  • window (Odd int) – To account for imperfect boxes, we sum our quartet products over a window of this width (in degrees), centered at the peak quartet product. Note: Even integers will be rounded up to the nearest odd integer. (Default: 5)

  • simplify_trajectory (bool) – We can opt to smooth the trajectory using Tracktable’s simplify function. This can help if we have particularly noisy data, but should be used with caution, as oversmoothing can lower the boxiness scores of true boxes. (Default: False)

  • error_tolerance (float) – The simplify function will not exceed this positional error tolerance, measured in the trajectory’s native distance represented in km. (Default: 0.00001)

  • ignore_zero_degree_quartet (bool) – GPS rounding can cause trajectories that don’t move to create a box-like pattern (since GPS point round to a grid). To ignore these, we can opt to ignore all boxes on the north-south-east-west grid. WARNING: This may delete non-GPS rounding boxes! (Default: True)

Returns

List of trajectories sorted based off of their boxiness score.

tracktable.algorithms.boxiness.sort_by_zigzaginess(trajectories, calculate_zigzaginess=True, buffer=5)[source]

Sorts a list of trajectories by zigzaginess.

Before sorting, zigzaginess will be calculated for each trajectory and stored as a property (trajectory.properties[‘zigzaginess’]). If zigzaginess has already been calculated and stored under properties, set calculate_zigzaginess to False to avoid unnecessary computation time.

Parameters

trajectories (list of Tracktable trajectories) – We will score each of these trajectories for “boxiness” and store the score as a trajectory property.

Keyword Arguments

  • buffer (int) – To account for imperfect zigzags, we need to buffer for a given number of degrees the calculation of the zigzaginess score. (Default: 5)

  • calculate_zigzaginess (bool) – Calculates zigzaginess as stores it as a property for each trajectory (trajectory.properties[‘zigzaginess’]). This property must be calculated and stored before the trajectories can be sorted. (Default: True)

Returns

List of trajectories sorted based off of their zigzaginess score