crossmatch_nested

crossmatch_nested#

Catalog.crossmatch_nested(other: Catalog, *, n_neighbors: int | None = None, radius_arcsec: float | None = None, min_radius_arcsec: float | None = None, algorithm: AbstractCrossmatchAlgorithm | None = None, output_catalog_name: str | None = None, require_right_margin: bool = False, nested_column_name: str | None = None) → Catalog[source]#

Perform a cross-match between two catalogs, adding the result as a nested column

For each row in the left catalog, the cross-matched rows from the right catalog are added in a new nested column. Any extra columns from the crossmatch like distance are added to this nested column too.

The pixels from each catalog are aligned via a PixelAlignment, and cross-matching is performed on each pair of overlapping pixels. The resulting catalog will have partitions matching an inner pixel alignment - using pixels that have overlap in both input catalogs and taking the smallest of any overlapping pixels.

The resulting catalog will be partitioned using the left catalog’s ra and dec, and the index for each row will be the same as the index from the corresponding row in the left catalog’s index.

Parameters:

otherCatalog

The right catalog to cross-match against

n_neighborsint, default 1

The number of neighbors to find within each point.

radius_arcsecfloat, default 1.0

The threshold distance in arcseconds beyond which neighbors are not added.

min_radius_arcsecfloat, default 0.0

The threshold distance in arcseconds beyond which neighbors are added.

algorithmAbstractCrossmatchAlgorithm | None, default KDTreeCrossmatch

The instance of an algorithm used to perform the crossmatch. If None, the default KDTree crossmatch algorithm is used. If specified, the algorithm is defined by subclassing AbstractCrossmatchAlgorithm.

Default algorithm:

KdTreeCrossmatch: find the k-nearest neighbors using a kd_tree

Custom algorithm:

To specify a custom algorithm, write a class that subclasses the AbstractCrossmatchAlgorithm class, and either overwrite the crossmatch or the perform_crossmatch function.

The function should be able to perform a crossmatch on two pandas DataFrames from a partition from each catalog. It should return two 1d numpy arrays of equal lengths with the indices of the matching rows from the left and right dataframes, and a dataframe with any extra columns generated by the crossmatch algorithm, also with the same length. These columns are specified in {AbstractCrossmatchAlgorithm.extra_columns}, with their respective data types, by means of an empty pandas dataframe. As an example, the KdTreeCrossmatch algorithm outputs a “_dist_arcsec” column with the distance between data points. Its extra_columns attribute is specified as follows:

pd.DataFrame({"_dist_arcsec": pd.Series(dtype=np.dtype("float64"))})

The crossmatch/perform_crossmatch methods will receive an instance of CrossmatchArgs which includes the partitions and respective pixel information:

- left_df: npd.NestedFrame
- right_df: npd.NestedFrame
- left_order: int
- left_pixel: int
- right_order: int
- right_pixel: int
- left_catalog_info: hc.catalog.TableProperties
- right_catalog_info: hc.catalog.TableProperties
- right_margin_catalog_info: hc.catalog.TableProperties

Include any algorithm-specific parameters in the initialization of your object. These parameters should be validated in AbstractCrossmatchAlgorithm.validate, by overwriting the method.

output_catalog_namestr, default {left_name}_x_{right_name}

The name of the resulting catalog.

require_right_marginbool, default False

If true, raises an error if the right margin is missing which could lead to incomplete crossmatches.

nested_column_namestr, default uses the name of the right catalog

The name of the nested column that will contain the crossmatched rows from the right catalog.

Returns:

Catalog: A Catalog with the data from the left and right catalogs joined with the cross-matched rows from the right catalog added in a new nested column. The resulting table contains all columns from the left catalog and a new nested column with all the columns from the right catalog and any extra columns generated by the crossmatch algorithm.

Raises:

ValueError: If both the kwargs for the default algorithm and an algorithm are specified. If the right catalog has no margin and require_right_margin is True.

crossmatch_nested

Contents

crossmatch_nested#