associate

trap.associate.de_ruiter_radius(*, p1_ra: ndarray, p1_dec: ndarray, p2_ra: ndarray, p2_dec: ndarray, p1_err_ns: ndarray, p1_err_ew: ndarray, p2_err_ns: ndarray, p2_err_ew: ndarray)[source]

Find the ‘de Ruiter radius’ of two points, which is a weighted distance that takes the positional uncertainties of both points into account.

This calculation is based on section 4.4.1 in the TraP paper[1].

The equation is:

\[r_{i,j} = \sqrt{ \frac{ ( \alpha_i - \alpha_j)^2 \cos^2( (\delta_i + \delta_j) / 2 ) }{ \sigma_{\alpha_i}^2 + \sigma_{\alpha_j}^2 } + \frac{ (\delta_i - \delta_j)^2 }{ \sigma_{\delta_i}^2 + \sigma_{\delta_j}^2 } }\]

Here the subscript i refers to a specific source and j refers to a potential new source. \(\alpha\) is the right ascension of the source and \(\delta\) the declination. \(\sigma_{\alpha}\) and \(\sigma_{\delta}\) refer to the uncertainty in right ascending and declination, respectively.

[1] Swinbank, John D., et al. “The LOFAR transients pipeline.” Astronomy and Computing 11 (2015): 25-48.

Parameters:

  • p1_ra (np.ndarray) – The right ascension of the first point

  • p1_dec (np.ndarray) – The declination of the first point

  • p2_ra (np.ndarray) – The right ascension of the second point

  • p2_dec (np.ndarray) – The declination of the second point

  • p1_err_ns (np.ndarray) – The uncertainty in the right ascension coordinate of the first point in degrees

  • p1_err_ew (np.ndarray) – The uncertainty in the declination coordinate of the first point in degrees

  • p2_err_ns (np.ndarray) – The uncertainty in the right ascension coordinate of the second point in degrees

  • p2_err_ew (np.ndarray) – The uncertainty in the declination coordinate of the second point in degrees

Returns:

The de Ruiter radius as defined in the TraP paper[1]

Return type:

np.ndarray

trap.associate.associate(sources: DataFrame, new_sources: DataFrame, de_ruiter_r_max: float = 5.68, surpress_duplications: bool = False) → Tuple[ndarray, ndarray, DataFrame, DataFrame][source]

Relates new sources with existing sources.

Start with a DataFrame that contains known sources and one that contains new sources. The new sources are then matched to the known sources. The sources can be obtained using trap.source_extraction.sources_from_fits_pyse().

Parameters:

  • sources (pd.DataFrame) –

    The list of know sources with at least the following columns:

    • ”id” (index of source)

    • ”ra” (right-ascension coordinate of source)

    • ”dec” (declination coordinate of source))

    • ”uncertainty_ns” (sqare root of quadratic sum of systematic error in north-south direction and the error_radius)

    • ”uncertainty_ew” (sqare root of quadratic sum of systematic error in east-west direction and the error_radius)

  • new_sources (pd.DataFrame) –

    The list of new sources with at least the following columns:

    • ”id” (index of source)

    • ”ra” (right-ascension coordinate of source)

    • ”dec” (declination coordinate of source))

    • ”uncertainty_ns” (square root of quadratic sum of the systematic error in north-south direction and error_radius)

    • ”uncertainty_ew” (square root of quadratic sum of the systematic error in east-west direction and error_radius)

  • de_ruiter_r_max (float) – If the de Ruiter radius is larger than this value for a given source pair, the sources are considered to be different sources. If the radius is smaller than de_ruiter_r_max, the sources are elligable to be considered the same source.

  • surpress_duplications (bool) – In the many-to-many case, prefer a connection to a source that is not connected yet over the nearest source if True. When False, always connect to the nearest source even if there are other, even closer, connections to that source already. False is the way both the vast pipeline and the original TraP operated and is the default here.

Returns:

  • null_detection_ids (the ids corresponding to new_sources.index that were not found in sources)

  • new_source_ids (the ids corresponding to sources.index that were in new_sources but not in the original sources)

  • persistings_mapping (pd.DataFrame:) – A dataframe containing the columns [original_id, new_id, de_ruiter] that map the indices from sources to new_sources of those that are identified as being a persistant source, meaning it is a source that occurs in both sourcse lists.

  • duplicate_mapping (A dataframe containing the columns [original_id, new_id, de_ruiter] that map the indices) – of any access sources in new_sources to the nearest source in the original sources DataFrame.