fish_track package

Submodules

fish_track.kernel module

fish_track.kernel.add_shadow(x, sigma)

Effectively add a negative zone around image x where x > x.mean

fish_track.kernel.get_kernels(images, pc_indices, cluster_num, plot=True, sigma=0)

  1. calculate the principle component of different images

  2. project images on some principles

  3. cluster the projected images

  4. calculate average for each cluster

  5. return the averaged images

Parameters

  • images (np.ndarray) – images obtained from fish_track.shape.get_shapes()

  • pc_indices (np.ndarray) – indices of the principle components

  • cluster_num (int) – the number of clusters (k)

  • sigma (float) – the sigma of the “shadow” add around the kernel

fish_track.kernel.plot_pca(dim, mean, pcs, name='pca')
fish_track.kernel.vanilla_pca(images)
Parameters

images (np.ndarray) – a collections of images to perform PCA

Returns

the projection matrix, the variance and mean

Return type

tuple

fish_track.linking module

class fish_track.linking.ActiveLinker(search_range)

Bases: object

Link positions into trajectories following 10.1007/s00348-005-0068-7 Works with n-dimensional data in Euclidean space

Getting trajectories from positions in different frames

Parameters

frames (list of numpy.ndarray) – the positions of particles in different frames from the experimental data

Returns

a collection of trajectories. Each trajectory is represented by a list, [time_points, positions]

Return type

list

class fish_track.linking.TrackpyLinker(max_movement, memory=0, max_subnet_size=30, **kwargs)

Bases: object

Linking positions into trajectories using Trackpy Works with 2D and 3D data. High dimensional data not tested. (no expiment available)

Parameters

  • positions (np.ndarray) – shape (time, num, dim)

  • time_points (np.ndarray) – shape (time, ), time_points may not be continues

  • labels (np.ndarray) – if given, the result will have a ‘label’ attribute which specifies the label values in different frames [(frame_index, [labels, … ]), …], shape (time, num)

class fish_track.linking.Trajectory(time, positions, blur=None, velocities=None, blur_velocity=None)

Bases: object

Bundle handy methods with trajectory data

break_into_two(time_index)

Break one trajectory into two trajectories.

Parameters

time_index (int) – the index of self.time at which the trajectory will be break down.

Returns

a list of two trajecotires

Return type

list

distance(traj)

Calculate the distance between self and another trajectory

the distance is defined as the distance where the earlier trajectory

travel to future, and the later trajectory travel to past, and the distance where they meet in time.

The purpose of such calculation is to improve the linking success rate.

interpolate()
offset(time)

offset all time

predict(t)

predict the position of the particle at future time-point t

retrace(t)

retrace the position of the particle at previous time-point t

Parameters

  • trajectories (list of Trajectory) – unlinked trajectories

  • network (list of numpy.ndarray) – the chosen network to link trajectories Each network may have different sizes

Returns

trajectories that were connected according to the given network

Return type

list of Trajectory

fish_track.linking.apply_network_merge(trajectories, network)
Merge the trajectories. The earlier trajecotires will be clipped and

connectd to later trajectories

Parameters

  • trajectories (list of Trajectory) – unmerged trajectories

  • network (list of numpy.ndarray) – the chosen network to merge trajectories. Each network may have different sizes.

Returns

trajectories that were merged

according to the given network

Return type

list of Trajectory

fish_track.linking.build_dist_matrix_sparse(trajs_sorted, dt, dx, cost, time_filter, debug=False)

Build a sparse distance matrix, then squeeze it

Parameters

  • trajs_sorted (list) – trajectories obtained from sort_trajectories()

  • dt (int) – if the time[-1] of traj #1 + dt > time[0] of traj #2 consider a link being possible

  • dx (float) – if within dt, the distance between * trajectory #1’s prediction and * trajectory #2’s first point is smaller than dx, assign a link

  • cost (callable) – the function to calculate cost between two trajectories, trajectories with smaller cost will be linked

Returns

(distance matrix (scipy.sparse.coo_matrix), row_map, col_map)

The row_map and col_map are used to map from squeezed distance matrix to origional distance matrix

Return type

tuple

fish_track.linking.choose_network(distance_matrix, networks) → numpy.ndarray

Choose the network with minimum distance amonest a collection of networks

