allensdk.eye_tracking package

Submodules

allensdk.eye_tracking.eye_tracking module

class allensdk.eye_tracking.eye_tracking.EyeTracker(input_stream, output_stream=None, starburst_params=None, ransac_params=None, pupil_bounding_box=None, cr_bounding_box=None, generate_QC_output=False, **kwargs)

Bases: object

Mouse Eye-Tracker.

Parameters:

• input_stream (generator) – Generator that yields numpy.ndarray frames to analyze.
• output_stream (stream) – Stream that accepts numpuy.ndarrays in the write method. None if not outputting annotations.
• starburst_params (dict) – Dictionary of keyword arguments for PointGenerator.
• ransac_params (dict) – Dictionary of keyword arguments for EllipseFitter.
• pupil_bounding_box (numpy.ndarray) – [xmin xmax ymin ymax] bounding box for pupil seed point search.
• cr_bounding_box (numpy.ndarray) – [xmin xmax ymin ymax] bounding box for cr seed point search.
• generate_QC_output (bool) – Flag to compute extra QC data on frames.
• **kwargs – pupil_min_value : int pupil_max_value : int cr_mask_radius : int pupil_mask_radius : int cr_recolor_scale_factor : float recolor_cr : bool adaptive_pupil: bool smoothing_kernel_size : int clip_pupil_values : bool average_iris_intensity : int

DEFAULT_ADAPTIVE_PUPIL = False

DEFAULT_AVERAGE_IRIS_INTENSITY = 40

DEFAULT_CLIP_PUPIL_VALUES = True

DEFAULT_CR_MASK_RADIUS = 10

DEFAULT_CR_RECOLOR_SCALE_FACTOR = 1.7

DEFAULT_GENERATE_QC_OUTPUT = False

DEFAULT_MAX_ECCENTRICITY = 0.25

DEFAULT_MAX_PUPIL_VALUE = 30

DEFAULT_MIN_PUPIL_VALUE = 0

DEFAULT_PUPIL_MASK_RADIUS = 40

DEFAULT_RECOLOR_CR = True

DEFAULT_SMOOTHING_KERNEL_SIZE = 7

find_corneal_reflection()

Estimate the position of the corneal reflection.

Returns:ellipse_parameters – (x, y, r, a, b) ellipse parameters. Return type:tuple

find_pupil(cr_parameters)

Estimate position of the pupil.

Parameters:cr_parameters (tuple) – (x, y, r, a, b) ellipse parameters of corneal reflection, used to prepare image if recolor_cr is set. Returns:ellipse_parameters – (x, y, r, a, b) ellipse parameters. Return type:tuple

im_shape

Image shape.

input_stream

Input frame source.

mean_frame

Average frame calculated from the input source.

process_image(image)

Process an image to find pupil and corneal reflection.

Parameters:image (numpy.ndarray) – Image to process. Returns:

• cr_parameters (tuple) – (x, y, r, a, b) corneal reflection parameters.
• pupil_parameters (tuple) – (x, y, r, a, b) pupil parameters.
• cr_error (float) – Ellipse fit error for best fit.
• pupil_error (float) – Ellipse fit error for best fit.

process_stream(start=0, stop=None, step=1, update_mean_frame=True)

Get cr and pupil parameters from frames of input_stream.

By default this will process every frame in the input stream.

Parameters:

• start (int) – Index of first frame to process. Defaults to 0.
• stop (int) – Stop index for processing. Defaults to None, which runs runs until the end of the input stream.
• step (int) – Number of frames to advance at each iteration. Used to skip frames while processing. Set to 1 to process every frame, 2 to process every other frame, etc. Defaults to 1.
• update_mean_frame (bool) – Whether or not to update the mean frame while processing the frames.

Returns:

• cr_parameters (numpy.ndarray) – [n_frames,5] array of corneal reflection parameters.
• pupil_parameters (numpy.ndarray) – [n_frames,5] array of pupil parameters.
• cr_errors (numpy.ndarray) – [n_frames,] array of fit errors for corneal reflection ellipses.
• pupil_errors (numpy.ndarray) – [n_frames,] array of fit errors for pupil ellipses.

recolor_corneal_reflection(cr_parameters)

Reshade the corneal reflection with the last pupil color.

Parameters:cr_parameters (tuple) – (x, y, r, a, b) ellipse parameters for corneal reflection.

setup_pupil_finder(cr_parameters)

