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 pyuvdata.parameter.UVParameter objects but this is fairly transparent to users.

SkyModel objects can be initialized from a file using the 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 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 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: 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

class pyradiosky.SkyModel(name=None, ra=None, dec=None, stokes=None, spectral_type=None, freq_array=None, freq_edge_array=None, lon=None, lat=None, gl=None, gb=None, frame=None, skycoord=None, reference_frequency=None, spectral_index=None, component_type=None, nside=None, hpx_inds=None, hpx_order=None, stokes_error=None, extended_model_group=None, beam_amp=None, extra_column_dict=None, history='', filename=None, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Object to hold point source and diffuse models.

Can be initialized using the from_file() class method or read() method, or by passing parameters listed below on object initialization. It can also be initialized as an empty object (by passing no parameters on object initialization), which will have all the attributes set to None so that the attributes can be set directly on the object at a later time. After setting attributes on the object, use the check() method to verify that the object is self-consistent.

Parameters:

name (array_like of str) – Unique identifier for each source component, shape (Ncomponents,). Not used if nside is set.
lon (astropy.coordinates.Longitude) – Source longitude in frame specified by keyword frame, shape (Ncomponents,).
lat (astropy.coordinates.Latitude) – Source latitude in frame specified by keyword frame, shape (Ncomponents,).
ra (astropy.coordinates.Longitude) – Source RA in the frame specified in the frame parameter, shape (Ncomponents,). Not needed if the skycoord is passed.
dec (astropy.coordinates.Latitude) – Source Dec in the frame specified in the frame parameter, shape (Ncomponents,). Not needed if the skycoord is passed.
gl (astropy.coordinates.Longitude) – source longitude in Galactic coordinates, shape (Ncomponents,). Not needed if the skycoord is passed.
gb (astropy.coordinates.Latitude) – source latitude in Galactic coordinates, shape (Ncomponents,). Not needed if the skycoord is passed.
frame (str or subclass of astropy.coordinates.BaseCoordinateFrame) – Astropy Frame or name of frame of source positions. If ra/dec or gl/gb are provided, this will be set to icrs or galactic by default. Strings must be interpretable by astropy.coordinates.frame_transform_graph.lookup_name(). Required if keywords lon and lat are used. Not needed if the skycoord is passed.
skycoord (astropy.coordinates.SkyCoord) – SkyCoord object giving the component positions.
stokes (astropy.units.Quantity or array_like of float (Deprecated)) – The source flux, shape (4, Nfreqs, Ncomponents). The first axis indexes the polarization as [I, Q, U, V].
spectral_type (str) – Indicates how fluxes should be calculated at each frequency.

Options:
- ‘flat’ : Flat spectrum.
- ‘full’ : Flux is defined by a value at each frequency.
- ‘subband’ : Flux is given at a set of band centers.
- ‘spectral_index’ : Flux is given at a reference frequency.
freq_array (astropy.units.Quantity) – Array of frequencies that fluxes are provided for, shape (Nfreqs,). If freq_edge_array is passed and freq_array is not set, freq_array will be calculated as the mean of the frequency edges per channel.
freq_edge_array (astropy.units.Quantity) – Array of frequencies giving the edges of the frequency bands, shape (2, Nfreqs). The zeroth index in the first dimension is for the lower edge of the band, the first index is for the upper edge. Only required for the subband spectral_type. If freq_array is a regularly spaced array and freq_edge_array is not set, freq_edge_array will be calculated from the freq_array assuming the band edges are directly between the band centers. An error will be raised if freq_array is not regularly spaced and freq_edge_array is not set.
reference_frequency (astropy.units.Quantity) – Reference frequencies of flux values, shape (Ncomponents,).
spectral_index (array_like of float) – Spectral index of each source, shape (Ncomponents). None if spectral_type is not ‘spectral_index’.
component_type (str) – Component type, either ‘point’ or ‘healpix’. If this is not set, the type is inferred from whether nside is set.
nside (int) – nside parameter for HEALPix maps.
hpx_inds (array_like of int) – Indices for HEALPix maps, only used if nside is set.
hpx_order (str) – For HEALPix maps, pixel ordering parameter. Can be “ring” or “nested”. Defaults to “ring” if unset in init keywords.
extended_model_group (array_like of str) – Identifier that groups components of an extended source model. Empty string for point sources, shape (Ncomponents,).
beam_amp (array_like of float) – Beam amplitude at the source position, shape (4, Nfreqs, Ncomponents). 4 element vector corresponds to [XX, YY, XY, YX] instrumental polarizations.
extra_column_dict (dict) – Dictionary of data to put in the extra_columns attribute. The keys are the column names, values should be 1D arrays, each with length Ncomponents.
history (str) – History to add to object.
filename (str or list of str) – Base file name (not the whole path) or list of base file names for input data to track on the object.

property ncomponent_length_params: Iterate over ncomponent length paramters.

add_extra_columns(*, names: str | list[str], values: ndarray[tuple[Any, ...], dtype[_ScalarT]] | list[numpy.ndarray[tuple[Any, ...], numpy.dtype[_ScalarT]]], dtype: str | list[str] | None = None)[source]

Add one or more length Ncomponent attributes to the object.

Parameters:

name (str or list of str) – The name(s) of the column(s).
value (np.ndarray or list of np.ndarray) – The value(s) of the data or metadata, each must be a 1D array of length Ncomponents. Note: Quantities are not supported.
dtype (str or list of str) – The type(s) that the data or metadata should be. If not set, use the dtype(s) of value.

remove_extra_columns(names: str | list[str])[source]

Remove one or more length Ncomponent attributes to the object.

Parameters:: name (str or list of str) – The name(s) of the column(s) to remove.

clear_time_position_specific_params()[source]: Set parameters which are time & position specific to None.

check(check_extra=True, run_check_acceptability=True)[source]

Check that all required parameters are set reasonably.

Check that required parameters exist and have appropriate shapes. Optionally check if the values are acceptable.

Parameters:

check_extra (bool) – Option to check optional parameters as well as required ones.
run_check_acceptability (bool) – Option to check if values in required parameters are acceptable.

transform_to(frame)[source]

Transform to a different skycoord coordinate frame.

This function is a thin wrapper on astropy.coordinates.SkyCoord.transform_to() please refer to that function for full documentation.

Parameters:: frame (str, BaseCoordinateFrame class or instance.) – The frame to transform this coordinate into. Currently frame must be one of [“galactic”, “icrs”].

healpix_interp_transform(frame, full_sky=False, inplace=True, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Transform a HEALPix map to a new frame and interpolate to new pixel centers.

This method is only available for a healpix type sky model. Computes the pixel centers for a HEALPix map in the new frame, then interpolates the old map using astropy_healpix.HEALPix.interpolate_bilinear_skycoord().

Conversion with this method may take some time as it must iterate over every frequency and stokes parameter individually.

Currently no polarization fixing is performed by this method. As a result, it does not support transformations for polarized catalogs since this would induce a Q <–> U rotation.

Current implementation is equal to using a healpy.Rotator class to 1 part in 10^-5 (e.g numpy.allclose(healpy_rotated_map, interpolate_bilinear_skycoord, rtol=1e-5) is True()).

Parameters:

frame (str, astropy.coordinates.BaseCoordinateFrame class or instance.) – The frame to transform this coordinate into.
full_sky (bool) – When True returns a full sky catalog even when some pixels are zero. Defaults to False.
inplace (bool) – Option to do the change in place on the object rather than return a new object. Default to True
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

Returns:

SkyModel object or None – Returns None if inplace is True (the calling object is updated), otherwise the modified SkyModel object is returned.

kelvin_to_jansky()[source]

Apply a conversion to stokes from K-based units to Jy-based units.

No conversion is applied if stokes is already compatible with Jy (for point component_type) or Jy/sr (for healpix component_type).

jansky_to_kelvin()[source]

Apply a conversion to stokes from Jy-based units to K-based units.

No conversion is applied if stokes is already compatible with K sr (for point component_type) or K (for healpix component_type).

get_lon_lat()[source]

Retrieve longitudinal and latitudinal (e.g. RA and Dec) values for components.

This is mostly useful for healpix objects where the coordinates are not stored on the object (only the healpix inds are stored, which can be converted to coordinates using this method).

healpix_to_point(to_jy=True, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Convert a healpix component_type object to a point component_type.

Multiply by the pixel area and optionally convert to Jy. This effectively treats diffuse pixels as unresolved point sources by integrating over the pixel area. Whether or not this is a good assumption depends on the nside and the resolution of the telescope, so it should be used with care, but it is provided here as a convenience.

Parameters:

to_jy (bool) – Option to convert to Jy compatible units.
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

assign_to_healpix(nside, order='ring', to_k=True, full_sky=False, sort=True, inplace=False, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Assign point components to their nearest pixel in a healpix grid.

Also divide by the pixel area and optionally convert to K. This effectively converts point sources to diffuse pixels in a healpix map. Whether or not this is a good assumption depends on the nside and the resolution of the telescope, so it should be used with care, but it is provided here as a convenience.

Note that the time and position specific parameters [time, telescope_location, alt_az, pos_lmn and above_horizon] will be set to None as part of this method. They can be recalculated afterwards if desired using the update_positions() method.

Parameters:

nside (int) – nside of healpix map to convert to.
order (str) – Order convention of healpix map to convert to, either “ring” or “nested”.
to_k (bool) – Option to convert to K compatible units.
full_sky (bool) – Option to create a full sky healpix map with zeros in the stokes array for pixels with no sources assigned to them. If False only pixels with sources mapped to them will be included in the object.
sort (bool) – Option to sort the object in order of the healpix indicies.
inplace (bool) – Option to do the change in place on the object rather than return a new object.
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

Returns:

SkyModel object or None – Returns None if inplace is True (the calling object is updated), otherwise the modified SkyModel object is returned.

at_frequencies(freqs, inplace=True, freq_interp_kind='cubic', nan_handling='clip', run_check=True, check_extra=True, run_check_acceptability=True, atol=None)[source]

Evaluate the stokes array at the specified frequencies.

Produces a SkyModel object that is in the full frequency spectral type, based on the current spectral type:

full: Extract a subset of existing frequencies.

subband: Interpolate to new frequencies.

spectral_index: Evaluate at the new frequencies.

flat: Copy to new frequencies.

Parameters:

freqs (Quantity) – Frequencies at which Stokes parameters will be evaluated.
inplace (bool) – If True, modify the current SkyModel object. Otherwise, returns a new instance. Default True.
freq_interp_kind (str or int) – Spline interpolation order, as can be understood by scipy.interpolate.interp1d. Only used if the spectral_type is “subband”.
nan_handling (str) – Choice of how to handle nans in the stokes when interpolating, only used if the spectral_type is “subband”. These are applied per source, so sources with no NaNs will not be affected by these choices. Options are “propagate” to set all the output stokes to NaN values if any of the input stokes values are NaN, “interp” to interpolate values using only the non-NaN values and to set any values that are outside the range of non-NaN values to NaN, and “clip” to interpolate values using only the non-NaN values and to set any values that are outside the range of non-NaN values to the nearest non-NaN value. For both “interp” and “clip”, any sources that have too few non-Nan values to use the chosen freq_interp_kind will be interpolated linearly and any sources that have all NaN values in the stokes array will have NaN values in the output stokes. Note that the detection of NaNs is done across all polarizations for each source, so all polarizations are evaluated using the same set of frequencies (so a NaN in one polarization at one frequency will cause that frequency to be excluded for the interpolation of all the polarizations on that source).
run_check (bool) – Run check on new SkyModel.
check_extra (bool) – Option to check optional parameters as well as required ones.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after combining objects.
atol (Quantity) – Tolerance for frequency comparison. Defaults to 1 Hz.

Returns:

SkyModel object or None – Returns None if inplace is True (the calling object is updated), otherwise the modified SkyModel object is returned.

update_positions(time, telescope_location)[source]

Calculate the altitude/azimuth positions for source components.

From alt/az, calculate direction cosines (lmn)

Doesn’t return anything but updates the following attributes in-place:

pos_lmn

alt_az

time

Parameters:

time (astropy.time.Time) – Time to update positions for.
telescope_location (EarthLocation or MoonLocation) – Telescope location to update positions for, must be either an astropy.coordinates.EarthLocation or a lunarsky.MoonLocation object.

calc_frame_coherency(store=True)[source]

Calculate the coherency in the object skymodel frame or hpx_frame.

Parameters:: store (bool) – Option to store the frame_coherency to the object. This saves time for repeated calls but adds memory.

coherency_calc(store_frame_coherency=True)[source]

Calculate the local coherency in alt/az basis.

SkyModel.update_positions() must be run prior to this method.

The coherency is a 2x2 matrix giving electric field correlation in Jy. It is specified on the object as a coherency in the frame basis, but must be rotated into local alt/az.

Parameters:: store_frame_coherency (bool) – Option to store the frame_coherency to the object. This saves time for repeated calls but adds memory.
Returns:: array of float – local coherency in alt/az basis, shape (2, 2, Nfreqs, Ncomponents)

concat(other, clear_time_position=True, verbose_history=False, inplace=True, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Combine two SkyModel objects along source axis.

Parameters:

other (SkyModel object) – Another SkyModel object which will be concatenated with self.
inplace (bool) – If True, overwrite self as we go, otherwise create a third object as the sum of the two.
clear_time_position (bool) – Option to clear time and position dependent parameters on both objects before concatenation. If False, time and position dependent parameters must match on both objects.
verbose_history (bool) – Option to allow more verbose history. If True and if the histories for the two objects are different, the combined object will keep all the history of both input objects (if many objects are combined in succession this can lead to very long histories). If False and if the histories for the two objects are different, the combined object will have the history of the first object and only the parts of the second object history that are unique (this is done word by word and can result in hard to interpret histories).
run_check (bool) – Option to check for the existence and proper shapes of parameters after combining objects.
check_extra (bool) – Option to check optional parameters as well as required ones.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after combining objects.

Returns:

SkyModel object or None – Returns None if inplace is True (the calling object is updated), otherwise the combined SkyModel object is returned.

Raises:

ValueError – If other is not a SkyModel object, self and other are not compatible or if data in self and other overlap. One way they can not be compatible is if they have different spectral_types.

select(component_inds: list[int] | ndarray[int] | None = None, lat_range: Latitude | None = None, lon_range: Longitude | None = None, min_brightness: Quantity | None = None, max_brightness: Quantity | None = None, brightness_freq_range: Quantity | None = None, non_nan: Literal['any', 'all'] | None = None, non_negative: bool = False, inplace: bool = True, run_check: bool = True, check_extra: bool = True, run_check_acceptability: bool = True)[source]

Downselect sources based on various criteria.

The history attribute on the object will be updated to identify the operations performed.

Parameters:

component_inds (array_like of int) – Component indices to keep on the object.
lat_range (astropy.coordinates.Latitude) – Range of Dec or galactic latitude, depending on the object skycoord.frame attribute, to keep on the object, shape (2,).
lon_range (astropy.coordinates.Longitude) – Range of RA or galactic longitude, depending on the object skycoord.frame attribute, to keep on the object, shape (2,). If the second value is smaller than the first, the lons are treated as being wrapped around lon = 0, and the lons kept on the object will run from the larger value, through 0, and end at the smaller value.
min_brightness (astropy.units.Quantity) – Minimum brightness in stokes I to keep on object (implemented as a >= cut).
max_brightness (astropy.units.Quantity) – Maximum brightness in stokes I to keep on object (implemented as a <= cut).
brightness_freq_range (astropy.units.Quantity) – Frequency range over which the min and max brightness tests should be performed. Must be length 2. If None, use the range over which the object is defined.
non_nan (string or None) – Option to only keep components that do not have NaN values in the stokes parameter at “any” or “all” frequencies. Options are “any”, “all” or None (for no cuts), default is None.
non_negative (bool) – Only keep components that do not have any negative Stokes I values.
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).
inplace (bool) – Option to perform the select directly on self or return a new SkyModel object with just the selected data (the default is True, meaning the select will be done on self).

Returns:

SkyModel object or None – Returns None if inplace is True (the calling object is updated), otherwise the modified SkyModel object is returned.

calculate_rise_set_lsts(telescope_latitude, horizon_buffer=0.04364)[source]

Calculate the rise & set LSTs given a telescope latitude.

Sets the _rise_lst and _set_lst attributes on the object. These values can be NaNs for sources that never rise or never set. Call cut_nonrising() to remove sources that never rise from the object.

Parameters:

telescope_latitude (Latitude object) – Latitude of telescope. Used to estimate rise/set lst.
horizon_buffer (float) – Angle buffer for rise/set LSTs in radians. Default is about 10 minutes of sky rotation. Components whose calculated altitude is less than horizon_buffer are excluded. Caution! The altitude calculation does not account for precession/nutation of the Earth. The buffer angle is needed to ensure that the horizon cut doesn’t exclude sources near but above the horizon. Since the cutoff is done using lst, and the lsts are calculated with astropy, the required buffer should _not_ drift with time since the J2000 epoch. The default buffer has been tested around julian date 2457458.0.

cut_nonrising(telescope_latitude, inplace=True, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Remove sources that will never rise.

Parameters:

telescope_latitude (Latitude object) – Latitude of telescope.
inplace (bool) – Option to do the cuts on the object in place or to return a copy with the cuts applied.
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

Returns:

SkyModel object or None – Returns None if inplace is True (the calling object is updated), otherwise the modified SkyModel object is returned.

read_skyh5(filename: str, skip_params: str | list[str] | bool = False, run_check: bool = True, check_extra: bool = True, run_check_acceptability: bool = True)[source]

Read a skyh5 file (our flavor of hdf5) into this object.

Parameters:

filename (str) – Path and name of the skyh5 file to read.
skip_params (str or list of str or bool) – A list of optional parameters to skip on read. If set to True, skip all truly optional parameters. The default is False, so by default all optional parameters will be read. Note that this only applies to truly optional parameters that are saved in the file, any optional parameters not saved in the file are always skipped.
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

classmethod from_skyh5(filename: str, **kwargs)[source]

Create a new SkyModel from skyh5 file (our flavor of hdf5).

Parameters:

filename (str) – Path and name of the skyh5 file to read.
skip_params (str or list of str or bool, default=False) – A list of optional parameters to skip on read. If set to True, skip all truly optional parameters. The default is False, so by default all optional parameters will be read. Note that this only applies to truly optional parameters that are saved in the file, any optional parameters not saved in the file are always skipped.
run_check (bool, default=True) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool, default=True) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool, default=True) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

read_votable_catalog(votable_file, table_name, id_column, lon_column, lat_column, flux_columns, frame, reference_frequency=None, freq_array=None, freq_edge_array=None, spectral_index_column=None, flux_error_columns=None, history='', run_check=True, check_extra=True, run_check_acceptability=True)[source]

Read a votable catalog file into this object.

This reader uses the units in the file, the units should be specified following the VOTable conventions.

Parameters:

votable_file (str) – Path to votable catalog file.
table_name (str) – Part of expected table name. Should match only one table name in votable_file.
id_column (str) – Part of expected ID column. Should match only one column in the table.
lon_column (str) – Part of expected longitudinal coordinate (e.g. RA) column. Should match only one column in the table.
lat_column (str) – Part of expected latitudinal coordinate (e.g. Dec) column. Should match only one column in the table.
flux_columns (str or list of str) – Part of expected Flux column(s). Each one should match only one column in the table.
frame (str) – Name of coordinate frame of source positions (lon/lat columns). Must be interpretable by astropy.coordinates.frame_transform_graph.lookup_name().
reference_frequency (astropy.units.Quantity) – Reference frequency for flux values, assumed to be the same value for all rows.
freq_array (astropy.units.Quantity) – Frequency band centers corresponding to flux_columns (should be same length). Required for multiple flux columns.
freq_edge_array (astropy.units.Quantity) – Frequency sub-band edges for each flux_columns, shape (2, len(flux_columns)). Required for multiple flux columns if freq_array is not regularly spaced. If freq_array is regularly spaced and freq_edge_array is not passed, freq_edge_array will be calculated from the freq_array assuming the band edges are directly between the band centers.
spectral_index_column (str) – Part of expected spectral index column. Should match only one column in the table.
flux_error_columns (str or list of str) – Part of expected Flux error column(s). Each one should match only one column in the table.
history (str) – History to add to object.
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

classmethod from_votable_catalog(votable_file: str, *args, **kwargs)[source]

Create a new SkyModel from a votable catalog.

This reader uses the units in the file, the units should be specified following the VOTable conventions.

Parameters:

votable_file (str) – Path to votable catalog file.
table_name (str) – Part of expected table name. Should match only one table name in votable_file.
id_column (str) – Part of expected ID column. Should match only one column in the table.
lon_column (str) – Part of expected longitudinal coordinate (e.g. RA) column. Should match only one column in the table.
lat_column (str) – Part of expected latitudinal coordinate (e.g. Dec) column. Should match only one column in the table.
flux_columns (str or list of str) – Part of expected Flux column(s). Each one should match only one column in the table.
frame (str) – Name of coordinate frame of source positions (lon/lat columns). Must be interpretable by astropy.coordinates.frame_transform_graph.lookup_name().
reference_frequency (astropy.units.Quantity) – Reference frequency for flux values, assumed to be the same value for all rows.
freq_array (astropy.units.Quantity) – Frequency band centers corresponding to flux_columns (should be same length). Required for multiple flux columns.
freq_edge_array (astropy.units.Quantity) – Frequency sub-band edges for each flux_columns, shape (2, len(flux_columns)). Required for multiple flux columns if freq_array is not regularly spaced. If freq_array is regularly spaced and freq_edge_array is not passed, freq_edge_array will be calculated from the freq_array assuming the band edges are directly between the band centers.
spectral_index_column (str) – Part of expected spectral index column. Should match only one column in the table.
flux_error_columns (str or list of str) – Part of expected Flux error column(s). Each one should match only one column in the table.
history (str) – History to add to object.
run_check (bool, default=True) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool, default=True) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool, default=True) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

read_gleam_catalog(gleam_file: str, spectral_type: Literal['flat', 'subband', 'spectral_index'] = 'subband', with_error: bool = False, use_paper_freqs: bool = False, run_check: bool = True, check_extra: bool = True, run_check_acceptability: bool = True)[source]

Read the GLEAM votable catalog file into this object.

Note that when using spectral_type=”spectral_index”, the spectral indices for some sources are set to NaNs when the source fluxes were not well fit with a power law. Even some bright sources have NaNs for spectral indices. With a “subband” spectral type, GLEAM also has sources that have NaNs and negatives in their Stokes I values for some or all frequencies.

Note that the GLEAM paper specifies that the 30.72 MHz bandwidth is subdivided into four 7.68 MHz sub-channels. But that clashes with the frequencies and edges listed in the catalog documentation which are spaced by exactly 8MHz. By default, this method uses the catalog frequency values. To use our best guess of the real values (which are not specified in the paper), set use_paper_freqs=True. This option only has an effect if spectral_type=”subband”.

Tested on: GLEAM EGC catalog, version 2

Parameters:

gleam_file (str) – Path to GLEAM votable catalog file.
spectral_type (str) – One of ‘flat’, ‘subband’ or ‘spectral_index’. If set to ‘flat’, the wide band integrated flux will be used, if set to ‘spectral_index’ the fitted flux at 200 MHz will be used for the flux column.
with_error (bool) – Option to include the errors on the stokes array on the object in the stokes_error parameter. Note that the values assigned to this parameter are the flux fitting errors. The GLEAM paper (Hurley-Walker et al., 2019) specifies that flux scale errors should be added in quadrature to these fitting errors, but that the size of the flux scale errors depends on whether the comparison is between GLEAM sub-bands or with another catalog. Between GLEAM sub-bands, the flux scale error is 2-3% of the component flux (depending on declination), while flux scale errors between GLEAM and other catalogs is 8-80% of the component flux (depending on declination).
use_paper_freqs (bool) – Use our best guess of the frequencies based on the GLEAM paper and what we know about the MWA. This option exists because the GLEAM paper specifies that the 30.72 MHz bandwidth is subdivided into four 7.68 MHz sub-channels. But the frequencies and edges listed in the catalog documentation are spaced by exactly 8MHz rather than 7.68 MHz. Our calculated band centers are different from the catalog values by at most 0.6 MHz, the band edges are different by at most 1.08 MHz. Only used if spectral_type=”subband”.
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

classmethod from_gleam_catalog(gleam_file: str, **kwargs)[source]

Create a SkyModel from a GLEAM catalog.

Note that when using spectral_type=”spectral_index”, the spectral indices for some sources are set to NaNs when the source fluxes were not well fit with a power law. Even some bright sources have NaNs for spectral indices. With a “subband” spectral type, GLEAM also has sources that have NaNs and negatives in their Stokes I values for some or all frequencies.

Note that the GLEAM paper specifies that the 30.72 MHz bandwidth is subdivided into four 7.68 MHz sub-channels. But that clashes with the frequencies and edges listed in the catalog documentation which are spaced by exactly 8MHz. By default, this method uses the catalog frequency values. To use our best guess of the real values (which are not specified in the paper), set use_paper_freqs=True. This option only has an effect if spectral_type=”subband”.

Tested on: GLEAM EGC catalog, version 2

Parameters:

gleam_file (str) – Path to GLEAM votable catalog file.
spectral_type (str) – One of ‘flat’, ‘subband’ or ‘spectral_index’. If set to ‘flat’, the wide band integrated flux will be used, if set to ‘spectral_index’ the fitted flux at 200 MHz will be used for the flux column.
with_error (bool) – Option to include the errors on the stokes array on the object in the stokes_error parameter. Note that the values assigned to this parameter are the flux fitting errors. The GLEAM paper (Hurley-Walker et al., 2019) specifies that flux scale errors should be added in quadrature to these fitting errors, but that the size of the flux scale errors depends on whether the comparison is between GLEAM sub-bands or with another catalog. Between GLEAM sub-bands, the flux scale error is 2-3% of the component flux (depending on declination), while flux scale errors between GLEAM and other catalogs is 8-80% of the component flux (depending on declination).
use_paper_freqs (bool) – Use our best guess of the frequencies based on the GLEAM paper and what we know about the MWA. This option exists because the GLEAM paper specifies that the 30.72 MHz bandwidth is subdivided into four 7.68 MHz sub-channels. But the frequencies and edges listed in the catalog documentation are spaced by exactly 8MHz rather than 7.68 MHz. Our calculated band centers are different from the catalog values by at most 0.6 MHz, the band edges are different by at most 1.08 MHz. Only used if spectral_type=”subband”.
run_check (bool, default=True) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool, default=True) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool, default=True) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