Parameters

  • distance_matrix (numpy.ndarray) – the distances for different links. distance_matrix[link] –> distance of this link

  • networks (numpy.ndarray) – a collection of networks, a network is a collection of links. The shape is (n_network, n_link, 2)

Returns

the network with minimum distance, shape (n_link, 2)

Return type

numpy.ndarray

fish_track.linking.cost_dist(traj_1, traj_2)
Parameters
Returns

the cost value

Return type

float

fish_track.linking.cost_merge(traj_1, traj_2)
fish_track.linking.cost_xu(traj_1, traj_2)
fish_track.linking.get_trajectory(labels, frames, target: int)
fish_track.linking.merge_trajectories(trajectories, dx, dt, debug=False)

Merge two trajectories, t1 and t2, if the end of t1 matches the head of t2.

Parameters

  • trajectories (list) – A collection of trajectories. Each trajectory is stored in a tuple, (time, positions)

  • dx (float) – distance threshold, t1 and t2 were considered to be matched if the distance between the end of t1 and the head of t2 were is smaller than dx.

Returns

a collection of merged trajectories

Return type

(list)

fish_track.linking.reduce_network(network)

Network is compose of linkes that looks like,

[(i_1, j_1), (i_2, j_2) ...]

The network is sorted with

i_n > ... > i_2 > i_1
Parameters

network (numpy.ndarray) – a collection of links, shape (n, 2)

Returns

the reduced network

Return type

list of numpy.ndarray

Example

>>> input = np.array([(0, 1), (1, 3), (3, 5), (4, 5), (6, 7), (7, 8)])
>>> output = np.array([(0, 1, 3, 5), (4, 5), (6, 7, 8)])
>>> [np.allclose(i, o) for i, o in zip(reduce_network(input), output)]
[True, True, True]

Re-link short trajectories into longer ones.

Parameters

  • trajectories (list) – A collection of trajectories, where each trajectory is stored in a tuple in the form of, (time, positions)

  • dx (float) – distance threshold, the only trajectories whose ‘head’ and ‘tail’ is smaller than dx in space were considered as a possible link

  • dt (int) – time threshold, the only trajectories whose ‘head’ and ‘tail’ is smaller than dt in time were considered as a possible link

  • blur (float or bool) – if blur is provided, all trajectories were filtered using a gaussian kernel, whose sigma is the value of blur

Returns

The relink trajectories.

Each trajectory is stored in a tuple, (time, positions)

Return type

list of tuple

Re-link short trajectories into longer ones.

The task is firstly separated into different segments with equal size, then combined

Parameters

  • trajectories (list) – A collection of trajectories. Each trajectory is stored in a tuple, (time, positions)

  • window_size (int) – the frame number size of each segment for the relink of the 1st iteration

  • max_frame (int) – the maximum number of frames

  • dx (float) – distance threshold, the only trajectories whose ‘head’ and ‘tail’ is smaller than dx in space were considered as a possible link

  • dt (int) – time threshold, the only trajectories whose ‘head’ and ‘tail’ is smaller than dt in time were considered as a possible link

  • blur (float or bool) – if blur is provided, all trajectories were filtered using a gaussian kernel, whose sigma is the value of blur

Returns

The relink trajectories.

Each trajectory is stored in a tuple, (time, positions)

Return type

list of tuple

fish_track.linking.segment_trajectories(trajectories, window_size, max_frame)

Split trajectories into different segments according to their starting time points

If there are 5400 frames, with a window_size = 500, then the edges of each segment are

[0, 500, 1000, 1500, 2000, 2500, 3000, 3500, 4000, 4500, 5000, 5400]
Parameters

  • trajectories (list) – A collection of trajectories. Each trajectory is stored in a tuple, (time, positions)

  • window_size (int) – the frame number size of each segment for the relink of the 1st iteration

  • max_frame (int) – the maximum number of frames

Returns

a list of trajectories in different segments

Return type

list

fish_track.linking.solve_unique(rows, cols, values, debug=False)

Find the link between two trajecotires that are both one-to-one and onto

That is to say, trajectory A only link to B, and B is only only linked by A.

Example:

..code-block:: python

A B

——> ——-> (first) (second)

Parameters

  • rows (np.ndarray) – The indices of the first trajectories

  • cols (np.ndarray) – The indices of the second trajectories

  • values (np.ndarray) – The distances between the prediction of first trajectory and the start of the second trajectory. Essentially this is the error.

