socca.models

socca.models.zoo()[source]

Print available model profiles in the socca library.

This function displays a list of all available profile models that can be used for fitting astronomical images, including various analytical profiles for galaxies, point sources, and background components.

Notes

Available models include:

  • Beta: Beta profile (power-law density)

  • gNFW: Generalized Navarro-Frenk-White profile

  • Power: Power-law profile

  • TopHat: Uniform top-hat profile

  • Sersic: Sersic profile for elliptical galaxies

  • Gaussian: Gaussian profile

  • Exponential: Exponential disk profile

  • PolyExponential: Polynomial-exponential profile

  • PolyExpoRefact: Refactored polynomial-exponential profile

  • ModExponential: Modified exponential profile

  • Point: Point source model

  • Background: Polynomial background model

  • Disk: 3D disk model with finite thickness

Examples

>>> import socca.models as models
>>> models.zoo()
Beta
gNFW
Power
TopHat
Sersic
Gaussian
Exponential
PolyExponential
PolyExpoRefact
ModExponential
Point
Background
Disk
class socca.models.Model(prof=None, positive=None)[source]

Bases: object

Composite model container for combining multiple profile components.

The Model class provides a flexible framework for constructing complex astronomical models by combining individual profile components (Beta, Sersic, Point, etc.). It manages parameter priors, positivity constraints, and model evaluation.

__init__(prof=None, positive=None)[source]

Initialize a composite model with optional initial profile component.

Parameters:

  • prof (Profile or Component, optional) – Initial profile component to add to the model. Can be any profile instance (Beta, Sersic, Point, etc.). If None, creates an empty model to which components can be added later.

  • positive (bool, optional) – Whether to enforce positivity constraint on the profile. If None, uses the default positivity setting from the profile itself.

Variables:

  • ncomp (int) – Number of components in the model.

  • priors (dict) – Dictionary mapping parameter names to their values or prior distributions.

  • params (list of str) – List of all parameter names in the model.

  • paridx (list of int) – Indices of parameters with prior distributions (free parameters).

  • positive (list of bool) – Positivity constraints for each component.

  • tied (list of bool) – Indicates which parameters are tied to other parameters.

  • type (list of str) – Class names of each component in the model.

  • units (dict) – Dictionary mapping parameter names to their physical units.

Examples

>>> from socca.models import Model, Beta
>>> # Create empty model and add component later
>>> model = Model()
>>> model.addcomponent(Beta())
>>> # Or initialize with a profile directly
>>> model = Model(Beta())
addcomponent(prof, positive=None)[source]

Add a profile component to the composite model.

This method incorporates a new profile component into the model, handling parameter registration, prior assignments, and constraint management. Components are indexed sequentially and their parameters are prefixed with the component index.

Parameters:

  • prof (Profile or Component) – Profile component to add (e.g., Beta, Sersic, Point, Background, Disk).

  • positive (bool, optional) – Override the default positivity constraint for this component. If None, uses the component’s default positivity setting.

Raises:

ValueError – If any parameter in the profile is set to None without a valid value or prior distribution.

Notes

  • Parameters are stored with names like ‘comp_00_xc’, ‘comp_01_rc’, etc.

  • Parameters can be fixed values, prior distributions, or tied (functions).

  • Only parameters with prior distributions are considered free parameters during fitting.

  • Tied parameters are evaluated as functions of other parameters.

Examples

>>> from socca.models import Model, Beta, Point
>>> model = Model()
>>> # Add a Beta profile
>>> model.addcomponent(Beta(xc=180.5, yc=45.2, rc=0.01))
>>> # Add a point source
>>> model.addcomponent(Point(xc=180.6, yc=45.3), positive=True)
>>> print(model.ncomp)
2
parameters(freeonly=False)[source]

Print a formatted table of model parameters with their values and units.

This method displays all model parameters, showing fixed values, prior distributions, or tied parameter relationships in a human-readable format.

Parameters:

freeonly (bool, optional) – If True, only display parameters with prior distributions (free parameters to be fitted). If False (default), display all parameters including fixed values and tied parameters.

Notes

Parameter values are displayed as:

  • Fixed values: shown in scientific notation (e.g., 1.5000E-02)

  • Prior distributions: shown as “Distribution: DistributionName”

  • Tied parameters: shown as “Tied parameter”

The output format is: parameter_name [units] : value