Initialize image and ransac filter for pupil fitting.

If recoloring the corneal_reflection, color it in and provide a filter to exclude points that fall on the colored-in ellipse from fitting.

Parameters:cr_parameters (tuple) – (x, y, r, a, b) ellipse parameters for corneal reflection. Returns:

• image (numpy.ndarray) – Image for pupil fitting. Has corneal reflection filled in if recolor_cr is set.
• filter_function (callable) – Function to indicate if points fall on the recolored ellipse or None if not recoloring.
• filter_parameters (tuple) – Ellipse parameters for recolor ellipse shape, which are cr_parameters with the axes scaled by cr_recolor_scale_factor.

update_fit_parameters(starburst_params=None, ransac_params=None, pupil_bounding_box=None, cr_bounding_box=None, **kwargs)

Update EyeTracker fitting parameters.

Parameters:

• starburst_params (dict) – Dictionary of keyword arguments for PointGenerator.
• ransac_params (dict) – Dictionary of keyword arguments for EllipseFitter.
• pupil_bounding_box (numpy.ndarray) – [xmin xmax ymin ymax] bounding box for pupil seed point search.
• cr_bounding_box (numpy.ndarray) – [xmin xmax ymin ymax] bounding box for cr seed point search.
• generate_QC_output (bool) – Flag to compute extra QC data on frames.
• **kwargs – pupil_min_value : int pupil_max_value : int cr_mask_radius : int pupil_mask_radius : int cr_recolor_scale_factor : float recolor_cr : bool adaptive_pupil: bool smoothing_kernel_size : int clip_pupil_values : bool average_iris_intensity : int

update_last_pupil_color(pupil_parameters)

Update last pupil color with mean of fit.

Parameters:pupil_parameters (tuple) – (x, y, r, a, b) ellipse parameters for pupil.

class allensdk.eye_tracking.eye_tracking.PointGenerator(index_length=150, n_rays=150, cr_threshold_factor=1.2, pupil_threshold_factor=1.2, cr_threshold_pixels=10, pupil_threshold_pixels=10)

Bases: object

Class to find candidate points for ellipse fitting.

Candidates points are found by drawing rays from a seed point and checking for the first threshold crossing of each ray.

Parameters:

• index_length (int) – Initial default length for ray indices.
• n_rays (int) – The number of rays to check.
• cr_threshold_factor (float) – Multiplicative factor for thresholding corneal reflection.
• pupil_threshold_factor (float) – Multiplicative factor for thresholding pupil.
• cr_threshold_pixels (int) – Number of pixels (from beginning of ray) to use to determine threshold of corneal reflection.
• pupil_threshold_pixels (int) – Number of pixels (from beginning of ray) to use to determine threshold of pupil.

DEFAULT_INDEX_LENGTH = 150

DEFAULT_N_RAYS = 150

DEFAULT_THRESHOLD_FACTOR = 1.2

DEFAULT_THRESHOLD_PIXELS = 10

get_candidate_points(image, seed_point, point_type, filter_function=None, filter_args=(), filter_kwargs=None)

Get candidate points for ellipse fitting.

Parameters:

• image (numpy.ndarray) – Image to check for threshold crossings.
• seed_point (tuple) – (y, x) center point for ray burst.
• point_type (str) – Either ‘cr’ or ‘pupil’. Determines if threshold crossing is high-to-low or low-to-high and which threshold_factor and threshold_pixels value to use.

Returns:

candidate_points – List of (y, x) candidate points.

Return type:

list

get_threshold(ray_values, threshold_pixels, threshold_factor)

Calculate the threshold from the ray values.

The threshold is determined from threshold_factor times the mean of the first threshold_pixels values.

Parameters:

• ray_values (numpy.ndarray) – Values of the ray.
• threshold_factor (float) – Multiplicative factor for thresholding.
• threshold_pixels (int) – Number of pixels (from beginning of ray) to use to determine threshold.

Returns:

threshold – Threshold to set for candidate point.

Return type:

float

threshold_crossing(xs, ys, values, point_type)

Check a ray for where it crosses a threshold.

The threshold is calculated using get_threshold.

Parameters:

• xs (numpy.ndarray) – X indices of ray.
• ys (numpy.ndarray) – Y indices of ray.
• values (numpy.ndarray) – Image values along ray.
• point_type (str) – Either ‘cr’ or ‘pupil’. Determines if threshold crossing is high-to-low or low-to-high and which threshold_factor and threshold_pixels value to use.