read_text_catalog(catalog_csv, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Read a text file of sources into this object.

Parameters:

catalog_csv (str) – Path to tab separated value file with the following required columns: * source_id: source name as a string of maximum 10 characters * <lon_coord>_<frame_info>: Longitudinal coordinate in degrees, can be FK4 or FK5 (noted by a b or j followed by the equinox) or any frame supported by astropy which does not require extra attributes. Tested examples include ICRS (ra_icrs), Galactic (l_galactic), FK4 (ra_b1950) and FK5 (ra_j2000). * <lat_coord>_<frame_info>: Latitudinal coordinate in degrees, can be FK4 or FK5 (noted by a b or j followed by the equinox) or any frame supported by astropy which does not require extra attributes. Tested examples include ICRS (dec_icrs), Galactic (b_galactic), FK4 (dec_b1950) and FK5 (dec_j2000). * Flux [Jy]: Stokes I flux density in Janskys

If flux is specified at multiple frequencies (must be the same set for all components), the frequencies must be included in each column name, e.g. Flux at 150 MHz [Jy]. Recognized units are (‘Hz’, ‘kHz’, ‘MHz’ or ‘GHz’):

If flux is only specified at one reference frequency (can be different per component), a frequency column should be added (note: assumed to be in Hz): * Frequency: reference frequency [Hz]

Optionally a spectral index can be specified per component with: * Spectral_Index: spectral index
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

classmethod from_text_catalog(catalog_csv: str, **kwargs)[source]

Create a SkyModel from a text catalog.

Parameters:

catalog_csv (str) – Path to tab separated value file with the following required columns: * source_id: source name as a string of maximum 10 characters * <lon_coord>_<frame_info>: Longitudinal coordinate in degrees, can be FK4 or FK5 (noted by a b or j followed by the equinox) or any frame supported by astropy which does not require extra attributes. Tested examples include ICRS (ra_icrs), Galactic (l_galactic), FK4 (ra_b1950) and FK5 (ra_j2000). * <lat_coord>_<frame_info>: Latitudinal coordinate in degrees, can be FK4 or FK5 (noted by a b or j followed by the equinox) or any frame supported by astropy which does not require extra attributes. Tested examples include ICRS (dec_icrs), Galactic (b_galactic), FK4 (dec_b1950) and FK5 (dec_j2000). * Flux [Jy]: Stokes I flux density in Janskys

If flux is specified at multiple frequencies (must be the same set for all components), the frequencies must be included in each column name, e.g. Flux at 150 MHz [Jy]. Recognized units are (‘Hz’, ‘kHz’, ‘MHz’ or ‘GHz’):

If flux is only specified at one reference frequency (can be different per component), a frequency column should be added (note: assumed to be in Hz): * Frequency: reference frequency [Hz]

Optionally a spectral index can be specified per component with: * Spectral_Index: spectral index
run_check (bool, default=True) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool, default=True) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool, default=True) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

