SkyModel
========
SkyModel is the main user class for point source and diffuse models.
It provides import and export functionality to and from supported file
formats as well as methods for transforming the data (combining, selecting,
changing coordinate frames) and can be interacted with directly.

Attributes
----------
The attributes on SkyModel hold all of the metadata and data required to
work with radio sky models. Under the hood, the attributes are
implemented as properties based on :class:`pyuvdata.parameter.UVParameter`
objects but this is fairly transparent to users.

SkyModel objects can be initialized from a file using the
:meth:`pyradiosky.SkyModel.from_file` class method
(as ``sky = SkyModel.from_file(<filename>)``) or be initialized by passing
in all the information to the constructor. SkyModel objects can also be
initialized as an empty object (as ``sky = SkyModel()``). When an empty
SkyModel object is initialized, it has all of these attributes defined but
set to ``None``. The attributes can be set by reading in a data file using
the :meth:`pyradiosky.SkyModel.read` method or by setting them directly on
the object. Some of these attributes are `required`_ to be set to have a
fully defined data set while others are `optional`_. The
:meth:`pyradiosky.SkyModel.check` method can be called on the object to
verify that all of the required attributes have been set in a consistent
way.

Required
********
These parameters are required to have a sensible SkyModel object and 
are required for most kinds of catalog files.

**Ncomponents**
     Number of components

**Nfreqs**
     Number of frequencies if spectral_type  is 'full' or 'subband', 1 otherwise.

**component_type**
     Type of component, options are: 'healpix', 'point'. If component_type is 'healpix', the components are the pixels in a HEALPix map in units compatible with K or Jy/sr. If the component_type is 'point', the components are point-like sources in units compatible with Jy or K sr. Determines which parameters are required.

**history**
     String of history.

**name**
     Component name, not required for HEALPix maps. shape (Ncomponents,)

**skycoord**
     :class:`astropy.coordinates.SkyCoord` object that contains the component positions, shape (Ncomponents,).

**spectral_type**
     Type of spectral flux specification, options are: 'full','flat', 'subband', 'spectral_index'.

**stokes**
     Component flux per frequency and Stokes parameter. Units compatible with one of: ['Jy', 'K sr', 'Jy/sr', 'K']. Shape: (4, Nfreqs, Ncomponents). 

Optional
********
These parameters are defined by one or more file standard but are not always required.
Some of them are required depending on the spectral_type or component_type (as noted below).

**above_horizon**
     Boolean indicator of whether this source is above the horizon at the current time and location. True indicates the source is above the horizon. shape (Ncomponents,)

**alt_az**
     Altitude and Azimuth of components in local coordinates. shape (2, Ncomponents)

**beam_amp**
     Beam amplitude at the source position as a function of instrument polarization and frequency. shape (4, Nfreqs, Ncomponents)

**extended_model_group**
     Identifier that groups components of an extended source model. Set to an empty string for point sources. shape (Ncomponents,)

**extra_columns**
     A recarray to store other information with a value per component.

**filename**
     List of strings containing the unique basenames (not the full path) of input files.

**frame_coherency**
     Electric field coherency per component in the object frame (given by `skycoord.frame` if `component_type` is 'point' or `hpx_frame` if  `component_type` is 'healpix'). The shape is (2, 2, Nfreqs, Ncomponents,).

**freq_array**
     Frequency array giving the center frequency in Hz, only required if spectral_type is 'full' or 'subband'.

**freq_edge_array**
     Array giving the frequency  band edges in Hz, only required if spectral_type is 'subband'. The zeroth index in the first dimension holds the lower band edge and the first index holds the upper band edge.

**hpx_frame**
     Healpix coordinate frame, a subclass of astropy.coordinates.BaseCoordinateFrame.

**hpx_inds**
     Healpix indices, only required for HEALPix maps.

**hpx_order**
     Healpix pixel ordering (ring or nested). Only required for HEALPix maps.

**nside**
     Healpix nside, only required for HEALPix maps.

**pos_lmn**
     Position cosines of components in local coordinates. shape (3, Ncomponents)

**reference_frequency**
     Reference frequency in Hz, only required if spectral_type is 'spectral_index'. shape (Ncomponents,)

**spectral_index**
     Spectral index only required if spectral_type is 'spectral_index'. shape (Ncomponents,)

**stokes_error**
     Error on the component flux per frequency and Stokes parameter. The details of how this is calculated depends on the catalog. Units should be equivalent to the units of the stokes parameter. Shape: (4, Nfreqs, Ncomponents). 

**telescope_location**
     Telescope Location for local position calculations.

**time**
     Time for local position calculations.

Methods
-------
.. autoclass:: pyradiosky.SkyModel
  :members:

last updated: 2025-06-27