Returns:

• y_index (int) – Y index of threshold crossing.
• x_index (int) – X index of threshold crossing.

Raises:

ValueError – If no threshold crossing found.

update_params(index_length=150, n_rays=150, cr_threshold_factor=1.2, pupil_threshold_factor=1.2, cr_threshold_pixels=10, pupil_threshold_pixels=10)

Update starburst point generation parameters.

Parameters:

• index_length (int) – Initial default length for ray indices.
• n_rays (int) – The number of rays to check.
• cr_threshold_factor (float) – Multiplicative factor for thresholding corneal reflection.
• pupil_threshold_factor (float) – Multiplicative factor for thresholding pupil.
• cr_threshold_pixels (int) – Number of pixels (from beginning of ray) to use to determine threshold of corneal reflection.
• pupil_threshold_pixels (int) – Number of pixels (from beginning of ray) to use to determine threshold of pupil.

allensdk.eye_tracking.eye_tracking.default_bounding_box(image_shape)

Calculate a default bounding box as 10% in from borders of image.

Parameters:image_shape (tuple) – (height, width) of image. Returns:bounding_box – [xmin, xmax, ymin, ymax] bounding box. Return type:numpy.ndarray

allensdk.eye_tracking.feature_extraction module

allensdk.eye_tracking.feature_extraction.get_circle_template(radius, fill=1, surround=0)

Get circular template for estimating center point.

Returns a cached template if it has already been computed.

Parameters:radius (int) – Radius in pixels of the circle to draw. Returns:template – Circle template. Return type:numpy.ndarray

allensdk.eye_tracking.feature_extraction.max_correlation_positions(image, template, bounding_box=None, reject_coords=None)

Correlate image with template and return the max location.

Correlation is done with mode set to mode and method ‘fft’. It is only performed over the image region within bounding_box if it is provided. The resulting coordinates are provided in the context of the original image.

Parameters:

• image (numpy.ndarray) – Image over which to convolve the kernel.
• template (numpy.ndarray) – Kernel to convolve with the image.
• bounding_box (numpy.ndarray) – [xmin, xmax, ymin, ymax] bounding box on the image.
• reject_coords (tuple) – (r, c) coordinates to disallow as best fit.

Returns:

max_position – (y, x) mean location maximum of the convolution of the kernel with the image.

Return type:

tuple

allensdk.eye_tracking.fit_ellipse module

Module for ellipse fitting.

The algorithm for the actual fitting is detailed at http://nicky.vanforeest.com/misc/fitEllipse/fitEllipse.html.

class allensdk.eye_tracking.fit_ellipse.EllipseFitter(minimum_points_for_fit=40, number_of_close_points=15, threshold=0.0001, iterations=20)

Bases: object

Wrapper class for performing ransac fitting of an ellipse.

Parameters:

• minimum_points_for_fit (int) – Number of points required to fit data.
• number_of_close_points (int) – Number of candidate outliers reselected as inliers required to consider a good fit.
• threshold (float) – Error threshold below which data should be considered an inlier.
• iterations (int) – Number of iterations to run.

DEFAULT_ITERATIONS = 20

DEFAULT_MINIMUM_POINTS_FOR_FIT = 40

DEFAULT_NUMBER_OF_CLOSE_POINTS = 15

DEFAULT_THRESHOLD = 0.0001

fit(candidate_points, **kwargs)

Perform a fit on (y,x) points.

Parameters:candidate_points (list) – List of (y,x) points that may fit on the ellipse. Returns:

• ellipse_parameters (tuple) – (x, y, angle, semi_axis1, semi_axis2) ellipse parameters.
• error (float) – Fit error for the ellipse.

update_params(minimum_points_for_fit=40, number_of_close_points=15, threshold=0.0001, iterations=20)

allensdk.eye_tracking.fit_ellipse.eccentricity(parameters)

Get the eccentricity of an ellipse from the conic parameters.

Parameters:parameters (numpy.ndarray) – Conic parameters of the ellipse. Returns:eccentricity – Eccentricity of the ellipse. Return type:float

allensdk.eye_tracking.fit_ellipse.ellipse_angle_of_rotation(parameters)

Calculate the rotation of the ellipse given the model parameters.

Calculation from http://mathworld.wolfram.com/Ellipse.html

Parameters:parameters (numpy.ndarray) – Parameters of the ellipse fit. Returns:rotation – Rotation of the ellipse. Return type:float

