`castor_etc.sources`

Sources

castor_etc.sources provides methods and classes to define and simulate different astronomical sources with arbitrary flux profiles. Also supports arbitrary surface brightness profiles (either from a function or from a FITS file). This subpackage mainly consists of the Profile class and the Source class.

Predefined flux profiles:

uniform
ellipse (exponentially-decaying flux with tunable scale lengths along the major and minor axes)
sersic

Predefined source types:

point (e.g., for stars)
extended (e.g., for supernova remnants)
galaxies

Module Contents

Classes

`Profiles`	Predefined flux profiles for different astronomical sources.
`Source`	Base (abstract) class for astronomical sources.
`PointSource`	Point source.
`ExtendedSource`	Extended source.
`GalaxySource`	A galaxy.
`CustomSource`	A source with a custom surface brightness profile from a FITS file.

API

class castor_etc.sources.Profiles

Predefined flux profiles for different astronomical sources.

Initialization

static uniform(a=None, b=None, angle=0): Uniform flux profile within some elliptical region or over the entire aperture (note that the aperture will still have fractional pixel weighting). This profile is typically used for a point source, hence the default values should be appropriate (and likely the best choices) in most cases.

Parameters

a, b :: scalar or astropy.Quantity angles or None The semimajor and semiminor axes of the ellipse, respectively. If scalars, they are assumed to be in arcsec. If a pixel partially overlaps the ellipse, the pixel will be weighted by its fractional overlap with the ellipse. If both None, generate uniform profile over the entire aperture.

angle :: scalar The counter-clockwise angle to rotate the ellipse, in degrees. At an angle of 0, a and b are aligned with the x- and y-axes, respectively.

Returns

profile :: function Function that generates a uniform flux profile.

static ellipse(a0, b0, angle=0)

Exponentially-decaying elliptical profile with arbitrary rotation. This profile is designed such that the center of the ellipse is always at (0, 0) but the aperture center (specified in the castor_etc.Photometry object) relative to this ellipse center can be set to arbitrary coordinates.

The weights are calculated as:

        weights = exp[-( (source_a/a0)^2 + (source_b/b0)^2 )]

where

        source_a = (x + x0) * cos(angle) + (y + y0) * sin(angle)

and

        source_b = (y + y0) * cos(angle) - (x + x0) * sin(angle)

x and y are the x- and y-coordinates of the aperture pixel (in arcsec) relative to the aperture (not source) center,
x0 and y0 are the x- and y-coordinates of the aperture center relative to the source center, in arcsec,
angle is the counter-clockwise rotation of the ellipse, in degrees. At an angle of 0, the semimajor axis (corresponding to the same line as a0) is aligned with the x-axis and the semiminor axis (corresponding to the same line as b0) is aligned with the y-axis.

Parameters

a0, b0 :: scalar or astropy.Quantity angles The “scale-length” semimajor and semiminor axes of the ellipse, respectively. That is, the flux at the elliptical level curve defined by a0 and b0 is a factor of e less than the flux at the center of the ellipse. If scalars, a0 and b0 are assumed to be in arcsec.

angle :: scalar The counter-clockwise angle to rotate the ellipse, in degrees. At an angle of 0, a0 and b0 are aligned with the x- and y-axes, respectively.

Returns

profile :: function Function that generates an exponentially-decaying elliptical profile.

static sersic(r_eff, n=1, e=0, angle=0)

