Hebog

Hebog is a scalable source finder for radio continuum images. It is experimental, and runs in a single process or on a Dask cluster. For each FITS image it:

1. estimates the background and noise;
2. detects compact and extended emission;
3. separates, fits and measures sources; and
4. publishes a source catalogue, a noise (RMS) image, a source mask and diagnostics.

How Hebog finds sources explains each step with diagrams.

Hebog aims to be a fast, scalable source finder that is easily integrated into next generation radio astronomy data processing pipelines such as Rapthor. It can also be used on its own from Python.

Status

• Experimental. Releases are 0.x and may change the API or output formats. Pin an exact version and read the release notes before upgrading.
• Not yet scientifically qualified. Hebog is compared against PyBDSF and Aegean on simulated images with known sources, but these checks are development evidence rather than qualification for survey use. See scientific status.
• Supported inputs: one FITS image in Jy/beam with ICRS or FK5 J2000 sky coordinates and at most 15,402 pixels on each side.

Current capability and release status lists the full input requirements and known limitations, and progress against goals summarises on one page where development stands against the project's telescope, Rapthor, science, performance, scalability and release goals.

Installation

Hebog is experimental: 0.x releases can change the API, the outputs and the measurements, so pin the exact version. Install it from PyPI into a Python 3.12 to 3.14 environment (releases before 0.22.0 are on GitHub only):

pip install hebog==0.22.0

Example

from pathlib import Path

from hebog import SourceFinderConfig, SourceFinderRequest, find_sources
from hebog.executors import SerialExecutor

request = SourceFinderRequest(
    image_path=Path("image.fits"),
    output_directory=Path("output"),
    run_id="example",
)
config = SourceFinderConfig(
    detection_threshold_sigma=5.0,
    island_threshold_sigma=3.0,
    minimum_island_pixels=7,
)
result = find_sources(request, config, SerialExecutor())
print(result.catalogue_path, result.source_count)

The output directory must not already exist; running the same request again returns the products already there. The source-finding tutorial explains the settings, the products and how to run on Dask.

Documentation

• FAQ for astronomers
• Find sources in a FITS image
• How Hebog finds sources
• Hebog and other source finders
• Catalogue, image and diagnostic outputs
• Interactive notebooks
• FAQ for developers and architects
• Architecture
• How Hebog distributes work
• Integrate Hebog into a pipeline
• API reference

Development

Install uv and just, then:

git clone https://github.com/gemmadanks/hebog.git
cd hebog
uv sync --all-groups
just check    # formatting, linting, type checks and fast tests
just --list   # all test, documentation and packaging commands

Contributions use Conventional Commits. AGENTS.md describes the project's working rules, test suites and review checklist.

Citation and licence

If Hebog contributes to your research, please cite it using CITATION.cff. Hebog is distributed under the BSD 3-Clause License.