allensdk.eye_tracking.fit_ellipse.ellipse_axis_length(parameters)

Calculate the semi-axes lengths of the ellipse.

Calculation from http://mathworld.wolfram.com/Ellipse.html

Parameters:parameters (numpy.ndarray) – Parameters of the ellipse fit. Returns:semi_axes – Semi-axes of the ellipse. Return type:numpy.ndarray

allensdk.eye_tracking.fit_ellipse.ellipse_center(parameters)

Calculate the center of the ellipse given the model parameters.

Calculation from http://mathworld.wolfram.com/Ellipse.html

Parameters:parameters (numpy.ndarray) – Parameters of the ellipse fit. Returns:center – [x,y] center of the ellipse. Return type:numpy.ndarray

allensdk.eye_tracking.fit_ellipse.ellipse_pass_filter(point, ellipse_params, tolerance, pupil_intensity_estimate=None, pupil_limits=None)

Function to pass or reject an ellipse candidate point.

Points are rejected if they fall on the border defined by ellipse_params. If pupil_limits is provided and pupil_intensity_limits falls outside it the point is rejected as well.

Parameters:

• point (tuple) – (y, x) point.
• ellipse_params (numpy.ndarray) – Ellipse parameters to check against.
• tolerance (float) – Tolerance for determining point is on ellipse.
• pupil_intensity_estimage (float) – Estimated intensity of the pupil used for generating the point.
• pupil_limits (tuple) – (min, max) valid intensities for the pupil.

Returns:

passed – True if the point passes the filter and is a good candidate for fitting.

Return type:

bool

allensdk.eye_tracking.fit_ellipse.fit_ellipse(data, max_radius=None, max_eccentricity=None)

Fit an ellipse to data.

Parameters:

• data (numpy.ndarray) – [n,2] array of (y,x) data points.
• max_radius (float) – Maximum radius to allow.
• max_eccentricity (float) – Maximum eccentricity to allow.

Returns:

• ellipse_parameters (tuple) – (x, y, angle, semi_axis1, semi_axis2) ellipse parameters.
• error (float) – Mean error of the fit.

allensdk.eye_tracking.fit_ellipse.fit_errors(parameters, data)

Calculate the errors on each data point.

Parameters:

• parameters (numpy.ndarray) – Paramaters of the fit ellipse model.
• data (numpy.ndarray) – [n,2] array of (y,x) points.

Returns:

Squared error of the fit at each point in data.

Return type:

numpy.ndarray

allensdk.eye_tracking.fit_ellipse.not_on_ellipse(point, ellipse_params, tolerance)

Function that tests if a point is not on an ellipse.

Parameters:

• point (tuple) – (y, x) point.
• ellipse_params (numpy.ndarray) – Ellipse parameters to check against.
• tolerance (float) – Tolerance for determining point is on ellipse.

Returns:

not_on – True if point is not within tolerance of the ellipse.

Return type:

bool

allensdk.eye_tracking.fit_ellipse.quadratic_parameters(conic_parameters)

Get quadratic ellipse coefficients from conic parameters.

Calculation from http://mathworld.wolfram.com/Ellipse.html

Parameters:conic_parameters (tuple) – (x, y, angle, semi_axis1, semi_axis2) ellipse parameters. Returns:quadratic_parameters – Polynomial parameters for the ellipse. Return type:tuple

allensdk.eye_tracking.frame_stream module

class allensdk.eye_tracking.frame_stream.CvInputStream(movie_path, num_frames=None, process_frame_cb=None)

Bases: allensdk.eye_tracking.frame_stream.FrameInputStream

close()

frame_shape

load_capture_properties()

num_frames

open()

class allensdk.eye_tracking.frame_stream.CvOutputStream(movie_path, frame_shape, frame_rate=30.0, fourcc='H264', is_color=True, block_size=1)

Bases: allensdk.eye_tracking.frame_stream.FrameOutputStream

close()

open(movie_path)

class allensdk.eye_tracking.frame_stream.FrameInputStream(movie_path, num_frames=None, process_frame_cb=None)

Bases: object

close()

frame_shape

get_frame(i)

next()

num_frames

open()

class allensdk.eye_tracking.frame_stream.FrameOutputStream(block_size=1)

Bases: object

close()

open(movie_path)

write(frame)

allensdk.eye_tracking.plotting module

class allensdk.eye_tracking.plotting.Annotator(output_stream=None)