Examples

>>> from socca.models import Model, Beta
>>> import numpyro.distributions as dist
>>> model = Model(Beta(xc=dist.Uniform(180, 181), yc=45.2, rc=0.01))
>>> model.parameters()
Model parameters
================
comp_00_xc   [deg]   : Distribution: Uniform
comp_00_yc   [deg]   : 4.5200E+01
comp_00_rc   [deg]   : 1.0000E-02
...
>>> model.parameters(freeonly=True)
Model parameters
================
comp_00_xc   [deg]   : Distribution: Uniform
getmap(img, convolve=None, addbackground=False)[source]

Generate a model image map using fixed parameter values only.

This method evaluates the model on the provided image grid using only fixed parameter values. All parameters must be fixed; parameters with prior distributions will raise an error.

Parameters:

  • img (Image) – Image object containing the grid, PSF, and WCS information.

  • convolve (bool, optional) – If True, return the PSF-convolved model. If False (default), return the unconvolved model. If None, defaults to False.

  • addbackground (bool, optional) – If True and convolve is True, include the background component in the output. If False (default), exclude background. Note that background is only added to convolved maps.

Returns:

Model image map on the same grid as img.data. Shape matches img.data.shape.

Return type:

ndarray

Raises:

ValueError – If any parameter has a prior distribution instead of a fixed value.

Warns:

UserWarning – If addbackground=True but convolve=False, warns that background is only added to convolved maps.

Notes

  • All model parameters must be fixed values (float or int).

  • Tied parameters are automatically evaluated from their dependencies.

  • For use during fitting with sampled parameters, use getmodel() instead.

Examples

>>> from socca.models import Model, Beta
>>> from socca.data import Image
>>> model = Model(Beta(xc=180.5, yc=45.2, rc=0.01, Ic=100, beta=0.5))
>>> img = Image('observation.fits')
>>> # Get unconvolved model
>>> model_map = model.getmap(img)
>>> # Get PSF-convolved model
>>> convolved_map = model.getmap(img, convolve=True)
getmodel(img, pp, doresp=False, doexp=False, component=None)[source]

Compute the full model image with PSF convolution, response, and exposure.

This is the main forward modeling function used during fitting. It evaluates all model components, applies PSF convolution, instrumental response, and exposure corrections as specified.

Parameters:

  • img (Image) – Image object containing data, grid, PSF, response map, and exposure map.

  • pp (array_like or dict) – Parameter values. If array_like, contains values for parameters with prior distributions, in the order they appear in paridx. If dict, contains all parameter values with keys matching self.params.

  • doresp (bool, optional) – If True, multiply by the instrumental response map (img.response). Default is False.

  • doexp (bool, optional) – If True, multiply by the exposure map (img.exposure). Default is False.

  • component (None, str, int, list, or Profile, optional) –

    Component(s) to include in the model computation. Can be:

    • None: Include all components (default)

    • str: Single component name (e.g., ‘comp_00’)

    • int: Component index (e.g., 0 for first component)

    • list: Multiple components as names, indices, or Profile objects

    • Profile: Object with id attribute specifying the component

    Default is None (all components).

Returns:

  • mraw (ndarray) – Unconvolved model image (raw surface brightness distribution).

  • msmo (ndarray) – Final model image after PSF convolution, response, and exposure corrections, including background.

  • mbkg (ndarray) – Background component only, with exposure applied if doexp=True.

  • mneg (ndarray) – Mask indicating pixels where model would be negative (if positivity constraints are violated). 1.0 where negative, 0.0 otherwise.

Notes

  • Fixed parameters are taken from self.priors

  • Free parameters are extracted from pp array

  • Tied parameters are computed from their functional dependencies

  • Point sources are handled in Fourier space for efficiency

  • Background components are not PSF-convolved

  • Disk components use 3D line-of-sight integration

  • The positivity mask (mneg) can be used to penalize negative values

Examples

>>> from socca.models import Model, Beta
>>> import numpyro.distributions as dist
>>> model = Model(Beta(xc=dist.Uniform(180, 181), yc=45.2))
>>> img = Image('observation.fits')
>>> # During fitting, pp contains sampled parameter values
>>> pp = [180.5]  # value for xc
>>> mraw, msmo, mbkg, mneg = model.getmodel(img, pp, doresp=True, doexp=True)