socca.models.misc

Additional model components.

class socca.models.misc.Point(**kwargs)

Bases: Component

Point source model for unresolved sources.

Models point sources (stars, quasars, unresolved AGN) that are handled efficiently in Fourier space. The source is convolved with the PSF to produce the observed image.

Parameters:

**kwargs (dict) –

Keyword arguments including:

xcfloat, optional

Right ascension in degrees.

ycfloat, optional

Declination in degrees.

Icfloat, optional

Integrated flux or peak brightness (same units as image).

positivebool, optional

Whether to enforce positivity constraint.

Variables:

• xc (float) – Source right ascension (deg).

• yc (float) – Source declination (deg).

• Ic (float) – Source intensity.

Notes

Point sources are special-cased in the model evaluation:

• Handled in Fourier space using phase shifts

• Always PSF-convolved (not meaningful without PSF)

• More efficient than evaluating a very narrow Gaussian

• Can account for instrumental response at the source position

__init__(**kwargs)

Initialize a point source component.

Parameters:

**kwargs (dict) – Keyword arguments including xc, yc, Ic, positive.

static profile(xc, yc, Ic)

Point source profile placeholder (not used).

Point sources are handled specially in Fourier space and do not use a standard radial profile function.

Parameters:

• xc (float) – Right ascension (deg).

• yc (float) – Declination (deg).

• Ic (float) – Source intensity.

Notes

This method is a placeholder to maintain API consistency. Point sources are actually evaluated in getmap() using Fourier space phase shifts.

static getgrid()

Point source grid placeholder (not used).

Point sources do not use a spatial grid; they are handled in Fourier space.

Notes

This method is a placeholder to maintain API consistency with other profile types that use getgrid() for coordinate transformations.

getmap(img, convolve=False)

Generate point source image via Fourier space phase shifts.

Creates a point source image by computing the appropriate phase shift in Fourier space and optionally convolving with the PSF.

Parameters:

• img (Image) – Image object containing FFT information and PSF.

• convolve (bool, optional) – If True, convolve with PSF. If False, return unconvolved point source (delta function on pixel grid). Default is False.

Returns:

Point source image on the image grid.

Return type:

ndarray

Raises:

ValueError – If any parameter is a prior distribution or set to None.

Warns:

UserWarning – If convolve=True but no PSF is defined.

Notes

The point source is created using the Fourier shift theorem:

• The source is placed at (xc, yc) via phase shifts

• Multiplication by PSF in Fourier space performs convolution

• More efficient than spatial convolution for point sources

• The ‘pulse’ factor accounts for Fourier normalization

For point sources, PSF convolution is typically essential since an unconvolved point source is a delta function (single bright pixel).

Examples

>>> from socca.models import Point
>>> from socca.data import Image
>>> point = Point(xc=180.5, yc=45.2, Ic=1000.0)
>>> img = Image('observation.fits')
>>> psf_convolved = point.getmap(img, convolve=True)

class socca.models.misc.Background(**kwargs)

Bases: Component

Polynomial background model for large-scale gradients.

Models smooth background variations using a 2D polynomial up to 3rd order. Useful for fitting sky background, instrumental gradients, or scattered light.

Parameters:

**kwargs (dict) –

Keyword arguments including:

rsfloat, optional

Reference radius for normalizing polynomial terms (deg).

a0float, optional

Constant (0th order) term.

a1x, a1yfloat, optional

Linear (1st order) terms in x and y.

a2xx, a2xy, a2yyfloat, optional

Quadratic (2nd order) terms.

a3xxx, a3xxy, a3xyy, a3yyyfloat, optional

Cubic (3rd order) terms.

positivebool, optional

Whether to enforce positivity constraint.

Variables:

• rs (float) – Reference radius for polynomial normalization (deg).

• a3yyy (a0, a1x, a1y, a2xx, a2xy, a2yy, a3xxx, a3xxy, a3xyy,) – Polynomial coefficients up to 3rd order.

Notes

The background is defined as:

B(x,y) = a0 + a1x·x’ + a1y·y’

• a2xx·x’^2 + a2xy·x’·y’ + a2yy·y’^2

• a3xxx·x’^3 + a3xxy·x’^2·y’ + a3xyy·x’·y’^2 + a3yyy·y’^3

where x’ = x/rs and y’ = y/rs are normalized coordinates.

• Coordinates are relative to the field center (CRVAL1, CRVAL2)

• x coordinate includes cos(dec) correction for spherical geometry

• Background is not PSF-convolved (assumed to vary on large scales)

• Typically use low-order terms (0th and 1st) to avoid overfitting

__init__(**kwargs)

Initialize a polynomial background component.

Parameters:

**kwargs (dict) – Keyword arguments including rs and polynomial coefficients a0, a1x, etc.

static profile(x, y, a0, a1x, a1y, a2xx, a2xy, a2yy, a3xxx, a3xxy, a3xyy, a3yyy, rs)

Evaluate 2D polynomial background on coordinate grids.

Parameters:

• x (ndarray) – Coordinate grids in degrees (relative to field center).

• y (ndarray) – Coordinate grids in degrees (relative to field center).

• a0 (float) – Constant term.

• a1x (float) – Linear coefficients.

• a1y (float) – Linear coefficients.

• a2xx (float) – Quadratic coefficients.

• a2xy (float) – Quadratic coefficients.

• a2yy (float) – Quadratic coefficients.

• a3xxx (float) – Cubic coefficients.

• a3xxy (float) – Cubic coefficients.

• a3xyy (float) – Cubic coefficients.

• a3yyy (float) – Cubic coefficients.

• rs (float) – Reference radius for normalization (deg).

Returns:

Background values on the coordinate grid.

Return type:

ndarray

Notes

Evaluates the polynomial:

B = a0 + a1x·x’ + a1y·y’ + a2xx·x’^2 + a2xy·x’·y’ + a2yy·y’^2

• a3xxx·x’^3 + a3xxy·x’^2·y’ + a3xyy·x’·y’^2 + a3yyy·y’^3

where x’ = x/rs and y’ = y/rs.

The normalization by rs keeps coefficients of different orders at comparable scales and improves numerical conditioning.

static getgrid(grid, xc, yc)

Compute relative coordinates for background evaluation.

Converts absolute celestial coordinates to coordinates relative to the field center, with spherical geometry correction.

Parameters:

• grid (Grid) – Grid object with .x and .y coordinate arrays (deg).

• xc (float) – Reference RA (field center) in degrees.

• yc (float) – Reference Dec (field center) in degrees.

Returns:

• xgrid (ndarray) – RA offsets in degrees (with cos(dec) correction).

• ygrid (ndarray) – Dec offsets in degrees.

Notes

The RA offset includes a cos(dec) factor to account for spherical geometry, ensuring that distances are approximately correct on the sky.

getmap(img, **kwargs)

Generate background map on the image grid.

Evaluates the polynomial background across the entire image field.

Parameters:

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

• **kwargs (dict) – Ignored keyword arguments (for API compatibility).

Returns:

Background map on the image grid.

Return type:

ndarray

Raises:

ValueError – If any parameter is a prior distribution or set to None.

Warns:

UserWarning – If ‘convolve’ argument is provided (background is never convolved).

Notes

• Background is evaluated relative to field center (CRVAL1, CRVAL2)

• Background is not PSF-convolved (assumed to vary smoothly)

• All polynomial coefficients must have fixed values

Examples

>>> from socca.models import Background
>>> from socca.data import Image
>>> bkg = Background(a0=10.0, a1x=0.1, a1y=-0.05, rs=1.0)
>>> img = Image('observation.fits')
>>> bkg_map = bkg.getmap(img)