Skip to main content

feature_computation.add_target_coordinates

feature_computation.add_target_coordinates(
    pid=None,
    one=None,
    channels=None,
    traj_dict=None,
)

Add target coordinates to channel information using trajectory data.

This function calculates the 3D target coordinates (x_target, y_target, z_target) for each channel based on the probe insertion trajectory. It supports two modes: retrieving trajectory data from the Alyx database using a probe ID, or using a direct trajectory dictionary. For a trajectory in the in-vivo Needles frame the function applies pitch correction and a coordinate system transformation to convert to the Allen coordinate system; a histology track is already in Allen coordinates and is used as is.

Args: pid (str, optional): Probe insertion ID. Required if using Alyx database mode (when one is provided). one (ONE, optional): ONE client instance. Required if using Alyx database mode (when pid is provided). channels (dict): Channel information dictionary containing at least ‘axial_um’ field. Should also contain ‘rawInd’ or ‘channel’ for channel indexing. traj_dict (dict, optional): Dictionary containing trajectory information with keys: - x, y, z: coordinates - depth, theta, phi: insertion parameters Required if not using Alyx database mode.

Returns: dict: Updated channels dictionary with added ‘x_target’, ‘y_target’, and ‘z_target’ fields containing the 3D coordinates for each channel.

Raises: ValueError: If neither (pid, one) nor traj_dict is provided, or if Alyx holds none of the usable provenances in PROVENANCE_PREFERENCE for the given pid.

Example: >>> from one.api import ONE >>> one = ONE() >>> channels = {‘axial_um’: np.arange(384) * 20} >>> updated_channels = add_target_coordinates( … pid=‘probe00’, one=one, channels=channels … )

Note: - For a Needles-frame trajectory, the function applies a -5 degree pitch correction to account for probe tilt, then transforms the coordinates from in-vivo to the Allen coordinate system. - If channels don’t have ‘rawInd’ or ‘channel’ fields, it picks the number of channels from the axial_um field. - The function interpolates coordinates along the probe track for each channel. - For Alyx database mode, trajectories are picked following PROVENANCE_PREFERENCE: micro-manipulator, else planned, else histology track. Insertions with none of the three raise rather than returning coordinates from an unrelated trajectory. - Planned and micro-manipulator trajectories are stored in the Needles (in-vivo) frame, histology tracks in the Allen frame, and each is read in its own frame. A traj_dict passed by the caller carries no provenance and is treated as a Needles one.