Module: trajectory_utils

A collection of methods for working with Trajectories

Examples

• Create a Trajectory from parameters.

• Convert a Trajectory into another data type.

• Serialize and deserialize a Trajectory.

• Use a trajectory and WCS to predict RA, dec positions.

kbmod.trajectory_utils.avg_trajectory_distance(trjA, trjB, times=[0.0])

Evaluate the average distance between two trajectories (in pixels) across different times.

Parameters:

trjATrajectory

The first Trajectory to evaluate.

trjBTrajectory

The second Trajectory to evaluate.

timeslist or numpy.ndarray

The zero-shifted times at which to evaluate the matches (in days). The average of the distances at these times are used.

Returns:

ave_distfloat

The average distance in pixels.

kbmod.trajectory_utils.evaluate_trajectory_mse(trj, x_vals, y_vals, zeroed_times, centered=True)

Evaluate the mean squared error for the trajectory’s predictions.

Parameters:

trjTrajectory

The trajectory object to evaluate.

x_valsnumpy.ndarray

The observed x pixel values.

y_valsnumpy.ndarray

The observed y pixel values.

zeroed_timesnumpy.ndarray

The times of each observed point aligned with the start time of the trajectory (in days).

centeredbool

Shift the center to start on a half pixel. Setting to True matches how KBMOD does the predictions during the search: x = vx * t + x0 + 0.5. Default: True

Returns:

msefloat

The mean squared error.

kbmod.trajectory_utils.find_closest_trajectory(query, trj_list, times=[0.0])

For a given trajectory (query) find the closest trajectory in a list.

Parameters:

queryTrajectory

The query trajectory.

trj_listlist

The list of trajectories to search.

timeslist

The list of zero-shifted times at which to evaluate the matches. The average of the distances at these times are used.

Returns:

result_idxint

The index of the closest matching trajectory.

result_distfloat

The average distance at the time steps.

kbmod.trajectory_utils.find_closest_velocity(query, trj_list)

For a given trajectory (query) find the trajectory with the closest velocity in the list.

Parameters:

queryTrajectory

The query trajectory.

trj_listlist

The list of trajectories to search.

Returns:

result_idxint

The index of the closest matching trajectory.

kbmod.trajectory_utils.fit_trajectory_from_pixels(x_vals, y_vals, times, centered=True)

Fit a linear trajectory from individual pixel values. This is not a pure best-fit because we restrict the starting pixels to be integers.

Parameters:

x_valsnumpy.ndarray

The x pixel values.

y_valsnumpy.ndarray

The y pixel values.

timesnumpy.ndarray

The times of each point in zeroed days (such that first first time is zero).

centeredbool

Shift the center to start on a half pixel. Setting to True matches how KBMOD does the predictions during the search: x = vx * t + x0 + 0.5. Default: True

Returns:

trjTrajectory

The trajectory object that best fits the observations of this fake.

kbmod.trajectory_utils.make_trajectory_from_ra_dec(ra, dec, v_ra, v_dec, wcs)

Create a trajectory object from (RA, dec) information.

Parameters:

rafloat

The right ascension at time t0 (in degrees)

decfloat

The declination at time t0 (in degrees)

v_rafloat

The velocity in RA at t0 (in degrees/day)

v_decfloat

The velocity in declination at t0 (in degrees/day)

wcsastropy.wcs.WCS

The WCS for the images.

.. note::

The motion is approximated as linear and will be approximately correct only for small temporal range and spatial region.

Returns:

trjTrajectory

The resulting Trajectory object.

kbmod.trajectory_utils.match_trajectory_sets(traj_query, traj_base, threshold, times=[0.0])

Find the best matching pairs of queries (smallest distance) between the query trajectories and base trajectories such that each trajectory is used in at most one pair.

Parameters:

traj_querylist

A list of trajectories to compare.

traj_baselist

The second list of trajectories to compare.

thresholdfloat

The distance threshold between two trajectories to count a match (in pixels).

timeslist

The list of zero-shifted times at which to evaluate the matches. The average of the distances at these times are used.

Returns:

resultslist

A list the same length as traj_query where each entry i indicates the index of the trajectory in traj_base that best matches trajectory traj_query[i] or -1 if no match was found with a distance below the given threshold.

Notes

This function is designed to evaluate the performance of searches by determining which true trajectories (traj_query) were found in the result set (traj_base).

kbmod.trajectory_utils.predict_pixel_locations(times, x0, vx, centered=True, as_int=True)

A vectorized Python implementation of the logic to predict the pixel locations from a starting pixel and a velocity.

Parameters:

timeslist-like

The length T list of zero-shifted times.

x0list-like

The length R list of starting pixel locations.

vxlist-like

The length R list of pixel velocities (in pixels per day) for each trajectory.

centeredbool

Shift the prediction to be at the center of the pixel (e.g. xp = x0 + vx * time + 0.5f). Default = True.

as_intbool

Return the predictions as integers. Default = True.

Returns:

posnumpy.ndarray

A R x T matrix where R is the number of trajectories (length of x0 and vx) and T is the number of times.

kbmod.trajectory_utils.trajectories_to_dict(trj_list)

Create a dictionary of trajectory related information from a list of Trajectory objects.

Parameters:

trj_listlist

The list of Trajectory objects.

Returns:

trj_dictTrajectory

The corresponding trajectory object.

kbmod.trajectory_utils.trajectory_from_dict(trj_dict)

Create a trajectory from a dictionary of the parameters.

Parameters:

trj_dictdict

The dictionary of parameters.

Returns:

trjTrajectory

The corresponding trajectory object.

kbmod.trajectory_utils.trajectory_from_np_object(result)

Transform a numpy object holding trajectory information into a trajectory object.

Parameters:

resultnp object

The result object loaded by numpy.

Returns:

trjTrajectory

The corresponding trajectory object.

kbmod.trajectory_utils.trajectory_predict_skypos(trj, wcs, times)

Predict the (RA, dec) locations of the trajectory at different times.

Parameters:

trjTrajectory

The corresponding trajectory object.

wcsastropy.wcs.WCS

The WCS for the images.

timeslist or numpy.ndarray

The times at which to predict the positions in MJD.

.. note::

The motion is approximated as linear and will be approximately correct only for small temporal range and spatial region. In essence, the new coordinates are calculated as: :math: x_new = x_old + v * (t_new - t_old)

Returns:

resultastropy.coordinates.SkyCoord

A SkyCoord with the transformed locations.