read_fhd_catalog(filename_sav: str, expand_extended: bool = True, extra_columns: dict | None = None, run_check: bool = True, check_extra: bool = True, run_check_acceptability: bool = True)[source]

Read in an FHD style catalog file.

FHD catalog files are IDL save files.

Parameters:

filename_sav (str) – Path to IDL .sav file.
expand_extended (bool) – If True, include extended source components.
extra_columns (dict, optional) – Dict giving structure tags to store in extra columns. Keys are idl structure tags, values are keys for extra_columns entries.
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

classmethod from_fhd_catalog(filename_sav: str, **kwargs)[source]

Create a SkyModel from an FHD catalog.

FHD catalog files are IDL save files.

Parameters:

filename_sav (str) – Path to IDL .sav file.
expand_extended (bool) – If True, include extended source components.
extra_columns (dict, optional) – Dict giving structure tags to store in extra columns. Keys are idl structure tags, values are keys for extra_columns entries.
run_check (bool, default=True) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool, default=True) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool, default=True) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

Read in any file supported by SkyModel.

This method supports a number of different types of files. Universal parameters (required and optional) are listed directly below, followed by parameters specific to each file type.

Parameters:

filename (str) – File to read in.
filetype (str, optional) – One of [‘skyh5’, ‘gleam’, ‘vot’, ‘text’, ‘fhd’] or None. If None, the code attempts to guess what the file type is.
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