Returns

(

not-unique row indices, not-unique col indices, not-unique distances, unique_links

)

Return type

tupel

fish_track.linking.sort_trajectories(trajectories)

Sort trajectories according to the first time point in each traj

Parameters

trajectories (List) – a collection of Trajectory or obj:tuple which contains the time points and positions of each trajectory

Returns

the sorted trajectories, each trajectory maintains the same type.

Return type

list

fish_track.linking.squeeze_sparse(array)

Given the indices in a row or column from a sparse matrix Remove the blank rows/columns

array[i + 1] >= array[i]
Parameters

array (numpy.ndarray) – the indices of columes/rows in a sparse matrix

Returns

the matrix without blank columes/rows

Return type

numpy.ndarray

Example

>>> input = np.array([44, 53, 278, 904, 1060, 2731])
>>> output = np.array([0, 1, 2, 3, 4, 5])
>>> np.allclose(output, squeeze_sparse(output))
True

Return ture if two trajectories would form portational link

fish_track.linking.time_filter_merge(traj_1, traj_2, dt)

Return ture if two trajectories would form portational link

fish_track.nrook module

solve n rook problem in restricted available sites

fish_track.nrook.solve_nrook(lm: numpy.ndarray[bool[m, n]]) → numpy.ndarray[int32]

solve the n rook problem in a given availabel sites

fish_track.nrook.solve_nrook_dense(lm: numpy.ndarray[bool[m, n]], max_row: int) → numpy.ndarray[int32]

solve the n rook problem in a given availabel sites from a dense distance matrix

fish_track.nrook module

solve n rook problem in restricted available sites

fish_track.nrook.solve_nrook(lm: numpy.ndarray[bool[m, n]]) → numpy.ndarray[int32]

solve the n rook problem in a given availabel sites

fish_track.nrook.solve_nrook_dense(lm: numpy.ndarray[bool[m, n]], max_row: int) → numpy.ndarray[int32]

solve the n rook problem in a given availabel sites from a dense distance matrix

fish_track.oishi module

fish_track.oishi.get_align_diff(orientations)

Get the difference between alignment angles of different agents

Parameters

orientations (np.ndarray) – the orientations of different features in degree

Returns

the distance between orientations

Return type

np.ndarray

fish_track.oishi.get_align_map(features, rot_num)
fish_track.oishi.get_box_for_kernel(kernel, u, v, image) → tuple

Get a boundary of the kernel in a bigger image the kernel is located at (u, v) in the image

fish_track.oishi.get_clusters(feature, kernels, angles, kernel_threshold=0.0)
Returns

the pixels that ‘belong’ to different features

the returnned results are (x, y), the shape is (number, dimension)

Return type

list

fish_track.oishi.get_clusters_from_image(feature, kernels, image, angles, roi, kernel_threshold=0.0) → list
Parameters

  • feature (np.ndarray) – oishi feature generated by get_oishi_features()

  • kernels (list of np.ndarray) – oishi kernels generated by get_oishi_kernels()

  • image (np.ndarray) – the processed binary image

  • angles (np.ndarray) – the discrete angles used to generate kernels

  • roi (tuple) – region of interests in the image

  • kernel_threshold (float) – intensity threshold

Returns

the pixels that ‘belong’ to different features

the returnned results are (x, y) the shape is (number, dimension)

Return type

list

fish_track.oishi.get_clusters_with_roi(feature, kernels, angles, roi, kernel_threshold=0.0)
Returns

the pixels that ‘belong’ to different features

the returnned results are (x, y), the shape is (number, dimension)

Return type

list

fish_track.oishi.get_oishi_features(image, oishi_kernels, threshold=0.5, local_size=4)

Calculate the oishi features in an image

Parameters

  • image (np.ndarray) – 2D image

  • oishi_kernels (list of np.ndarray) – the kernels with different shapes/scales/orientations

  • threshold (float) – intensity threshold

  • local_size (int) – the local maxima defined were considered as potential oishi features

Returns

oishi features, shape (6, n)

[x, y, orientation, shape, brightness, likelihood] the returned feature location is (x, y) in the image coordinate NOT (row, colume)

Return type

np.ndarray

fish_track.oishi.get_oishi_kernels(kernels, rot_num=35)
fish_track.oishi.get_sub_image(image, centre, window)
fish_track.oishi.join_pairs(pairs) → list
fish_track.oishi.o2v(orientation, angles) → numpy.ndarray

