API Reference

xmatch functionality

pycorrelator.xmatch(catalog1, catalog2, tolerance, verbose=True) → XMatchResult[source]

Performs a cross-match between two catalogs.

This function matches objects from two different catalogs based on their coordinates. Objects from catalog1 and catalog2 that are within a specified angular distance (tolerance) are considered matches.

Parameters:

  • catalog1 (array-like) – The first catalog.

  • catalog2 (array-like) – The second catalog.

  • tolerance (float) – The tolerance for the cross-match in degrees.

  • verbose (bool, optional) – Whether to print the progress.

Returns:

A XMatchResult object that contains the cross-match result.

Return type:

XMatchResult

class pycorrelator.XMatchResult(cat1: Catalog, cat2: Catalog, tolerance, result_dict: defaultdict)[source]
get_dataframe1(min_match=0, coord_columns=['Ra', 'Dec'], retain_all_columns=True, retain_columns=None) → DataFrame[source]

Get the first catalog with the number of matches as a pandas dataframe.

Parameters:

  • min_match (int, optional) – The minimum number of matches for an object to be included in the dataframe. Default is 0.

  • coord_columns (list[str], optional) – The names of the columns for the coordinates. Default is [‘Ra’, ‘Dec’].

  • retain_all_columns (bool, optional) – Whether to retain all the columns in the input (dataframe). Default is True.

  • retain_columns (list[str], optional) – The names of the columns to retain in the output dataframe. Will override retain_all_columns if not empty. Default is None.

Returns:

The dataframe of the first catalog with the number of matches.

Return type:

pandas.DataFrame

get_dataframe2(min_match=0, coord_columns=['Ra', 'Dec'], retain_all_columns=True, retain_columns=None) → DataFrame[source]

Get the second catalog with the number of matches as a pandas dataframe.

Please refer to the get_dataframe1() and replace the ‘first catalog’ with the ‘second catalog’.

get_result_dict() → defaultdict[source]
get_result_dict_reserve() → defaultdict[source]
get_serial_dataframe(min_match=1, reverse=False, coord_columns=['Ra', 'Dec'], retain_all_columns=True, retain_columns=None) → DataFrame[source]

Get a pandas dataframe with the information of the matching of the two catalogs in a serial manner.

Each object from the first catalog with sufficient matches (as defined by min_match) appear first, followed by their matched objects from the second catalog.

Parameters:

  • min_match (int, optional) – The minimum number of matches for an object from the first catalog to be included in the dataframe. Default is 1.

  • reverse (bool, optional) – Whether to reverse the order of catalogs (i.e., make the second catalog as the first and vice versa). Default is False.

  • coord_columns (list[str], optional) – The names of the columns for the coordinates. Default is [‘Ra’, ‘Dec’].

  • retain_all_columns (bool, optional) – Whether to retain all the columns in the input (dataframe). Default is True.

  • retain_columns (list[str], optional) – The names of the columns to retain in the output dataframe. Will override retain_all_columns if not empty. Default is None.

Returns:

The serial dataframe of the two catalogs with the number of matches.

Return type:

pandas.DataFrame

number_distribution() → Counter[source]

Get the distribution of the number of matches for each object in the first catalog.

Returns:

The distribution of the number of matches for each object in the first catalog.

Return type:

collections.Counter

fof functionality

pycorrelator.fof(catalog, tolerance) → FoFResult[source]

Perform the Friends-of-Friends (FoF) grouping algorithm on a catalog.

This function applies the FoF algorithm to a given catalog. The algorithm works by linking objects that are within a specified angular distance (tolerance) of each other, forming groups or clusters of objects.

Parameters:

  • catalog (array-like) – The catalog to group.

  • tolerance (float) – The tolerance for the grouping in degrees.

Returns:

The result of the Friends-of-Friends grouping.

Return type:

FoFResult

class pycorrelator.FoFResult(catalog: Catalog, tolerance: float, result_list: list)[source]
get_coordinates() → list[list[tuple]][source]

Returns the coordinates of objects grouped as lists of tuples.

Returns:

A list of lists of tuples of coordinates of objects in each group.

Return type:

list[list[tuple]]

get_group_coordinates() → list[tuple][source]

Returns the center coordinates of the groups.

Returns:

A list of tuples of coordinates of the center of each group.

Return type:

list[tuple]

get_group_dataframe(min_group_size=1, coord_columns=['Ra', 'Dec'], retain_all_columns=True, retain_columns=None) → DataFrame[source]

Get the grouped data as a two-level indexed pandas DataFrame.

Parameters:

  • min_group_size (int, optional) – The minimum group size to include in the DataFrame. Default is 1.

  • coord_columns (list[str], optional) – The names of the columns for the coordinates. Default is [‘Ra’, ‘Dec’].

  • retain_all_columns (bool, optional) – Whether to retain all the columns in the input (dataframe). Default is True.

  • retain_columns (list[str], optional) – The names of the columns to retain in the output dataframe. Will override retain_all_columns if not empty. Default is None.

Returns:

A two-level indexed pandas DataFrame containing the grouped data.

Return type:

pandas.DataFrame

get_group_sizes() → list[int][source]

Returns the object counts in each group.

Returns:

A list of integers representing the number of objects in each group.

Return type:

list[int]