LineOfInterest

class movement.roi.LineOfInterest(points, loop=False, name=None)

Bases: BaseRegionOfInterest

Representation of boundaries or other lines of interest.

This class can be used to represent boundaries or other internal divisions of the area in which the experimental data was gathered. These might include segments of a wall that are removed partway through a behavioural study, or coloured marking on the floor of the experimental enclosure that have some significance. Instances of this class also constitute the boundary of two-dimensional regions (polygons) of interest.

An instance of this class can be used to represent these “one dimensional regions” (lines of interest, LoIs) in an analysis. The basic usage is to construct an instance of this class by passing in a list of points, which will then be joined (in sequence) by straight lines between consecutive pairs of points, to form the LoI that is to be studied.

Methods

compute_allocentric_angle_to_nearest_point(...)	Compute the allocentric angle to the nearest point in the region.
compute_angle_to_normal(direction, position)	Compute the angle between the normal to the segment and a direction.
compute_approach_vector(point[, ...])	Compute the approach vector from a point to the region.
compute_distance_to(point[, boundary_only])	Compute the distance from the region to a point.
compute_egocentric_angle_to_nearest_point(...)	Compute the egocentric angle to the nearest point in the region.
compute_nearest_point_to(position[, ...])	Compute (one of) the nearest point(s) in the region to position.
contains_point(position[, include_boundary])	Determine if a position is inside the region of interest.
normal([on_same_side_as])	Compute the unit normal to this line.
plot([ax])	Plot the region of interest on a new or existing axis.

compute_allocentric_angle_to_nearest_point(position, boundary_only=False, in_degrees=False, reference_vector=None)

Compute the allocentric angle to the nearest point in the region.

With the term “allocentric”, we indicate that we are measuring angles with respect to a reference frame that is fixed relative to the experimental/camera setup. By default, we assume this is the positive x-axis of the coordinate system in which position is.

The allocentric angle is the signed angle between the approach vector and a given reference vector.

Parameters:

• position (xarray.DataArray) – DataArray of spatial positions.

• boundary_only (bool) – If True, the allocentric angle to the closest boundary point of the region is computed. Default False.

• in_degrees (bool) – If True, angles are returned in degrees. Otherwise angles are returned in radians. Default False.

• reference_vector (ArrayLike | xr.DataArray) – The reference vector to be used. Dimensions must be compatible with the argument of the same name that is passed to compute_signed_angle_2d(). Default (1., 0.).

Return type:

DataArray

See also

compute_approach_vector

The method used to compute the approach vector.

compute_egocentric_angle_to_nearest_point

Related class method for computing the egocentric angle to the region.

movement.utils.vector.compute_signed_angle_2d

The underlying function used to compute the signed angle between the approach vector and the reference vector.

compute_angle_to_normal(direction, position, in_degrees=False)

Compute the angle between the normal to the segment and a direction.

The returned angle is the signed angle between the normal to the segment and the direction vector(s) provided.

Parameters:

• direction (xarray.DataArray) – An array of vectors representing a given direction, e.g., the forward vector(s).

• position (xr.DataArray) – Spatial positions, considered the origin of the direction.

• in_degrees (bool) – If True, angles are returned in degrees. Otherwise angles are returned in radians. Default False.

Return type:

DataArray

See also

movement.utils.vector.compute_signed_angle_2d

For the definition of the signed angle between two vectors.

compute_approach_vector(point, boundary_only=False, unit=False)

Compute the approach vector from a point to the region.

The approach vector is defined as the vector directed from the point provided, to the closest point that belongs to the region.

Parameters:

• point (ArrayLike) – Coordinates of a point to compute the vector to (or from) the region.

• boundary_only (bool) – If True, the approach vector to the boundary of the region is computed. Default False.

• unit (bool) – If True, the approach vector is returned normalised, otherwise it is not normalised. Default is False.

Returns:

Approach vector from the point to the region.

Return type:

np.ndarray

See also

compute_allocentric_angle_to_nearest_point

Relies on this method to compute the approach vector.

compute_egocentric_angle_to_nearest_point

Relies on this method to compute the approach vector.

compute_distance_to(point, boundary_only=False)

Compute the distance from the region to a point.

