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.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.trajectory_predict_skypos(trj, wcs, times, t0=None)

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.

t0float, optional

The epoch (in MJD) at which the trajectory’s starting pixel (trj.x, trj.y) is defined. Times are offset relative to this epoch. If None (the default) the first entry of times is used, which is only correct when times starts at the trajectory’s own epoch. Callers passing a subset of the stack’s obstimes (for example, only the valid observations of a result) must pass the stack’s first obstime here, otherwise every predicted position is displaced by |v| * (times[0] - t0).

.. 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.

kbmod.trajectory_utils.trajectory_results_best_match(traj_query, results, times=[0.0])

For each query trajectory find the best matching result in a Results table. This uses a greedy match so multiple queries can match the same result.

Parameters:

traj_querylist

A list of trajectories to compare.

resultsResults

The table of results with columns for x, y, vx, and vy.

timeslist

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

Returns:

best_distnp.ndarray

A list the same length as traj_query where each entry i indicates the MSE distance of the best matching result row.

best_matchnp.ndarray

A list the same length as traj_query where each entry i indicates the index of the best matching result row.