galsbi 0.3.0
Package to easily generate catalogs from the model
License: MIT License

# The (Great) GalSBI

[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/galsbi.svg)](https://pypi.python.org/pypi/galsbi/)
[![PyPI version](https://badge.fury.io/py/galsbi.svg)](https://badge.fury.io/py/galsbi)
[![pipeline](https://gitlab.com/cosmology-ethz/galsbi/badges/main/pipeline.svg)](https://gitlab.com/cosmology-ethz/galsbi/-/pipelines)
[![coverage](https://gitlab.com/cosmology-ethz/galsbi/badges/main/coverage.svg)](https://gitlab.com/cosmology-ethz/galsbi)
<a href="https://cosmo-docs.phys.ethz.ch/galsbi/htmlcov/index.html">
  <img src="https://img.shields.io/badge/coverage_report-green"
    alt="coverage report"/>
</a>

[![DOI](https://joss.theoj.org/papers/10.21105/joss.08766/status.svg)](https://doi.org/10.21105/joss.08766)
[![image](https://img.shields.io/badge/arXiv-2412.08701-B31B1B.svg?logo=arxiv&style=flat)](https://arxiv.org/abs/2412.08701)
[![image](https://img.shields.io/badge/arXiv-2412.08722-B31B1B.svg?logo=arxiv&style=flat)](https://arxiv.org/abs/2412.08722)
[![image](https://img.shields.io/badge/arXiv-2505.21610-B31B1B.svg?logo=arxiv&style=flat)](https://arxiv.org/abs/2505.21610)

[![Docs](https://badgen.net/badge/icon/Documentation?icon=https://cdn.jsdelivr.net/npm/simple-icons@v13/icons/gitbook.svg&label)](https://cosmo-docs.phys.ethz.ch/galsbi/)
[![Source Code](https://badgen.net/badge/icon/Source%20Code?icon=gitlab&label)](https://gitlab.com/cosmology-ethz/galsbi)

Create realistic galaxy catalogs and astronomical images based on the GalSBI model.
The GalSBI phenomenological model is described in [Fischbacher et al. (2024)](https://arxiv.org/abs/2412.08701), while
the stellar population synthesis-based model GalSBI-SPS in [Tortorelli et al. (2025)](https://arxiv.org/abs/2505.21610). The Python
package is described in [Fischbacher et al. (2024)](https://arxiv.org/abs/2412.08722).

## Motivation

Next-generation galaxy surveys will test cosmology with unprecedented precision.
To fully realize the potential of these surveys, forward modeling of galaxy populations
offers a promising path - enabling accurate redshift estimation, shape measurement
calibration, selection effect modeling, and deeper insights into galaxy properties.

GalSBI is a parametric galaxy population model constrained by observational data using
simulation-based inference (SBI).
The `galsbi` Python package provides a flexible framework for generating realistic
galaxy catalogs and rendering them into astronomical images via
[UFig](https://gitlab.com/cosmology-ethz/ufig).


## Installation

The package can be installed via pip:

```bash
pip install galsbi
```

or using uv:

```bash
uv pip install galsbi
```

## Usage

To generate a catalog of galaxies with their intrinsic properties from the phenomenological model,
you can use the following code snippet:

```python
from galsbi import GalSBI

model = GalSBI(name="Fischbacher+24") # define which model to use
model(mode="intrinsic") # generating catalogs with intrinsic galaxy properties
cats = model.load_catalogs() # load the generated catalogs

intrinsic_i_band_cat = cats["ucat galaxies i"]
```

To generate a catalog of galaxies with their intrinsic properties from the stellar population synthesis-based model
GalSBI-SPS, you can use the following code snippet:

```python
from galsbi import GalSBI

model = GalSBI("Tortorelli+25")
model(mode="intrinsic")
cats = model.load_catalogs()

intrinsic_i_band_cat = cats["ucat galaxies i"]
```

More examples and detailed documentation can be found in the [documentation](https://cosmo-docs.phys.ethz.ch/galsbi/).
**Note:** The first time you run `galsbi`, additional data files will be downloaded
automatically and cached locally. The initial run may also take longer due to
PyCosmo compilation. If you encounter any issues, see the
[FAQ](https://cosmo-docs.phys.ethz.ch/galsbi/faq.html#i-get-an-error-when-i-run-the-code-for-the-first-time-during-the-compilation-of-pycosmo-what-should-i-do).

Currently, the following models are available:

- `Fischbacher+24`: constrained in [Fischbacher et al. (2024)](https://arxiv.org/abs/2412.08701).
- `Tortorelli+25`: constrained in [Tortorelli et al. (2025)](https://arxiv.org/abs/2505.21610).
- `Moser+24`: constrained in [Moser et al. (2024)](https://arxiv.org/abs/2401.06846).

There are different modes available to generate catalogs:

- `intrinsic`: generates a catalog with intrinsic galaxy properties for HSC grizy bands.
- `emulator`: generates a catalog with intrinsic galaxy properties for HSC grizy bands
  and a catalog with measured galaxy properties for each band using an emulator trained
  on HSC deep fields.
- `image`: generates a catalog with intrinsic galaxy properties for HSC grizy bands
  and a simulated image for each band. The image has background noise and PSF size
  similar to HSC deep fields.
- `image+SE`: same as `image`, but also runs `SExtractor` on the images to generate
  catalogs with measured galaxy properties for each band.
- `config_file`: runs the model following a custom configuration file. The path to the configuration file can be passed as an argument `config_file`. The predefined configuration files can be found in the `src/galsbi/configs` directory and can be used as a starting point for custom configurations.

The loaded catalogs are stored in a dictionary with the following keys:
- `ucat galaxies <band>`: intrinsic galaxy catalog for the given band.
- `ucat stars <band>`: intrinsic star catalog for the given band.
- `sextractor <band>`: catalog with measured galaxy properties for the given band (if a measured catalog is generated)
- `sed`: catalog with SEDs of the galaxies (in case the SEDs are saved, see [Saving Galaxy Spectra](https://cosmo-docs.phys.ethz.ch/galsbi/spectra.html)).
- `restframe_wavelength_in_A`: the restframe wavelength in Angstroms for the SEDs (if the SEDs are saved).

By default, the catalogs are loaded as structured NumPy arrays. Setting `output_format` to `df` loads them as pandas DataFrames, while `output_format="fits"` loads them as FITS catalogs. An overview of the columns in the catalogs can be found in the [Catalog Column Descriptions](https://cosmo-docs.phys.ethz.ch/galsbi/column_description.html).

If an image is generated, one can also load the images, segmentation and background maps using
`model.load_images()`. This returns a dictionary with the following keys:
- `image <band>`: the simulated image for the given band.
- `segmentation <band>`: the segmentation map for the given band.
- `background <band>`: the background map for the given band.

More details on the usage of the package can be found in the [documentation](https://cosmo-docs.phys.ethz.ch/galsbi/).

## Citation

If you use GalSBI in your work, please cite the science papers [Fischbacher et al. (2024)](https://arxiv.org/abs/2412.08701), [Tortorelli et al. (2025)](https://arxiv.org/abs/2505.21610),
the `ProMage` magnitude emulator paper [Tortorelli et al. (2025b)](https://arxiv.org/abs/2509.00150), and the code release paper [Fischbacher et al. (2024)](https://arxiv.org/abs/2412.08722).
If you are using specific models or parametrizations, please also cite the corresponding papers.
If you are not sure which papers to cite, use the following with your model instance:

```python
model.cite()
```

## Credits

This package was developed by the Cosmology group at ETH Zurich and updated by the ACAI group at LMU Munich.
The package is currently maintained by
[Silvan Fischbacher](silvanf@phys.ethz.ch) and [Luca Tortorelli](luca.tortorelli@physik.lmu.de).

## Contributions

Contributions are welcome, and they are greatly appreciated! Every
little bit helps, and credit will always be given.

Please see the [Contributing to galsbi](https://cosmo-docs.phys.ethz.ch/galsbi/contributing.html)
documentation for more information on how to contribute.