GLEAM:

spectral_type (str) – Option to specify the GLEAM spectral_type to read in. Default is ‘subband’.
with_error (bool) – Option to include the errors on the stokes array on the object in the stokes_error parameter. Note that the values assigned to this parameter are the flux fitting errors. The GLEAM paper (Hurley-Walker et al., 2019) specifies that flux scale errors should be added in quadrature to these fitting errors, but that the size of the flux scale errors depends on whether the comparison is between GLEAM sub-bands or with another catalog. Between GLEAM sub-bands, the flux scale error is 2-3% of the component flux (depending on declination), while flux scale errors between GLEAM and other catalogs is 8-80% of the component flux (depending on declination).
use_paper_freqs (bool) – Use our best guess of the frequencies based on the GLEAM paper and what we know about the MWA. This option exists because the GLEAM paper specifies that the 30.72 MHz bandwidth is subdivided into four 7.68 MHz sub-channels. But the frequencies and edges listed in the catalog documentation are spaced by exactly 8MHz rather than 7.68 MHz. Our calculated band centers are different from the catalog values by at most 0.6 MHz, the band edges are different by at most 1.08 MHz. Only used if spectral_type=”subband”.

FHD:

expand_extended (bool) – If True, include the extended source components in FHD files.
extra_columns (dict, optional) – Dict giving structure tags to store in extra columns. Keys are idl structure tags, values are keys for extra_columns entries.

