def get_ap_vel(df, time_step, scaling_factor): # Calculates 'angular persistence', 'velocity', and 'directed velocity'
    """
    Primary function called by "get_chemotaxis_stats" and
    "get_chemotaxis_stats_by_interval". Calculates the 'Angular_persistence', 'Velocity',
    and 'Directed_velocity' for each timepoint of each unique cell.

    Parameters
    ----------
    df: DataFrame
        Typically supplied by the calling function. Must include columns labeled 'Time',
        'Experiment_number', 'Cell_line', 'Cell_number', 'x', and 'y'. 'Time',
        'Experiment_number', and 'Cell_number', must be series of integers; 'Cell_line'
        must be a series of strings; 'x' and 'y' must be series of floats. IMPORTANT:
        Ensure that 'x' and 'y' are in units of pixels.

    time_step: integer
        Typically supplied by the calling function. This value specifies the duration of
        the interval between each timepoint for a cell track.

    scaling_factor: float
        Typically supplied by the calling function. Factor for conversion of 'x' and 'y'
        series of 'df' from pixels to real units of length. IMPORTANT: If designing a
        pipeline with other functions in this toolbox, ensure that the same real units of
        length are used in all cases (e.g., everything is coverted to microns).

    Returns
    -------
    output: DataFrame
        This DataFrame contains all the original columns with the further addition of
        'Velocity', 'Angular_persistence', and 'Directed_velocity' columns.

    """
    diff_df = df[['x', 'y', 'x_from_center', 'y_from_center']].diff()
    dot_product = df['x_from_center'] * diff_df['x_from_center'] + df['y_from_center'] * diff_df['y_from_center']
    magnitude = (df['x_from_center']**2 + df['y_from_center']**2)**0.5 * (diff_df['x_from_center']**2 + diff_df['y_from_center']**2)**0.5
    df['Angular_persistence'] = dot_product / magnitude * -1
    df['Velocity'] = (diff_df['x']**2 + diff_df['y']**2)**0.5 * scaling_factor / time_step
    df['Directed_velocity'] = df['Velocity'] * df['Angular_persistence']
    return df