Parameters:

• point (ArrayLike) – Coordinates of a point, from which to find the nearest point in the region defined by self.

• boundary_only (bool, optional) – If True, compute the distance from point to the boundary of the region, rather than the closest point belonging to the region. Default False.

Returns:

Euclidean distance from the point to the (closest point on the) region.

Return type:

float

compute_egocentric_angle_to_nearest_point(direction, position, boundary_only=False, in_degrees=False)

Compute the egocentric angle to the nearest point in the region.

With the term “egocentric”, we indicate that we are measuring angles with respect to a reference frame that is varying in time relative to the experimental/camera setup.

The egocentric angle is the signed angle between the approach vector and a direction vector (examples include the forward vector of a given individual, or the velocity vector of a given point).

Parameters:

• direction (xarray.DataArray) – An array of vectors representing a given direction, e.g., the forward vector(s).

• position (xarray.DataArray) – DataArray of spatial positions, considered the origin of the direction vector.

• boundary_only (bool) – Passed to compute_approach_vector() (see Notes). Default False.

• in_degrees (bool) – If True, angles are returned in degrees. Otherwise angles are returned in radians. Default False.

Return type:

DataArray

See also

compute_allocentric_angle_to_nearest_point

Related class method for computing the egocentric angle to the region.

compute_approach_vector

The method used to compute the approach vector.

movement.utils.vector.compute_signed_angle_2d

The underlying function used to compute the signed angle between the approach vector and the reference vector.

compute_nearest_point_to(position, boundary_only=False)

Compute (one of) the nearest point(s) in the region to position.

If there are multiple equidistant points, one of them is returned.

Parameters:

• position (ArrayLike) – Coordinates of a point, from which to find the nearest point in the region.

• boundary_only (bool, optional) – If True, compute the nearest point to position that is on the boundary of self. Default False.

Returns:

Coordinates of the point on self that is closest to position.

Return type:

np.ndarray

contains_point(position, include_boundary=True)

Determine if a position is inside the region of interest.

Parameters:

• position (ArrayLike) – Spatial coordinates [x, y, [z]] to check as being inside the region.

• include_boundary (bool) – Whether to treat a position on the region’s boundary as inside the region (True) or outside the region (False). Default True.

Returns:

True if the position provided is within the region of interest. False otherwise.

Return type:

bool

property coords: CoordinateSequence

Coordinates of the points that define the region.

These are the points passed to the constructor argument points.

Note that for Polygonal regions, these are the coordinates of the exterior boundary, interior boundaries must be accessed via self.region.interior.coords.

property dimensions: int

Dimensionality of the region.

property is_closed: bool

Return True if the region is closed.

A closed region is either: - A polygon (2D RoI). - A 1D LoI whose final point connects back to its first.

property name: str

Name of the instance.

normal(on_same_side_as=(0.0, 0.0))

Compute the unit normal to this line.

The unit normal is a vector perpendicular to the input line whose norm is equal to 1. The direction of the normal vector is not fully defined: the line divides the 2D plane in two halves, and the normal could be pointing to either of the half-planes. For example, a horizontal line divides the 2D plane in a bottom and a top half-plane, and we can choose whether the normal points “upwards” or “downwards”. We use a sample point to define the half-plane the normal vector points to.

If this is a multi-segment line, the method raises an error.

Parameters:

on_same_side_as (ArrayLike) – A sample point in the (x,y) plane the normal is in. If multiple points are given, one normal vector is returned for each point given. By default, the origin is used.

Return type:

ndarray

:raises ValueError : When the normal is requested for a multi-segment geometry.:

plot(ax=None, **matplotlib_kwargs)

Plot the region of interest on a new or existing axis.

Parameters:

• ax (plt.Axes, optional) – matplotlib.pyplot.Axes object to draw the region on. A new Figure and Axes will be created if not provided.

• matplotlib_kwargs (Any) – Keyword arguments passed to the matplotlib.pyplot plotting function.

Return type:

tuple[Figure, Axes]

property region: LinearRing | LineString | Polygon

shapely.Geometry representation of the region.

Examples using LineOfInterest

Compute distances and angles to regions of interest

Compute distances and angles to regions of interest