SkyH5:

skip_params (str or list of str or bool) – A list of optional parameters to skip on read. If set to True, skip all optional parameters. The default is False, so by default all optional parameters will be read. Note that this only applies to truly optional parameters that are saved in the file, any optional parameters not saved in the file are always skipped.

VOTable:

table_name (str) – Part of expected VOTable name. Should match only one table name in the file.
id_column (str) – Part of expected VOTable ID column. Should match only one column in the file.
lon_column (str) – Part of expected VOTable longitudinal coordinate column. Should match only one column in the file.
lat_column (str) – Part of expected VOTable latitudinal coordinate column. Should match only one column in the file.
flux_columns (str or list of str) – Part of expected vot Flux column(s). Each one should match only one column in the file. Only used for vot files.
frame (str) – Name of coordinate frame for VOTable source positions (lon/lat columns). Defaults to “icrs”. Must be interpretable by astropy.coordinates.frame_transform_graph.lookup_name(). Only used for vot files.
reference_frequency (astropy.units.Quantity) – Reference frequency for VOTable flux values, assumed to be the same value for all components.
freq_array (astropy.units.Quantity) – Frequencies corresponding to VOTable flux_columns (should be same length). Required for multiple flux columns.
freq_edge_array (astropy.units.Quantity) – Frequency sub-band edges for each flux_columns, shape (2, len(flux_columns)). Required for multiple flux columns if freq_array is not regularly spaced. If freq_array is regularly spaced and freq_edge_array is not passed, freq_edge_array will be calculated from the freq_array assuming the band edges are directly between the band centers.
spectral_index_column (str) – Part of expected VOTable spectral index column. Should match only one column in the file.
flux_error_columns (str or list of str) – Part of expected VOTable flux error column(s). Each one should match only one column in the file.
history (str) – History to add to object for VOTable files.