Convert orientation to a unit vector

Parameters

  • orientation (int) – label of the orientation. angles[labels] yields the actural angle value

  • angles (np.ndarray) – the unit is degree

Returns

the (x, y) direction of the orientation

Return type

np.ndarray

fish_track.oishi.refine_oishi_features(features, rot_num, dist_threshold, orient_threshold, likelihood_threshold, intensity_threshold)
fish_track.oishi.rotate_kernel(kernel, angle)

Rotate the kernel with given angle, and shift the highest value to the centre

Parameters

  • kernel (np.ndarray) – a 2D image representing the kernel of a shape

  • angle (float) – The rotation angle in degrees

Returns

The rotated kernel

Return type

np.ndarray

Example

>>> kernel = np.zeros((5, 5))
>>> kernel[2, :] = np.array([1, 1, 2, 1, 1])  # 2D image with a horizontal line
>>> target = np.zeros((5, 5))
>>> target[:, 2] =np.array([1, 1, 2, 1, 1])  # 2D image with a vertical line
>>> np.allclose(rotate_kernel(kernel, 90), target)  # rotate kernel 90 degrees
True

fish_track.read module

fish_track.read.get_background(video_iter, step=1, max_frame=1000, process=<function <lambda>>)
fish_track.read.get_background_movie(file_name, length=1500, output='background.avi', fps=15, cache='deque')

Get a movie of background, being a box-average along time series with length of length Save bg every segment (25 frames), and save difference otherwise

fish_track.read.get_foreground_movie(video, background, output='foreground.avi', process=<function <lambda>>, fps=15, local=5, thresh_flag=0, bop=0)

Generate a movie that only has foreground pixels

Parameters

  • video (str) – name of the video to be processed (from camera)

  • background (str) – name of the background video. It is assumend that the foreground is darker, so foreground = backgroudn - video

  • preprocess (Callable) – a python function to process both foreground and background before the substraction

  • fps (int or float) – the frame rate of the obtained video

  • local (int) – the range of the local threshold

  • threh_flag (int) – flags for the global threshold, 0 - otsu; 1 - triangle; >1 - fixed value threshold, value is given number

  • bop (int) – the binary open morphological transformation, 0 - don’t use; >0 - size of the kernel

Return: None, but create a movie file

fish_track.read.get_frame(file_name, frame)

return the frame content as an array

fish_track.read.get_frame_number(file_name)
fish_track.read.get_frames_from_xyz(filename, ncols=3)
fish_track.read.get_trajectories_xyz(filename)
fish_track.read.iter_image_sequence(folder, prefix='frame_', start=0)
fish_track.read.iter_video(file_name, roi=None, start=0)
fish_track.read.make_difference_movie(filename, start=0, end=0, kind='video', transform=<function <lambda>>)

Return a movie that stores the difference between successive frames

fish_track.shape module

fish_track.shape.align_sub_image(sub_image, want_ar=False)

Align the image Everything is in 2d

fish_track.shape.get_maxima(image: numpy.ndarray, threshold: float, window_size)

return the location of features in the image the result is (u, v), not (row, column) :return maxima: shape is (n, 2)

fish_track.shape.get_shapes(image, fish, report=False)

measure and aligh individual shapes in an image if report were True, also return the volumes and aspect_ratios

fish_track.shape.get_sub_image_box(position, radius, image_shape=None)
fish_track.shape.get_sub_images(image, centres, max_radius)

only works for 2d image

fish_track.shape.is_inside(position, radius, boundary)

fish_track.utility module

support only python3 because of __dict__.items() it’s 2019 now come on

class fish_track.utility.Configure(config_file)

Bases: object

write(config_file)
class fish_track.utility.SubProperty(dictionary)

Bases: object

fish_track.utility.detect_circle(image: numpy.array, size=50, upper_threshold=0.5)

Detect the central circle in the image The foreground is dark :param image: 2d image as numpy array :return: the (x, y) coordinates of the centre

fish_track.utility.draw_2d(radius: int)
fish_track.utility.join_pairs(pairs)
fish_track.utility.validate(images, model, fail_mark=0.25, shape=(40, 40))

validate shapes with trained keras model good shape: probability of being good > fail_mark

Module contents