Bases: object

Class for annotating frames with ellipses.

Parameters:output_stream (object) – Object that implements a write method that accepts ndarray frames as well as open and close methods.

COLORS = {'cr': (0, 0, 255), 'pupil': (255, 0, 0)}

annotate_frame(frame, pupil_parameters, cr_parameters, seed=None, pupil_candidates=None)

Annotate an image with ellipses for cr and pupil.

If the annotator was initialized with an output stream, the frame will be written to the stream.

Parameters:

• frame (numpy.ndarray) – Grayscale image to annotate.
• pupil_parameters (tuple) – (x, y, r, a, b) ellipse parameters for pupil.
• cr_parameters (tuple) – (x, y, r, a, b) ellipse parameters for corneal reflection.
• seed (tuple) – (y, x) seed point of pupil.
• pupil_candidates (list) – List of (y, x) candidate points used for the ellipse fit of the pupil.

Returns:

rgb_frame – Color annotated frame.

Return type:

numpy.ndarray

annotate_with_cumulative_cr(frame, filename=None)

Annotate frame with all cr ellipses from the density map.

Parameters:

• frame (numpy.ndarray) – Grayscale frame to annotate.
• filename (string) – Filename to save annotated image to, if provided.

Returns:

rgb_frame – Annotated color frame.

Return type:

numpy.ndarray

annotate_with_cumulative_pupil(frame, filename=None)

Annotate frame with all pupil ellipses from the density map.

Parameters:

• frame (numpy.ndarray) – Grayscale frame to annotate.
• filename (string) – Filename to save annotated image to, if provided.

Returns:

rgb_frame – Annotated color frame.

Return type:

numpy.ndarray

clear_rc()

Clear the cached row and column ellipse border points.

close()

Close the output stream if it exists.

compute_density(frame, pupil_parameters, cr_parameters)

Update the density maps with from the current frame.

Parameters:

• frame (numpy.ndarray) – Input frame.
• pupil_parameters (tuple) – (x, y, r, a, b) ellipse parameters for pupil.
• cr_parameters (tuple) – (x, y, r, a, b) ellipse parameters for corneal reflection.

initiate_cumulative_data(shape)

Initialize density arrays to zeros of the correct shape.

Parameters:shape (tuple) – (height, width) to make the density arrays.

update_rc(name, ellipse_parameters, shape)

Cache new row and column ellipse border points.

Parameters:

• name (string) – “pupil” or “cr” to reference the correct object in the lookup table.
• ellipse_parameters (tuple) – Conic parameters of the ellipse.
• shape (tuple) – (height, width) shape of image used to generate ellipse border points at the right rows and columns.

Returns:

cache_updated – Whether or not new values were cached.

Return type:

bool

allensdk.eye_tracking.plotting.annotate_with_box(image, bounding_box, rgb_vals=(255, 0, 0), filename=None)

Annotate image with bounding box.

Parameters:

• image (numpy.ndarray) – Grayscale or RGB image to annotate.
• bounding_box (numpy.ndarray) – [xmin, xmax, ymin, ymax] bounding box.
• rgb_vals (tuple) – (r, g, b) 0-255 color values for annotation.
• filename (string) – Filename to save annotated image to, if provided.

Returns:

rgb_image – Annotated color image.

Return type:

numpy.ndarray

allensdk.eye_tracking.plotting.annotate_with_cumulative(frame, density, rgb_vals=(255, 0, 0), filename=None)

Annotate frame with all values from density.

Parameters:

• frame (numpy.ndarray) – Grayscale frame to annotate.
• density (numpy.ndarray) – Array of the same shape as frame with non-zero values where the image should be annotated.
• rgb_vals (tuple) – (r, g, b) 0-255 color values for annotation.
• filename (string) – Filename to save annotated image to, if provided.

Returns:

rgb_frame – Annotated color frame.

Return type:

numpy.ndarray

allensdk.eye_tracking.plotting.color_by_mask(rgb_image, mask, rgb_vals=(255, 0, 0))

Color image at points indexed by mask.

The image is recolored in-place.

Parameters:

• rgb_image (numpy.ndarray) – Color image to draw into.
• mask (numpy.ndarray) – Boolean mask of points to color in.
• rgb_vals (tuple) – (r, g, b) 0-255 color values for annotation.

allensdk.eye_tracking.plotting.color_by_points(rgb_image, row_points, column_points, rgb_vals=(255, 0, 0))