classmethod from_file(filename: str, **kwargs)[source]

Initialize a new SkyModel from any file supported by SkyModel.

This method supports a number of different types of files. Universal parameters (required and optional) are listed directly below, followed by parameters specific to each file type.

Parameters:

filename (str) – File to read in.
filetype (str, optional) – One of [‘skyh5’, ‘gleam’, ‘vot’, ‘text’, ‘fhd’] or None. If None, the code attempts to guess what the file type is.
run_check (bool, default=True) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool, default=True) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool, default=True) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

GLEAM:

spectral_type (str, default=’subband’) – Option to specify the GLEAM spectral_type to read in. Default is ‘subband’.
with_error (bool) – Option to include the errors on the stokes array on the object in the stokes_error parameter. Note that the values assigned to this parameter are the flux fitting errors. The GLEAM paper (Hurley-Walker et al., 2019) specifies that flux scale errors should be added in quadrature to these fitting errors, but that the size of the flux scale errors depends on whether the comparison is between GLEAM sub-bands or with another catalog. Between GLEAM sub-bands, the flux scale error is 2-3% of the component flux (depending on declination), while flux scale errors between GLEAM and other catalogs is 8-80% of the component flux (depending on declination).
use_paper_freqs (bool) – Use our best guess of the frequencies based on the GLEAM paper and what we know about the MWA. This option exists because the GLEAM paper specifies that the 30.72 MHz bandwidth is subdivided into four 7.68 MHz sub-channels. But the frequencies and edges listed in the catalog documentation are spaced by exactly 8MHz rather than 7.68 MHz. Our calculated band centers are different from the catalog values by at most 0.6 MHz, the band edges are different by at most 1.08 MHz. Only used if spectral_type=”subband”.

