Fit a model to photometric data

In broad band observations of astrophysical sources, the total flux is given by the convolution of the radiation coming from the source with the response of the instrument. GalaPy objects of type galapy.Galaxy.PhotoGXY can model this kind of measurements, when the transmission model of the different observational bands is provided to the class.

Fitting through the command line

Tip

To fit an entire catalogue of sources, or to compare multiple physical models across a sample, use the --catalogue/-cat flag when generating the parameter file. See Multi-source catalogue fitting for a full description.

Sampling the parameter space can be done from the command line in a terminal. This will require to compile a templated parameter file that can be generated by calling

$ galapy-genparams [--name/-n NAME] [--SFH_model/-sfh SFH_MODEL] [--catalogue/-cat]

Where the argument NAME can include any path in the filesystem. Since the generated parameter file has python syntax, we automatically append a .py extension to the custom file name. If no argument is passed the parameter file will be generated in the current directory:

$ ls
galapy_hyper_parameters.py

The generated file should be self-explanatory and has to be modified according to the fit the user has to perform.

Tip

The parameter file, for obvious reasons, needs at least to import the observational photometric dataset for running a parameter space sampling. Without this fundamental step, the program will crash as it does not know against what to compare the generated models.

For testing the correct installation of the library, follow these 3 steps:

Generate a parameter file with a SFH model of choice:
```
$ galapy-genparams -sfh insitu
```
open the generated parameter file with a text editor (e.g. $ emacs galapy_hyper_parameters.py) and modify the first 4 parameters with the following minimal set-up:
```
bands  = ['GOODS.b']
fluxes = [1.0]
errors = [1.0]
uplims = [0]
```
save and close the file.
By running the following command, the parameter-space sampling procedure will start using the Emcee sampler:
```
$ galapy-fit galapy_hyper_parameters.py
```

There are 4 main blocks in the parameter file:

Import the observational data: where the user should load its observational data as well as define the photometric system;
Define the physics of the galaxy model: define what SFH model and what SSP library to use, turn on/off components of the spectrum (i.e. radio support, x-ray support, AGN templates);
Choose the fixed and free parameters (as well as their priors): each parameter of the model that will not be listed here will be set to its default value, otherwise, the user can here modify default values and choose what parameters to keep free;
Sampling and output format choices: decide which sampler to use and define the sampling hyperparameters (the default parameters should work most of the times), decide what and where to output.

Tip

Keep in mind that the parameter file can be considered as a python module and, therefore, all operations that can be done in python are available within this file. It is, e.g., possible to import python packages that could be useful to manipulate the datasets or load them from system. It is also possible to run functions and define classes or whatever else the user might find useful for setting up properly their run. Some packages we always find useful to import at the beginning of the parameter file are

import numpy as np
import os, sys

Once the parameter file has been generated and properly modified, we can run

$ galapy-fit parameter_file.py [--serial/-s | --multiprocessing/-mp NCPU]

which will run the sampling and authomatically store the results, as specified by the user in the parameter file. NOTE THAT the two optional arguments regulate whether to run the sampling serially or using shared-memory parallelism. The default behaviour is to run parallely on all the available CPUs.

A thorough description of all the hyper-parameters that can be addressed when preparing the parameter file is provided in Build and modify the parameter file page.

Multi-source catalogue fitting

When observations are available for a sample of sources, GalaPy can process all of them in a single run using a catalogue parameter file. The same mechanism also supports running K different physical models on every source simultaneously, making it straightforward to carry out systematic model comparisons across an entire catalogue in one submission.

A catalogue parameter file is generated by passing the --catalogue (or -cat) flag to galapy-genparams:

$ galapy-genparams --catalogue [--name/-n NAME] [--SFH_model/-sfh SFH_MODEL]

The file mirrors the single-source file in overall structure; the blocks Define the physics of the galaxy model, Choose the fixed and free parameters, and Sampling and output format choices are identical and define the shared configuration applied to every source. Only the observational data block and two catalogue-specific additions differ; a full description is provided in Catalogue parameter file. In brief:

fluxes, errors, and uplims become 2-D array-likes of shape (N, M), where N is the number of sources and M the number of photometric bands.
An optional models list of K dictionaries enables testing different physical configurations on every source (e.g. different SFH topologies, AGN on/off). GalaPy launches N x K independent fits, distributing work across CPUs exactly as for a single-source multi-processing run. When models is absent or empty, a single shared model is applied to all sources.
run_id is a list of N strings providing a filename prefix for each source (auto-labelled obj0, obj1, … when left empty). When K > 1 model variants are specified, an auto-generated suffix encoding the varying keys is appended to distinguish outputs, e.g. obj0_AGNFalse, obj0_AGNTrue.

Once the catalogue parameter file has been prepared, it is submitted to galapy-fit with the same syntax as a single-source run:

$ galapy-fit catalogue_parameter_file.py [--serial/-s | --multiprocessing/-mp NCPU]

GalaPy detects catalogue mode automatically from the contents of the parameter file.

Note

Each (source, variant) pair produces its own independent results file, identical in format to a standard single-source output. Post-processing and analysis are therefore unchanged: use the existing tools in galapy.analysis on each file individually, source by source and model by model.

Fitting through the Python API

Coming soon.