Color image at points indexed by row and column vectors.

The image is recolored in-place.

Parameters:

• rgb_image (numpy.ndarray) – Color image to draw into.
• row_points (numpy.ndarray) – Vector of row indices to color in.
• column_points (numpy.ndarray) – Vector of column indices to color in.
• rgb_vals (tuple) – (r, g, b) 0-255 color values for annotation.

allensdk.eye_tracking.plotting.ellipse_perimeter_points(ellipse_params, image_shape)

Generate row, column indices for ellipse perimeter.

Parameters:

• ellipse_params (tuple) – (x, y, r, a b) ellipse parameters.
• image_shape (tuple) – (height, width) shape of image.

Returns:

• row_points (numpy.ndarray) – Row indices for ellipse perimeter.
• column_points (numpy.ndarray) – Column indices for ellipse perimeter.

allensdk.eye_tracking.plotting.ellipse_points(ellipse_params, image_shape)

Generate row, column indices for filled ellipse.

Parameters:

• ellipse_params (tuple) – (x, y, r, a b) ellipse parameters.
• image_shape (tuple) – (height, width) shape of image.

Returns:

• row_points (numpy.ndarray) – Row indices for filled ellipse.
• column_points (numpy.ndarray) – Column indices for filled ellipse.

allensdk.eye_tracking.plotting.get_filename(output_folder, prefix, image_type)

Helper function to build image filename.

Parameters:

• output_folder (string) – Folder for images.
• prefix (string) – Image filename without extension.
• image_type (string) – File extension for image (e.g. ‘.png’).

Returns:

filename – Fill filename of image, or None if no output folder.

Return type:

string

allensdk.eye_tracking.plotting.get_rgb_frame(frame)

Convert a grayscale frame to an RGB frame.

If the frame passed in already has 3 channels, it is simply returned.

Parameters:frame (numpy.ndarray) – Image frame. Returns:rgb_frame – [height,width,3] RGB frame. Return type:numpy.ndarray

allensdk.eye_tracking.plotting.plot_cumulative(pupil_density, cr_density, output_dir=None, show=False, image_type='.png')

Plot cumulative density of ellipse fits for cr and pupil.

Parameters:

• pupil_density (numpy.ndarray) – Accumulated density of pupil perimeters.
• pupil_density – Accumulated density of cr perimeters.
• output_dir (string) – Output directory to store images. Images aren’t saved if None is provided.
• show (bool) – Whether or not to call pyplot.show() after generating both plots.
• image_type (string) – Image extension for saving plots.

allensdk.eye_tracking.plotting.plot_density(density, title=None, filename=None, show=False)

Plot cumulative density.

Parameters:

• density (numpy.ndarray) – Accumulated 2-D density map to plot.
• title (string) – Title for the plot.
• filename (string) – Filename to save the plot to.
• show (bool) – Whether or not to call pyplot.show() after generating the plot.

allensdk.eye_tracking.plotting.plot_summary(pupil_params, cr_params, output_dir=None, show=False, image_type='.png')

Plot timeseries of various pupil and cr parameters.

Generates plots of pupil and cr parameters against frame number. The plots include (x, y) position, angle, and (semi-minor, semi-major) axes seperately for pupil and cr, for a total of 6 plots.

Parameters:

• pupil_params (numpy.ndarray) – Array of pupil parameters at every frame.
• cr_params (numpy.ndarray) – Array of cr parameters at every frame.
• output_dir (string) – Output directory for storing saved images of plots.
• show (bool) – Whether or not to call pyplot.show() after generating the plots.
• image_type (string) – File extension to use if saving images to output_dir.

allensdk.eye_tracking.plotting.plot_timeseries(x1, label1, x2=None, label2=None, title=None, filename=None, show=False)

Helper function to plot up to 2 timeseries against index.

Parameters:

• x1 (numpy.ndarray) – Array of values to plot.
• label1 (string) – Label for x1 timeseries.
• x2 (numpy.ndarray) – Optional second array of values to plot.
• label2 (string) – Label for x2 timeseries.
• title (string) – Title for the plot.
• filename (string) – Filename to save the plot to.
• show (bool) – Whether or not to call pyplot.show() after generating the plot.

allensdk.eye_tracking.ransac module

class allensdk.eye_tracking.ransac.RansacFitter

Bases: object

fit(fit_function, error_function, data, threshold, minimum_points_for_fit, number_of_close_points, iterations, **kwargs)

