Ctrl+K

Getting Started

Getting Started#

Data Preparation#

Jolideco is a deconvolution package for any astronomical image affected by Poisson noise. It is not designed to work with any specific instrument, but rather a combination of instruments. However this also means Jolideco only operates on already reduced data, typically as FITS images.

So before you can run your first Jolideco analysis, for each observation you need to have the following data ready:

Quantity

Definition

counts

An image containing the binned events

psf

An image with a model of the point spread function (PSF)

exposure (optional)

An image containing the exposure, typically as product of the lifetime and effective area

background (optional)

An image of the instrumental background, typically as predicted counts

As Jolideco does no provide any data reduction functionality you have to reduce the data using the software provided by the observatory you got the data from. However to simplify the process for Fermi-LAT and Chandra you can use the following snakemake pipelines:

Both workflows will produce the required image files for Jolideco.

For TeV gamma-ray data reduction you can use Gammapy. Especially check out the Tutorial on image data reduction.

Usage#

Once you have prepared the data you can use Jolideco to deconvolve it.

This is how to use Jolideco:

import numpy as np
from jolideco import MAPDeconvolver
from jolideco.models import FluxComponent
from jolideco.data import point_source_gauss_psf

data = point_source_gauss_psf()
component = FluxComponent.from_numpy(
    flux=np.ones((32, 32))
)
deconvolve = MAPDeconvolver(n_epochs=1_000)
result = deconvolve.run(data=data, components=component)

The MAPDeconvolver is the main API of Jolideco. It runs the reconstruction algorithm and returns a MapDeconvolverResult object.

The main data types and classes are:

  • FluxComponents: a collection of flux components, they hold the model parameters.

  • NPPredCalibrations: a collection of calibration models, that hold the parameters for the calibratuion, including the background norm as well as positional shift per observation.

  • data: a list of dictionaries with the required data for each observation (see above)

From these quantities the predicted number of counts is computed like:

\[N_{Pred} = \mathrm{PSF} \circledast (\mathcal{E} \cdot (F + B))\]

Where \(\mathcal{E}\) is the exposure, \(F\) the deconvovled flux image, \(B\) the background and \(PSF\) the PSF image.

For more detailed analysis example check out the Tutorials.

Tips and Tricks#

Here is a list of tips and tricks that might help you to get started with Jolideco. They have been collected from the experience of the developers and users of Jolideco.

  • Start with a uniform prior for the flux and “overfit” to the data. Convergence should be really fast.

  • This image you can use as a starting point for the patch prior later.

  • The patch prior is normalized such that it is roughly equally informative as one observation.

  • If you only have few data (low statistics), beta should be chosen such that the prior is not too strong. Aim for a value that makes the prior around 20% of the likelihood.

  • You can check the prior strength by looking at MapDeconvolverResult.trace_loss

  • Start with the "gleam-v0.1" prior which is a good all purpose prior.

  • For bright sources you can work with an oversampled flux image. Typically a 2x2 oversampling is sufficient.

Contents