2D Sersic profile for describing how the flux of a galaxy changes as a function of distance from its center. This is actually just a wrapper function for astropy’s Sersic2D model (https://docs.astropy.org/en/stable/api/astropy.modeling.functional_models.Sersic2D.html).

The following docstring is adapted from the astropy Sersic2D docstring.

Parameters

r_eff :: scalar or astropy.Quantity angle Effective (half-light) radius. If a scalar, r_eff is assumed to be in arcsec.

n :: scalar Sersic index of the galaxy.

e :: scalar Ellipticity of the galaxy. N.B. this is defined as (following astropy): 1 - b/a, not sqrt(1 - b^2/a^2), where b/a is the axial ratio.

angle :: scalar The counter-clockwise rotation angle in degrees. At an angle of 0, the semimajor and semiminor axes of the galaxy are aligned with the x- and y-axes, respectively.

Returns

profile :: function Sersic-index profile function.

class castor_etc.sources.Source(profile, init_dimensions=True, check_profile=True)

Bases: castor_etc.spectra.SpectrumMixin, castor_etc.spectra.NormMixin

Base (abstract) class for astronomical sources.

Initialization

Abstract method for all Source subclasses.

Parameters

profile :: function with a header of (x, y, aper_center) -> (2D array of floats)

`profile` is a function that describes how the flux or surface brightness of
the source varies as a function of x- & y-axis distance (in arcsec) from the
center of the source relative to the flux at the source's center.

The function signature for `profile` must have exactly 3 positional arguments,
`(x, y, aper_center)`, and return an array of floats.
  - `x` and `y` are 2D arrays representing the angular distance, in arcsec,
  of each pixel from the aperture's center,
  - `aper_center` is a 2-element 1D array of floats representing the x- and y-
  coordinates of the aperture's center relative to the source's center,
  respectively.

Given these three arguments, the `profile` function should return a 2D array
of the same shape as `x` and `y`, where each element is the flux at that pixel
relative to the flux at the center of the source (not aperture). It may be
helpful to look at how some of the predefined profiles are implemented (e.g.,
`Profiles.ellipse`).

init_dimensions :: bool If True, initialize attributes related to the source’s dimensions (i.e., a, b, dist, angle_a, angle_b, rotation) to None. If False, do not initialize these attributes.

check_profile :: bool If True, run some basic tests to check that the given profile accepts the correct input types and returns the correct output types.

Attributes

profile :: function with a header of (x, y, aper_center) -> (2D array of floats) The 2D profile function specifying how the flux changes as a function of pixel coordinates.

wavelengths, spectrum :: None (for now) In the future, these will be 1D arrays characterizing the spectrum of the source.

Returns

Instance of a base Source object

copy(): Convenience method for creating a deep copy of the Source object.

Parameters

None

Returns

Source_copy :: Source object The deep copy of the Source object.

class castor_etc.sources.PointSource

Bases: castor_etc.sources.Source

Point source.

Initialization

Generate a circular point source (e.g., a star).

Attributes

profile :: None The 2D profile function specifying how the flux changes as a function of x- & y-axis distance (in arcsec) from the center of the source. This is set to None and will be handled in the Photometry object instead (where the “profile” of a point source is the telescope’s PSF). TODO: in the future, use the telescope’s sampled PSF to generate a profile here (or in photometry.py) instead of using a Gaussian in photometry.py (currently setting the profile in photometry.py only because we are assuming PSF is Gaussian with FWHM = telescope FWHM)

angle_a, angle_b :: astropy.Quantity angles The angles subtended by the circular point source’s radius. Since this source is circular, these will be equal. By default, these are both set to 1e-12 arcsec to approximate a very small source. Although required attributes, the actual values of these do not matter too much since PointSource objects use the encircled energy (which is dependent on the telescope’s PSF) rather than surface brightness to perform photometry calculations.

area :: astropy.Quantity angle The angular area subtended by the point source. Although a required attribute, the exact value of this does not matter in photometry calculations.

rotation :: float The CCW rotation of the source relative to the x-axis, in radians. Since this is a circular point source, this rotation does not have any effect and is set to zero for simplicity.

a, b :: None The physical semimajor and semiminor axis lengths of the circular point source. These are set to None since they are not required attributes.

dist :: None The distance to the source. This is set to None since it is not a required attribute.

passband :: None The passband of the custom surface brightness profile. This is set to None since this source is not a CustomSource.

ra :: astropy.Quantity angle Right ascension of the target in degree

dec :: astropy.Quantity angle Declination of the target in degree

srch_Gmax :: int or float Maximum Gaia G magnitude for Gaia catalog query (applies to both the target and the guide stars)

srch_nmax :: int Maximum Gaia sources to include.

srch_rad :: astropy.Quantity Search radius, in degree, for Gaia catalog query (applies to both the target and the guide stars)

Teff :: int or float Effective temperature of the target in Kelvin

Gmag :: int or float Gaia G magnitude of the target used to query the Gaia catalog

logg :: int or float log(g) value of the target

radius :: int or float radius of the target

metallicity :: int or float metallicity of the target

Bpmag :: int or float Gaia BP magnitude of the target

Rpmag :: int or float Gaia RP magnitude of the target

stellar_model_grid :: str Stellar model grid, ‘ATLAS9’ or ‘BTSettl’, for selecting spectrum of the source according to the interpolated stellar atmosphere model.

bkg_sources :: bool If True, then background Gaia sources are included during the transit simulation calculation. If False, nmax is set to 1.

fov :: int or float Full width FoV in degree

fov_pa :: astropy.Quantity Field of view position angle

ccd_dim :: int list CCD dimesions adopted from TelescopeObj

gaia :: dict of array Contains queried gaia sources’ parameters

Returns

PointSource instance

class castor_etc.sources.ExtendedSource(angle_a=None, angle_b=None, a=None, b=None, dist=None, rotation=0.0, profile='uniform', exponential_scale_lengths=None)

Bases: castor_etc.sources.Source

Extended source.

Initialization

Generate an extended source given either:

the angles subtended by the source’s semimajor (angle_a) and semiminor (angle_b) axes,
the physical semimajor (a) and semiminor (b) axis lengths and distance (dist) to the source.

The dimensions of the extended source (i.e., the quantities in the list above) will be used to calculate the source’s surface brightness. See the profile parameter below for more details. In general, the smaller the extended source (i.e., determined by angle_a and angle_b), the higher the surface brightness assuming the source spectrum is normalized to the same value and everything else is equal.

Note that users should use the GalaxySource class to generate galaxies.

Parameters

angle_a, angle_b :: int or float or astropy.Quantity The angle subtended by the extended source’s semimajor and semiminor axes, respectively. If scalars, they are assumed to be in arcsec. If given, a, b, and dist must all be None. If not given, a, b, and dist must all be provided.

a, b :: int or float or astropy.Quantity The physical semimajor and semiminor axes of the extended source, respectively. If scalars, they are assumed to be in units of kpc. If given, dist must also be provided and angle_a & angle_b must both be None. If not given, angle_a and angle_b must both be provided. Internally, these values along with the distance will be used to calculate the angle_a and angle_b attributes.

dist :: int or float or astropy.Quantity The distance to the source. If a scalar, dist is assumed to be in units of kpc. If given, a & b must also be provided and angle_a & angle_b must both be None. If not given, angle_a & angle_b must both be provided. Internally, these values along with the semimajor and semiminor axis lengths will be used to calculate the angle_a and angle_b attributes.

rotation :: int or float The counter-clockwise (CCW) rotation of the source’s semimajor axis relative to the x-axis, in degrees. At a rotation of 0 degrees, the source’s semimajor axis is along the x-axis and the source’s semiminor axis is along the y-axis.

profile :: “uniform” or “exponential” or a function with a header of profile(x, y, aper_center) - If “uniform”, the source will be generated as an ellipse with uniform surface brightness. The dimensions (e.g., angle_a and angle_b) supplied will be used to calculate the surface brightness of the source and the surface brightness drops to zero outside this ellipse. - If “exponential”, the source will be generated as an ellipse with an exponentially decaying surface brightness profile; the scale lengths for this profile is specified by the exponential_scale_lengths parameter. The dimensions (e.g., angle_a and angle_b) supplied will be used to calculate the surface brightness of the source but this surface brightness will not immediately drop to zero outside the ellipse; rather, the surface brightness exponentially drops off according to the specified scale lengths. exponential_scale_lengths must be provided if profile is “exponential”. - Otherwise, this must be a function with 3 positional parameters that describes the surface brightness of the source relative to the brightness at the source’s centre, as a function of x- & y-axis distance (in arcsec) from the center of the source. - x and y are 2D arrays representing the angular distance, in arcsec, of each pixel from the aperture’s center, - aper_center is a 2-element 1D array of floats representing the x- and y- coordinates of the aperture’s center relative to the source’s center, respectively.

exponential_scale_lengths :: 2-element 1D `astropy.Quantity` array or
                             2-element 1D array of floats or or None
  The (a0, b0) "scale-lengths" along the ellipse's semimajor and semiminor
  axes, respectively. That is, the surface brightness at the elliptical level
  curve defined by a0 and b0 is a factor of e less than the surface brightness
  at the center of the ellipse. If scalars, a0 and b0 are assumed to be in
  arcsec.

Attributes

profile :: function with a header of (x, y, aper_center) -> (2D array of floats) The 2D profile function specifying how the surface brightness changes as a function of pixel coordinates.

a, b :: astropy.Quantity lengths or None The physical semimajor and semiminor axis lengths of the extended source. If parameters a and b were not specified, these attributes will be None.

dist :: astropy.Quantity lengths or None The distance to the source. If the parameter dist was not specified, this attribute will be None.

angle_a, angle_b :: astropy.Quantity angles The angles subtended by the extended source’s semimajor and semiminor axes.

area :: astropy.Quantity angle The angular area subtended by the extended source.

rotation :: float The CCW rotation of the source’s semimajor axis relative to the x-axis, in radians. At a rotation of 0 radians, the source’s semimajor axis is along the x-axis and the source’s semiminor axis is along the y-axis.

passband :: None The passband of the custom surface brightness profile. This is set to None since this source is not a CustomSource.

Returns

ExtendedSource instance

class castor_etc.sources.GalaxySource(r_eff, n, axial_ratio, rotation=0.0)

Bases: castor_etc.sources.Source

A galaxy.

Initialization

Generate a galaxy with a specific effective radius (here, equal to the semimajor axis a), Sersic index (n), and axial ratio (b/a).

The dimensions of the galaxy (i.e., the semimajor and semiminor axis) will be used to calculate its surface brightness when doing photometry calculations and is not a hard limit on the galaxy’s physical size (i.e., the surface brightness will not immediately drop to zero outside of the ellipse defined by the semimajor/semiminor axis). In general, the smaller the galaxy, the higher the surface brightness assuming the source spectrum is normalized to the same value and everything else is equal.

Also see the ExtendedSource class for other profiles (e.g., uniform, exponential decay with scale lengths).

Parameters

r_eff :: int or float or astropy.Quantity angle Effective (half-light) radius. If a scalar, r_eff is assumed to be in arcsec. This is also known as the half-light radius, i.e., the radius within which half the light of the galaxy is contained.

Following the `astropy` convention, `r_eff` is equal to the semimajor axis
(a); the semiminor axis (b) is calculated as
`axial_ratio * r_eff = b/a * a = b`.

n :: int or float Sersic index of the galaxy.

axial_ratio :: int or float The ratio of the semiminor axis (b) to the semimajor axis (a). This must be a number between (0, 1].

rotation :: int or float The counter-clockwise (CCW) rotation of the source’s semimajor axis relative to the x-axis, in degrees. At a rotation of 0 degrees, the source’s semimajor axis is along the x-axis and the source’s semiminor axis is along the y-axis.

Attributes

profile :: function with a header of (x, y, aper_center) -> (2D array of floats) The 2D profile function specifying how the surface brightness changes as a function of x- & y-axis distance (in arcsec) from the center of the source. In this case, it is a Sersic profile.

angle_a, angle_b :: astropy.Quantity angles The angles subtended by the extended source’s semimajor and semiminor axes. These attributes were calculated from the given r_eff and axial_ratio.

Following the `astropy` convention, `angle_a` is equal to `r_eff`, and
`angle_b` is calculated as `axial_ratio * r_eff = b/a * a = b`.

area :: astropy.Quantity angle The angular area subtended by the extended source.

rotation :: float The CCW rotation of the source’s semimajor axis relative to the x-axis, in radians. At a rotation of 0 radians, the source’s semimajor axis is along the x-axis and the source’s semiminor axis is along the y-axis.

a, b :: None The physical semimajor and semiminor axis lengths of the galaxy. These are set to None since they are not required attributes.

dist :: None The distance to the source. This is set to None since it is not a required attribute.

passband :: None The passband of the custom surface brightness profile. This is set to None since this source is not a CustomSource.

Returns

GalaxySource instance

class castor_etc.sources.CustomSource(profile_filepath, passband, center=None, px_scale_unit=u.deg)

Bases: castor_etc.sources.Source

A source with a custom surface brightness profile from a FITS file.

Initialization

Create a source with a custom surface brightness profile from a FITS file. The FITS file should be an image that contains, at each pixel, the electron/s induced by the source in the given passband; the data should not contain any NaNs/infs. These data will be linearly interpolated to a given telescope’s pixel scale when doing photometry calculations. Note that any user-requested values outside the given data’s extent will be set to zero.

This CustomSource class is useful if you want to bypass the internal source surface brightness profile and spectrum generation while using the ETC’s other functionality (e.g., aperture photometry, sky background estimation, etc.).

Parameters

profile_filepath :: str The path to the FITS file containing the surface brightness profile of the source.

passband :: str A valid Telescope passband name (e.g., “uv”, “u”, “g”). The valid passband names depend on the specific Telescope instance.

center :: 2-tuple of scalars or astropy.coordinates.SkyCoord object or None The (x, y) center of the source. If scalars, they are assumed to be in pixel coordinates. If None, use the center of the image as the center of the source.

px_scale_unit :: astropy.units.Unit The unit of the pixel scale (i.e., the “CUNIT” or “CUNIT1”/”CUNIT2” header keyword).

Attributes

profile :: function with a header of (x, y, aper_center) -> (2D array of floats) The 2D profile function specifying how the surface brightness changes as a function of x- & y-axis distance (in arcsec) from the center of the source. For this source, the x and y arrays must represent points on a regular, rectangular grid (i.e., they should be generated via python np.meshgrid(..., indexing="xy") ).

passband :: str The passband of the custom surface brightness profile.

angle_a, angle_b :: None The angles subtended by the extended source’s semimajor and semiminor axes. These are set to None since they are irrelavant for a custom source.

area :: None The angular area subtended by the extended source. This is set to None since it is irrelavant for a custom source.

rotation :: None The CCW rotation of the source’s semimajor axis relative to the x-axis, in radians. At a rotation of 0 radians, the source’s semimajor axis is along the x-axis and the source’s semiminor axis is along the y-axis. This is set to None since it is irrelavant for a custom source.

a, b :: None The physical semimajor and semiminor axis lengths of the galaxy. These are set to None since they are irrelavant for a custom source.

dist :: None The distance to the source. This is set to None since it is irrelavant for a custom source.

Returns

CustomSource instance

castor_etc.sources

Sources

Module Contents

Classes

API

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Attributes

Returns

Parameters

Returns

Attributes

Returns

Parameters

Attributes

Returns

Parameters

Attributes

Returns

Parameters

Attributes

Returns

`castor_etc.sources`