FHD:

expand_extended (bool) – If True, include the extended source components in FHD files.
extra_columns (dict, optional) – Dict giving structure tags to store in extra columns. Keys are idl structure tags, values are keys for extra_columns entries.

SkyH5:

skip_params (str or list of str or bool, default=False) – A list of optional parameters to skip on read. If set to True, skip all optional parameters. The default is False, so by default all optional parameters will be read. Note that this only applies to truly optional parameters that are saved in the file, any optional parameters not saved in the file are always skipped.

VOTable:

table_name (str) – Part of expected VOTable name. Should match only one table name in the file.
id_column (str) – Part of expected VOTable ID column. Should match only one column in the file.
lon_column (str) – Part of expected VOTable longitudinal coordinate column. Should match only one column in the file.
lat_column (str) – Part of expected VOTable latitudinal coordinate column. Should match only one column in the file.
flux_columns (str or list of str) – Part of expected vot Flux column(s). Each one should match only one column in the file. Only used for vot files.
frame (str, default=”icrs”) – Name of coordinate frame for VOTable source positions (lon/lat columns). Defaults to “icrs”. Must be interpretable by astropy.coordinates.frame_transform_graph.lookup_name(). Only used for vot files.
reference_frequency (astropy.units.Quantity) – Reference frequency for VOTable flux values, assumed to be the same value for all components.
freq_array (astropy.units.Quantity) – Frequencies corresponding to VOTable flux_columns (should be same length). Required for multiple flux columns.
freq_edge_array (astropy.units.Quantity) – Frequency sub-band edges for each flux_columns, shape (2, len(flux_columns)). Required for multiple flux columns if freq_array is not regularly spaced. If freq_array is regularly spaced and freq_edge_array is not passed, freq_edge_array will be calculated from the freq_array assuming the band edges are directly between the band centers.
spectral_index_column (str) – Part of expected VOTable spectral index column. Should match only one column in the file.
flux_error_columns (str or list of str) – Part of expected VOTable flux error column(s). Each one should match only one column in the file.
history (str) – History to add to object for VOTable files.

write_skyh5(filename, clobber=False, data_compression=None, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Write this object to a skyh5 file (our flavor of hdf5).

Parameters:

filename (str) – Path and name of the file to write to.
clobber (bool) – Indicate whether an existing file should be overwritten (clobbered).
data_compression (str) – HDF5 filter to apply when writing the stokes data. Default is None (no filter/compression). One reasonable option to reduce file size is “gzip”.
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).

write_text_catalog(filename)[source]

Write out this object to a text file.

Note that text files have limited functionality compared to skyh5 files. They do not support diffuse maps or subband type catalogs or catalogs with extended_model_groups or catalogs with units other than Jy.

Readable with read_text_catalog().

Parameters:: filename (str) – Path to output file (string)

last updated: 2026-06-03