spherimatch

A Python package for cross-matching and self-matching in spherical coordinates.

Table of Contents

• Introduction
• Features
• Installation
• Example Usage
• API Reference
• Contributing
• Citation

Introduction

spherimatch is a Python package designed to perform cross-matching and self-matching in spherical coordinates. This is particularly useful in fields such as astrophysics, geophysics, and any domain where objects are naturally distributed on a spherical surface. Currently, this package only support astrophysics coordinates (Ra, Dec) in degrees. More units and naming convention will be supported in the future.

Features

• Efficient computation ( $O(N\log N)$ ) of matching problems in spherical coordinates.
• Friends-of-Friends (FoF) analysis in spherical coordinates.
• Duplicate removal in spherical coordinates.
• Easy integration with existing data processing packages, such as pandas.

Installation

Install spherimatch by:

pip install spherimatch

See the installation guide for more details.

Example Usage

Before you start, please check out our documentation for a quick start.

• To perform cross-matching between two catalogs, check this cross-matching example.
• To cluster the objects in a catalog with the Friends-of-Friends (FoF) algorithm, check this clustering example.
• To remove duplicates from a catalog, check this duplicate removal example.

API Reference

The API reference can be found in the full documentation.

Contributing

If you find any bugs or potential issues, please report it directly to me (via Slack or E-mail), or start an issue.

If you have any suggestions or feature requests, feel free to start an issue.

Citation

If you find spherimatch useful in your research, please consider citing it.

spherimatch is registered in the Astrophysics Source Code Library (ASCL), and can be cited using its Bibcode: 2025ascl.soft07022H.

Please feel free to use your preferred citation format. For convenience, here is a BibTeX entry:

@software{2025ascl.soft07022H,
       author = {{Hsu}, Yuan-Ming},
        title = "{spherimatch: Cross-matching and self-matching in spherical coordinates}",
 howpublished = {Astrophysics Source Code Library, record ascl:2507.022},
         year = 2025,
        month = jul,
          eid = {ascl:2507.022},
       adsurl = {https://ui.adsabs.harvard.edu/abs/2025ascl.soft07022H},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

You may also include a reference to the GitHub repository https://github.com/technic960183/spherimatch in the footnote if appropriate.

If you publish a paper that uses spherimatch, feel free to let me know. I would be happy to hear how this package supports your work!