| Title: | Image Processing Tools for Barnes Maze Experiments |
|---|---|
| Description: | Tools to process the information obtained from experiments conducted in the Barnes Maze. These tools enable the detection of trajectories generated by subjects during trials, as well as the acquisition of precise coordinates and relevant statistical data regarding the results. Through this approach, it aims to facilitate the analysis and interpretation of observed behaviors, thereby contributing to a deeper understanding of learning and memory processes in such experiments. |
| Authors: | Antonio Guerrero [cre], Vanessa Ramirez [aut], Jorge Macias [ctb] |
| Maintainer: | Antonio Guerrero <[email protected]> |
| License: | LGPL-3 |
| Version: | 1.1.0 |
| Built: | 2026-05-25 07:50:26 UTC |
| Source: | https://github.com/cran/BioTrajectory |
Converts an object of type 'data.frame' or similar into a 'Trajectory' object. The 'data.frame' should contain columns 'x' and 'y' representing the coordinates.
as.trajectory(x, delta_time = 1)as.trajectory(x, delta_time = 1)
x |
An object of class 'data.frame' with 'x' and 'y' columns. |
delta_time |
Control variable with a default value of 1. |
A 'Trajectory' object containing the coordinates from the 'data.frame'.
This function calculates the centroid of a set of points contained in an object of class 'trajectory'. The centroid is the average of the coordinates of all the points.
centroid(obj)centroid(obj)
obj |
An object of class 'trajectory' that must contain a component named 'points'. |
A numeric vector containing the coordinates of the centroid of the points stored in 'obj$points'.
The function first applies the Canny edge detection algorithm to the input image.
It then detects circles corresponding to the board and holes using the
detectCircles function. The function filters the detected hole circles
based on their distance from the board circle, ensuring they fall within acceptable
ranges relative to the specified radii. Finally, it calculates the median radius
and angle differences of the remaining circles and constructs a circular representation
for the holes based on these parameters.
detectBarnes(im, boardRadius, holeRadius, sigma = 25, plot = TRUE)detectBarnes(im, boardRadius, holeRadius, sigma = 25, plot = TRUE)
im |
A matrix representing the image where the circles will be detected. |
boardRadius |
The expected radius of the board circles. |
holeRadius |
The expected radius of the hole circles. |
sigma |
An optional parameter that controls the standard deviation for the Gaussian filter used in edge detection (default value is 25). |
plot |
Opcion of plot |
Detects circles representing boards and holes in a given image of a maze. It utilizes edge detection to identify potential circle patterns based on specified radius parameters. The function returns the detected circles' coordinates, along with additional information about the board and hole radii.
A list containing:
c1 |
Coordinates of the detected board circle. |
boardRadius |
Radius of the board circle. |
c2 |
A list of coordinates representing the detected hole circles. |
holeRadius |
Radius of the hole circles. |
path <- system.file('extdata/data.tiff', package='BioTrajectory') im <- tiff::readTIFF(path) im <- imager::as.cimg(t(im[,,1])) Barnes <- detectBarnes(im, boardRadius=207, holeRadius=13, sigma=25)path <- system.file('extdata/data.tiff', package='BioTrajectory') im <- tiff::readTIFF(path) im <- imager::as.cimg(t(im[,,1])) Barnes <- detectBarnes(im, boardRadius=207, holeRadius=13, sigma=25)
Given a dataset of points, it computes the Euclidean distances from each point to a specified target point. The function also identifies contiguous segments of points that fall within a specified radius around the target.
distanceToTarget(data, target, targetRadious = 0)distanceToTarget(data, target, targetRadious = 0)
data |
An object of class 'trajectory' containing a collection of points with coordinates. |
target |
A numeric vector representing the coordinates of the target point. |
targetRadious |
A numeric value indicating the radius around the target point. Points within this radius are considered to be close to the target. Default is 0. |
A list containing:
distance |
A numeric vector of distances from each point in 'data' to the 'target'. |
r |
A list with two components: 'start', indicating the starting indices of contiguous segments of points within the target radius, and 'length', indicating the lengths of these segments. |
target_radious |
The radius around the target point. |
Computes the cumulative distance between consecutive points in a given set of coordinates. It sums the Euclidean distances between each pair of adjacent points, providing the total distance traveled along the path defined by the points.
distanceTraveled(data)distanceTraveled(data)
data |
An object of class 'trajectory' containing a collection of points with coordinates. |
A numeric value representing the total distance traveled through the points.
This function estimates the center and radius of a circle that best fits four points provided by the user. The user interacts with the plot to select four points, and the function optimizes the parameters (center and radius) using a least squares approach.
getRadius(frame)getRadius(frame)
frame |
The plot or frame to display the points and interact with the user. |
The function plots the provided 'frame' and then uses the 'locator()' function to allow the user to click on four points. The function then performs optimization using the 'optim()' function to minimize the difference between the selected points and the circle's equation.
The objective function ('ftemp') calculates the sum of squared differences between the points and the expected distance from the circle's center.
A vector of length 3, where: - The first element is the x-coordinate of the circle center (cx). - The second element is the y-coordinate of the circle center (cy). - The third element is the radius of the circle (r).
if(interactive()){ path <- system.file('extdata/data.tiff', package='BioTrajectory') im <- tiff::readTIFF(path) im <- imager::as.cimg(t(im[,,1])) frame <- plot(im) circle_params <- getRadius(frame) print(circle_params) }if(interactive()){ path <- system.file('extdata/data.tiff', package='BioTrajectory') im <- tiff::readTIFF(path) im <- imager::as.cimg(t(im[,,1])) frame <- plot(im) circle_params <- getRadius(frame) print(circle_params) }
This function calculates the trajectory of an object in a sequence of images. It compares each frame to a background image to detect movement. The function identifies the largest object in each frame and calculates its centroid coordinates across the sequence.
getTrajectory(listImages, Barnes, iBackground, iBegin, iEnd)getTrajectory(listImages, Barnes, iBackground, iBegin, iEnd)
listImages |
A vector of file paths to the images in the sequence. |
Barnes |
A parameter used by the 'removeBackground()' function to remove background noise. |
iBackground |
An index indicating which image from the sequence is used as the background. |
iBegin |
An index specifying the first image in the sequence to start tracking. |
iEnd |
An index specifying the last image in the sequence to track. |
The function reads the images from 'listImages' and compares each frame to the background image specified by 'iBackground'. Background subtraction is performed using the 'removeBackground()' function, followed by thresholding to identify significant changes between the background and the current frame. The largest connected component in the thresholded image is assumed to be the object of interest, and its centroid is calculated.
Instead of directly returning the centroid coordinates, the function now creates an object of class 'trayectoria' to store the calculated centroids. The coordinates of the object in each frame are added to the 'trayectoria' object. If no object is detected in a frame, the corresponding coordinates are set to 'NA'. The resulting 'trayectoria' object is returned, which allows users to further manipulate and analyze the trajectory of the object across frames.
The returned 'trayectoria' object contains methods for extracting and analyzing the coordinates, making it easier to track the object over time.
An object of class 'trayectoria' containing the points (coordinates) of the object in each frame. The 'trayectoria' object will include the 'x' and 'y' coordinates. If no object is detected in a frame, the corresponding coordinates will be set to 'NA' in the 'trayectoria' object.
# Not run: path <- system.file('extdata/frames', package='BioTrajectory') images <- list.files(path, full.names = TRUE) B <- list(c1 = structure(list(x = 342L, y = 263L), row.names = 1L, class = "data.frame"), boardRadius = 207, c2 = structure(list(x = c(157L, 172L, 202L, 245L, 297L, 352L, 408L, 455L, 494L, 517L, 522L, 507L, 476L, 430L, 375L, 318L, 262L, 215L, 180L, 160L), y = c(242L, 188L, 141L, 105L, 85L, 80L, 93L, 124L, 166L, 219L, 277L, 334L, 383L, 420L, 440L, 442L, 426L, 394L, 350L, 298L), class = "data.frame")), holeRadius = 13) trajectory <- getTrajectory(images, B, 1, 1, 2) print(trajectory)# Not run: path <- system.file('extdata/frames', package='BioTrajectory') images <- list.files(path, full.names = TRUE) B <- list(c1 = structure(list(x = 342L, y = 263L), row.names = 1L, class = "data.frame"), boardRadius = 207, c2 = structure(list(x = c(157L, 172L, 202L, 245L, 297L, 352L, 408L, 455L, 494L, 517L, 522L, 507L, 476L, 430L, 375L, 318L, 262L, 215L, 180L, 160L), y = c(242L, 188L, 141L, 105L, 85L, 80L, 93L, 124L, 166L, 219L, 277L, 334L, 383L, 420L, 440L, 442L, 426L, 394L, 350L, 298L), class = "data.frame")), holeRadius = 13) trajectory <- getTrajectory(images, B, 1, 1, 2) print(trajectory)
Generates a heatmap based on the density of points in a trajectory. It utilizes kernel density estimation to visualize the concentration of points, allowing for adjustments in color palette and plotting limits.
heatmapFromTrajectory(data, plim = NULL, plot.pal = TRUE, ...)heatmapFromTrajectory(data, plim = NULL, plot.pal = TRUE, ...)
data |
An object of class 'trajectory' containing a collection of points with coordinates. |
plim |
Optional vector of length two specifying the plotting limits for the density values. If provided, values outside this range will be adjusted. |
plot.pal |
A logical value indicating whether to plot the color palette alongside the heatmap (default is TRUE). |
... |
Additional graphical parameters to customize the image. |
A matrix of density values corresponding to the heatmap.
Given a dataset of points, it interpolates to generate intermediate points between them.
interpolateTrajectory(data, n = 4)interpolateTrajectory(data, n = 4)
data |
An object of class 'trajectory' containing a collection of points with coordinates. |
n |
An integer indicating the number of intermediate points to generate between each pair of points. Default is 4. |
An object of class 'trayectoria', which contains the 'x' and 'y' coordinates, including both the original points and any interpolated points. The 'trayectoria' object allows users to store, manipulate, and analyze the coordinates of the object across frames. If no object is detected in a frame, the corresponding coordinates will be set to 'NA'.
Checks if an object is of class 'Trajectory'.
is.trajectory(x)is.trajectory(x)
x |
An object to check. |
A logical value ('TRUE' or 'FALSE') indicating whether the object is of class 'Trajectory'.
This function checks if the distance between the first and last points in an object of class 'trajectory' is smaller than a specified tolerance 'tol'. The distance is calculated using the Euclidean distance between the two points.
isClosed(obj, tol = 1e-06)isClosed(obj, tol = 1e-06)
obj |
An object of class 'trajectory' that contains a component 'points'. |
tol |
A numeric value specifying the tolerance. If the distance between the first and last points is smaller than this value, the function returns 'TRUE'. Default is '1e-6'. |
A logical value ('TRUE' or 'FALSE'), indicating whether the distance between the first and last points is smaller than 'tol'.
Calculates the total length of the trajectory, which is the sum of the distances between consecutive points in the 'Trajectory' object.
## S3 method for class 'trajectory' length(x)## S3 method for class 'trajectory' length(x)
x |
An object of class 'Trajectory'. |
A numeric value representing the total length of the trajectory.
Calculates the distances between a set of points and target locations. It identifies the nearest target for each point and checks if the distance is within a specified radius. If a target is found within the radius, its index and distance are returned; otherwise, -1 is returned for both.
nearestTarget(data, targets, r)nearestTarget(data, targets, r)
data |
An object of class 'trajectory' containing a collection of points with coordinates. |
targets |
A matrix or data frame containing the coordinates of the target locations with rows representing targets. |
r |
A numeric value specifying the radius within which to consider targets. |
A data frame with two columns:
nt |
Index of the nearest target for each point. If no target is found within the radius, this will be -1. |
d |
Distance to the nearest target. If no target is found within the radius, this will be -1. |
This function computes the normal vectors at each point of an object of class 'trajectory' by rotating the tangent vectors 90 degrees.
normalVectors(obj)normalVectors(obj)
obj |
An object of class 'trajectory' that contains a component 'points'. |
A matrix of the same dimensions as 'obj$points' with the normal vectors. Each row represents a normal vector at a given point, which is obtained by rotating the corresponding tangent vector by 90 degrees.
Combines two 'Trajectory' objects by concatenating their points. The result is a new trajectory that contains the coordinates of both input trajectories.
## S3 method for class 'trajectory' tr1 | tr2## S3 method for class 'trajectory' tr1 | tr2
tr1 |
A 'Trajectory' object. |
tr2 |
A 'Trajectory' object. |
A new 'Trajectory' object containing the concatenated points of the two input trajectories.
Plots the trajectory by displaying the 'x' and 'y' coordinates as points on a 2D plot. Optionally, you can add a line connecting the points.
## S3 method for class 'trajectory' plot(x, ..., stepSize = 0)## S3 method for class 'trajectory' plot(x, ..., stepSize = 0)
x |
A 'Trajectory' object to plot. |
... |
Other parameters to be passed. |
stepSize |
An integer specifying the interval for plotting segments of the trajectory. If set to 0, the entire trajectory is plotted. Default is 0. |
A plot displaying the trajectory.
Prints a detailed summary of the trajectory, including statistics for both the 'x' and 'y' coordinates and the total number of frames.
## S3 method for class 'summary.trajectory' print(x, ...)## S3 method for class 'summary.trajectory' print(x, ...)
x |
A 'summary.trajectory' object, typically returned by the 'summary.trajectory' method. |
... |
Other parameters to be passed. |
Prints the summary directly.
This function reads an image from a file path and resizes it to a specified number of rows. It supports several image formats, including JPG, JPEG, PNG, TIFF, and TIF. The function also converts the image into a suitable format for further processing.
readImage(path, resizeRows)readImage(path, resizeRows)
path |
The file path of the image to be read. |
resizeRows |
The desired number of rows (height) to resize the image. The aspect ratio of the image will be maintained during resizing. |
The function detects the image format based on the file extension. It currently supports the following formats: JPG, JPEG, PNG, TIFF, and TIF. If the image has more than 3 dimensions (such as an RGBA image with an alpha channel), the alpha channel is discarded. The image is resized only if its height exceeds the specified 'resizeRows'.
A cimg object containing the resized image.
# Example usage img_path <- system.file('extdata/data.tiff', package='BioTrajectory') img <- readImage(img_path, resizeRows = 500) plot(img) # Visualizes the resized image# Example usage img_path <- system.file('extdata/data.tiff', package='BioTrajectory') img <- readImage(img_path, resizeRows = 500) plot(img) # Visualizes the resized image
Reads a text file containing tracking data, where each line represents coordinates. If a line contains "null", it adds NA values for that entry. Optionally, it can remove rows with NA values.
readtrackData(file, na.rm = FALSE)readtrackData(file, na.rm = FALSE)
file |
A character string specifying the path to the file containing the tracking data. |
na.rm |
A logical value indicating whether to remove rows with NA values (default is FALSE). |
An object of class 'trayectoria' containing the points (coordinates) of the object in each frame. The 'trayectoria' object will include the 'x' and 'y' coordinates. If no object is detected in a frame, the corresponding coordinates will be set to 'NA' in the 'trayectoria' object.
# Read tracking data from a file path <- system.file('extdata/track.txt', package='BioTrajectory') tracking_data <- readtrackData(path, na.rm = TRUE) # Print the resulting data frame print(tracking_data)# Read tracking data from a file path <- system.file('extdata/track.txt', package='BioTrajectory') tracking_data <- readtrackData(path, na.rm = TRUE) # Print the resulting data frame print(tracking_data)
This function reverses the order of the points in an object of class 'trajectory' and then constructs a new trajectory using the reversed points. The function assumes the existence of a 'trajectory' function that creates a trajectory from the given x and y coordinates, as well as a time step 'delta_time'.
reverseTrajectory(obj)reverseTrajectory(obj)
obj |
An object of class 'trajectory' that contains a component 'points', which is a matrix or data frame with the coordinates of the points. It is assumed that 'points' has columns 'x' and 'y' representing the coordinates of the points in the trajectory. |
A new trajectory object created using the reversed points and the original 'delta_time' from 'obj'.
This function provides an interactive image frame viewer where the user can navigate through a sequence of images and select a specific one. The viewer uses buttons for navigation (previous and next) and an option to select an image. The function uses the 'rp.control' to create a window for the interface, and 'grid' for displaying images.
selFrame(image_files)selFrame(image_files)
image_files |
A vector of file paths to the images that will be displayed in the viewer. |
The function displays a sequence of images from the provided file paths, allowing the user to navigate between them using "Previous" and "Next" buttons. The images are displayed using 'grid.raster' from the 'grid' package. A "Select" button allows the user to select the current image, and the function returns the index of the selected image.
The index of the selected image.
# Not run: path <- system.file('extdata/frames/', package='BioTrajectory') image_files <- list.files(path, pattern = "\\.png$", full.names = TRUE) selFrame(image_files)# Not run: path <- system.file('extdata/frames/', package='BioTrajectory') image_files <- list.files(path, pattern = "\\.png$", full.names = TRUE) selFrame(image_files)
This function generates a plot of the distance to a target over time or some other associated parameter in the object. It also draws a horizontal line to indicate the target radius and a red segment that shows the start and length of a parameter associated with the 'obj'.
showDistanceToTarget(obj, ...)showDistanceToTarget(obj, ...)
obj |
An object that must contain at least three elements: distance:A numeric vector representing the distance to the target targetRadious: A numeric value indicating the target radius. r:An object containing at least two elements: - start: A numeric value representing the start of the range. - length: A numeric value representing the length of the range. |
... |
Additional parameters of object. |
This function generates a line plot of the distance to a target (stored in 'obj$distance'). It also draws a red horizontal line at the value of 'obj$targetRadious' to indicate the target's radius. Additionally, a red vertical segment is drawn to show the start of the range defined by 'obj$r$start' and the length defined by 'obj$r$length'.
A plot showing the relationship between the object's position and the target's position.
# Create a fictional object with example data obj <- list( distance = rep(c(5, 10, 15, 20, 15, 10, 5),5), targetRadious = 12, r = list(start = 2, length = 10) ) # Visualize the distance to the target using the function showDistanceToTarget(obj)# Create a fictional object with example data obj <- list( distance = rep(c(5, 10, 15, 20, 15, 10, 5),5), targetRadious = 12, r = list(start = 2, length = 10) ) # Visualize the distance to the target using the function showDistanceToTarget(obj)
This function applies a moving average filter to the 'x' and/or 'y' coordinates of a "trajectory" object. The filter is applied using a window of a specified size. The function then creates a new trajectory object using the smoothed coordinates. The filter is applied symmetrically around each point.
smoothTrajectory(obj, method = c("x", "y", "both"), window = 3)smoothTrajectory(obj, method = c("x", "y", "both"), window = 3)
obj |
An object of class 'trajectory' that contains a component 'points', which is a data frame with the coordinates of the points. It is assumed that 'points' has columns 'x' and 'y' representing the trajectory coordinates. |
method |
A character string specifying which coordinate(s) to smooth. Can be one of '"x"', '"y"', or '"both"'. Default is '"both"', which smooths both the 'x' and 'y' coordinates. |
window |
An odd integer specifying the window size for the moving average filter. The window must be an odd number to ensure a symmetric filter. Default is 3. |
A new trajectory object created using the smoothed 'x' and 'y' coordinates.
This function subsamples the points of a 'trajectory' object by selecting every 'step'-th point. It then creates a new trajectory using the selected points, adjusting the 'delta_time' accordingly.
subsampleTrajectory(obj, step = 2)subsampleTrajectory(obj, step = 2)
obj |
An object of class 'trajectory' that contains a component 'points'. The 'points' component must have columns 'x' and 'y' representing the trajectory coordinates. |
step |
A positive integer that defines the step size for subsampling the points. Default is '2', meaning every second point will be selected. |
A new trajectory object created using the subsampled points and the adjusted 'delta_time'.
Generates a summary of the trajectory, including the minimum, maximum, and mean of the 'x' and 'y' coordinates, as well as the total number of frames.
## S3 method for class 'trajectory' summary(object, ...)## S3 method for class 'trajectory' summary(object, ...)
object |
An object of class 'Trajectory'. |
... |
Other parameters to be passed. |
A summary object containing statistics for both the 'x' and 'y' coordinates of the trajectory.
This function calculates the unit tangent vectors at each point of the trajectory represented by a 'trajectory' object. The tangent vectors are computed by taking the difference between consecutive points and normalizing them to have unit length.
tangentVectors(obj)tangentVectors(obj)
obj |
An object of class 'trajectory' that contains a component 'points'. |
A matrix where each row is a unit tangent vector corresponding to each pair of consecutive points in 'obj$points'.
A class representing a trajectory of an object over time, including the 'x' and 'y' coordinates of the object's centroids across frames. It provides methods to manipulate and analyze the trajectory, such as calculating the length, summarizing the trajectory, printing the summary, and plotting the trajectory.
trajectory(x, y, delta_time = 1)trajectory(x, y, delta_time = 1)
x |
Numeric vector with the 'x' coordinates of the trajectory. |
y |
Numeric vector with the 'y' coordinates of the trajectory. |
delta_time |
Control variable with a default value of 1. |
The 'Trajectory' class stores the coordinates of an object across multiple frames. The class provides methods to compute various aspects of the trajectory, such as its length and summary statistics, as well as visualizations. It can also be used to manipulate the trajectory, such as combining it with another trajectory using the '|' operator.
This function trims the points of a 'trajectory' object by selecting a subset of the points from the specified 'from' to 'to' indices. It then creates a new trajectory using the selected points.
trimTrajectory(obj, from = 1, to = nrow(obj$points))trimTrajectory(obj, from = 1, to = nrow(obj$points))
obj |
An object of class 'trajectory' that contains a component 'points', which is a data frame with the coordinates of the points in the trajectory. |
from |
A positive integer indicating the starting index of the points to include. Default is 1. |
to |
A positive integer indicating the ending index of the points to include. Default is the total number of rows in 'obj$points'. |
A new trajectory object created using the subset of points from the 'from' to 'to' indices.
This function is a wrapper that simplifies extracting frames from a video. It processes the video file and saves the frames as PNG images in the specified directory. By default, it extracts 15 frames per second.
videoToFrames(videoPath, outputDir, fps = 15)videoToFrames(videoPath, outputDir, fps = 15)
videoPath |
Path to the video file. |
outputDir |
Path to the directory where the extracted images will be saved. |
fps |
The number of frames shown per second in the video. By default, it extracts 15 frames per second. |
A list of file paths to the generated images.
# Not run: videoPath <- system.file('extdata/video.mp4', package='BioTrajectory') outputDir <- system.file('extdata/frames/', package='BioTrajectory') images <- videoToFrames(videoPath, outputDir, fps=15) print(images) # Displays the paths to the generated images# Not run: videoPath <- system.file('extdata/video.mp4', package='BioTrajectory') outputDir <- system.file('extdata/frames/', package='BioTrajectory') images <- videoToFrames(videoPath, outputDir, fps=15) print(images) # Displays the paths to the generated images