Find a best fit to a model using ransac.

Parameters:

• fit_function (callable) – Method that fits a model to data.
• error_function (callable) – Function that calculates error given parameters and a subset of data. Returns array of errors, one for each sample.
• data (numpy.ndarray) – Matrix of data points of shape (#samples, #items/sample).
• threshold (float) – Error threshold below which data should be considered an inlier.
• minimum_points_for_fit (int) – Number of points required to fit data.
• number_of_close_points (int) – Number of candidate outliers reselected as inliers required to consider a good fit.
• iterations (int) – Number of iterations to run.
• **kwargs – Additional constraint keyword arguments passed to fit_function.

Returns:

• best_params (numpy.ndarray) – Best parameters of the model.
• best_error (float) – Best error in the fitting.

Raises:

ValueError: – If there is less data than minimum_points_for_fit.

allensdk.eye_tracking.ransac.check_outliers(error_function, parameters, data, outlier_indices, threshold)

Check if any outliers should be inliers based on initial fit.

Parameters:

• error_function (callable) – Function that calculates error given parameters and a subset of data. Returns array of errors, one for each sample.
• parameters (numpy.ndarray) – Model parameters after some fit.
• data (numpy.ndarray) – Matrix of data points of shape (#samples, #items/sample).
• outlier_indices (numpy.ndarray) – Index array for initial outlier guess.
• threshold (float) – Error threshold below which data should be considered an inlier.

Returns:

Index array of new inliers.

Return type:

numpy.ndarray

allensdk.eye_tracking.ransac.fit_iteration(fit_function, error_function, data, threshold, minimum_points_for_fit, number_of_close_points, **kwargs)

Perform one iteration of ransac model fitting.

Parameters:

• fit_function (callable) – Method that fits a model to data.
• error_function (callable) – Function that calculates error given parameters and a subset of data. Returns array of errors, one for each sample.
• data (numpy.ndarray) – Matrix of data points of shape (#samples, #items/sample).
• threshold (float) – Error threshold below which data should be considered an inlier.
• minimum_points_for_fit (int) – Number of points required to fit data.
• number_of_close_points (int) – Number of candidate outliers reselected as inliers required to consider a good fit.
• **kwargs – Additional constraint keyword arguments passed to fit_function.

Returns:

(model parameters, model error)

Return type:

tuple

allensdk.eye_tracking.ransac.partition_candidate_indices(data, minimum_points_for_fit)

Generation indices to partition data into inliers/outliers.

Parameters:

• data (np.ndarray) – Matrix of data points of shape (#samples, #items/sample).
• minimum_points_for_fit (int) – Minimum number of points required to attempt fit.

Returns:

(inliers, outliers) tuple of index arrays for potential

Return type:

tuple

allensdk.eye_tracking.utils module

allensdk.eye_tracking.utils.generate_ray_indices(index_length, n_rays)

Generate index arrays for rays emanating in a circle from a point.

Rays have start point at 0,0.

Parameters:

• index_length (int) – Length of each index array.
• n_rays (int) – Number of rays to generate. Rays are evenly distributed about 360 degrees.

Returns:

(xs, ys) tuple of [n_rays,index_length] index matrices.

Return type:

tuple

allensdk.eye_tracking.utils.get_ray_values(xs, ys, image)

Get values of image along a set of rays.

Parameters:

• xs (np.ndarray) – X indices of rays.
• ys (np.ndarray) – Y indices of rays.
• image (np.ndarray) – Image to get values from.

Returns:

List of arrays of image values along each ray.

Return type:

list

allensdk.eye_tracking.utils.good_coordinate_mask(xs, ys, shape)

Generate a coordinate mask inside shape.

Parameters:

• xs (np.ndarray) – X indices.
• ys (np.ndarray) – Y indices.
• shape (tuple) – (height, width) shape of image.

Returns:

Logical mask for xs and xs to ensure they are inside image.

Return type:

np.ndarray

allensdk.eye_tracking.utils.rotate_rays(xs, ys, angles)

Rotate index arrays about angles.

Parameters:

• xs (np.ndarray) – Unrotated x-index array of shape [1,n].
• ys (np.ndarray) – Unrotated y-index array of shape [1,n].
• angles (np.adarray) – Angles over which to rotate of shape [m,1].

Returns:

(xs, ys) tuple of [m,n] index matrices.

Return type:

tuple

Module contents

Top-level package for AllenSDK Eye Tracking.