pynrc.obs_hci

class pynrc.obs_hci(sp_sci, sp_ref, distance, wfe_ref_drift=10, wfe_roll_drift=0, offset_list=None, wind_mode='WINDOW', xpix=320, ypix=320, disk_hdu=None, verbose=False, **kwargs)[source]

Bases: pynrc.obs_nircam.nrc_hci

NIRCam coronagraphic observations

Subclass of the nrc_hci instrument class used to observe stars (plus exoplanets and disks) with either a coronagraph or direct imaging.

The main concept is to generate a science target of the primary source along with a simulated disk structure. Planets are further added to the astronomical scene. A separate reference source is also defined for PSF subtraction, which contains a specified WFE. A variety of methods exist to generate slope images and analyze the PSF-subtracted results via images and contrast curves.

Parameters
  • sp_sci (pysynphot.spectrum) – A pysynphot spectrum of science target (e.g., central star). Should already be normalized to the apparent flux.

  • sp_ref (pysynphot.spectrum or None) – A pysynphot spectrum of reference target. Should already be normalized to the apparent flux.

  • distance (float) – Distance in parsecs to the science target. This is used for flux normalization of the planets and disk.

  • wfe_ref_drift (float) – WFE drift in nm between the science and reference targets. Expected values are between ~3-10 nm.

  • wfe_roll_drift (float) – WFE drift in nm between science roll angles. Default=0.

  • wind_mode (str) – ‘FULL’, ‘STRIPE’, or ‘WINDOW’

  • xpix (int) – Size of the detector readout along the x-axis. The detector is assumed to be in window mode unless the user explicitly sets wind_mode=’FULL’.

  • ypix (int) – Size of the detector readout along the y-axis. The detector is assumed to be in window mode unless the user explicitly sets wind_mode=’FULL’.

  • disk_hdu (HDUList) – A model of the disk in photons/sec. This requires header keywords PIXSCALE (in arcsec/pixel) and DISTANCE (in pc).

Attributes Summary

planets

Planet info (if any exists)

wfe_ref_drift

WFE drift (nm) of ref obs relative to sci obs

Methods Summary

add_planet([atmo, mass, age, entropy, xy, …])

Insert a planet into observation.

kill_planets()

Remove planet info

calc_contrast([hdu_diff, roll_angle, nsig, …])

Create contrast curve.

gen_disk_image([PA_offset, use_cmask])

Create image of just disk.

gen_planets_image([PA_offset, quick_PSF, …])

Create image of just planets.

gen_roll_image([PA1, PA2, zfact, …])

Make roll-subtracted image.

planet_spec([Av])

Exoplanet spectrum.

saturation_levels([ngroup, do_ref, image])

Saturation levels

star_flux([fluxunit, sp])

Stellar flux.

Methods Documentation

add_planet(atmo='hy3s', mass=10, age=100, entropy=10, xy=None, rtheta=None, runits='AU', Av=0, renorm_args=None, sptype=None, accr=False, mmdot=None, mdot=None, accr_rin=2, truncated=False)[source]

Insert a planet into observation.

Add exoplanet information that will be used to generate a point source image using a spectrum from Spiegel & Burrows (2012). Use self.kill_planets() to delete them.

Coordinate convention is for +N up and +E to left.

Parameters
  • atmo (str) – A string consisting of one of four atmosphere types: [‘hy1s’, ‘hy3s’, ‘cf1s’, ‘cf3s’].

  • mass (int) – Number 1 to 15 Jupiter masses.

  • age (float) – Age in millions of years (1-1000).

  • entropy (float) – Initial entropy (8.0-13.0) in increments of 0.25

  • sptype (str) – Instead of using a exoplanet spectrum, specify a stellar type.

  • renorm_args (dict) – Pysynphot renormalization arguments in case you want very specific luminosity in some bandpass. Includes (value, units, bandpass).

  • Av (float) – Extinction magnitude (assumes Rv=4.0) of the exoplanet due to being embedded in a disk.

  • xy (tuple, None) – (X,Y) position in sky coordinates of companion (N up, E left).

  • rtheta (tuple, None) – Radius and position angle relative to stellar position. Alternative to xy keyword

  • runits (str) – What are the spatial units? Valid values are ‘AU’, ‘asec’, or ‘pix’.

  • accr (bool) – Include accretion? default: False

  • mmdot (float) – From Zhu et al. (2015), the Mjup^2/yr value. If set to None then calculated from age and mass.

  • mdot (float) – Or use mdot (Mjup/yr) instead of mmdot.

  • accr_rin (float) – Inner radius of accretion disk (units of RJup; default: 2)

  • truncated (bool) – Full disk or truncated (ie., MRI; default: False)?

kill_planets()[source]

Remove planet info

calc_contrast(hdu_diff=None, roll_angle=10, nsig=1, exclude_disk=True, exclude_planets=True, no_ref=False, func_std=<function std>, **kwargs)[source]

Create contrast curve.

Generate n-sigma contrast curve for the current observation settings. Make sure that MULTIACCUM parameters are set for both the main class (self.update_detectors()) as well as the reference target class (self.nrc_ref.update_detectors()).

Parameters
  • hdu_diff (HDUList) – Option to pass an already pre-made difference image.

  • roll_angle (float) – Telescope roll angle (deg) between two observations. If set to 0 or None, then only one roll will be performed. If value is >0, then two rolls are performed, each using the specified MULTIACCUM settings (doubling the effective exposure time).

  • nsig (float) – n-sigma contrast curve.

  • exclude_disk (bool) – Ignore disk when generating image?

  • exclude_planets (bool) – Ignore planets when generating image?

  • no_ref (bool) – Exclude reference observation. Subtraction is then Roll1-Roll2.

  • func_std (func) – The function to use for calculating the radial standard deviation.

Keyword Arguments
  • zfact (float) – Zodiacal background factor (default=2.5)

  • exclude_noise (bool) – Don’t add random Gaussian noise (detector+photon)?

  • ideal_Poisson (bool) – If set to True, use total signal for noise estimate, otherwise MULTIACCUM equation is used.

  • opt_diff (bool) – Optimal reference differencing (scaling only on the inner regions)

Returns

tuple – Three arrays in a tuple: the radius in arcsec, n-sigma contrast, and n-sigma magnitude sensitivity limit (vega mag).

gen_disk_image(PA_offset=0, use_cmask=False, **kwargs)[source]

Create image of just disk.

Generate a (noiseless) convolved image of the disk at some PA offset. The PA offset value will rotate the image CCW. Image units of e-/sec.

Coordinate convention is for N up and E to left.

Parameters
  • PA_offset (float) – Rotate entire scene by some position angle. Positive values are counter-clockwise from +Y direction. Corresponds to instrument aperture PA.

  • use_cmask (bool) – Use the coronagraphic mask image to attenuate disk regions getting obscurred by a corongraphic mask feature

gen_planets_image(PA_offset=0, quick_PSF=True, use_cmask=False, **kwargs)[source]

Create image of just planets.

Use info stored in self.planets to create a noiseless slope image of just the exoplanets (no star).

Coordinate convention is for +N up and +E to left.

Parameters
  • PA_offset (float) – Rotate entire scene by some position angle. Positive values are counter-clockwise from +Y direction. Corresponds to instrument aperture PA.

  • quick_PSF (bool) – Rather than generate a spectrum-weighted PSF, use the cached PSF scaled by the photon count through the bandpass. Resulting PSFs are less accurate, but generation is much faster. Default is True.

  • use_cmask (bool) – Use the coronagraphic mask image to determine if any planet is getting obscurred by a corongraphic mask feature

gen_roll_image(PA1=0, PA2=10, zfact=None, oversample=None, no_ref=False, opt_diff=True, fix_sat=False, ref_scale_all=False, **kwargs)[source]

Make roll-subtracted image.

Create a final roll-subtracted slope image based on current observation settings. Coordinate convention is for N up and E to left.

Procedure:

  • Create Roll 1 and Roll 2 slope images (star+exoplanets+disk)

  • Create Reference Star slope image

  • Add noise to all images

  • Scale ref image

  • Subtract ref image from both rolls

  • De-rotate Roll 1 and Roll 2 to common coordinates

  • Average Roll 1 and Roll 2

Returns an HDUList of final image (N rotated upwards).

Parameters
  • PA1 (float) – Position angle of first roll position (clockwise, from East to West)

  • PA2 (float, None) – Position angle of second roll position. If set equal to PA1 (or to None), then only one roll will be performed. Otherwise, two rolls are performed, each using the specified MULTIACCUM settings (doubling the effective exposure time).

  • oversample (float) – Set oversampling of final image.

  • no_ref (bool) – Exclude reference observation. Subtraction is then Roll1-Roll2.

  • opt_diff (bool) – Optimal reference differencing (scaling only on the inner regions)

  • fix_sat (bool) – Calculate saturated regions and fix with median of nearby data.

  • ref_scale_all (bool) – Normally we just use the science and reference PSFs to calculate scaling. However, if there is an unresolved companion or disk emission close to the star, then we won’t get the correct scale factor for optimal reference subtraction. Instead, this option inludes disk and companions for calculating the reference scale factor.

Keyword Arguments
  • exclude_disk (bool) – Do not include disk in final image (for radial contrast), but still add Poisson noise from disk.

  • exclude_planets (bool) – Do not include planets in final image (for radial contrast), but still add Poisson noise from disk.

  • exclude_noise (bool) – Don’t add random Gaussian noise (detector+photon)

  • ideal_Poisson (bool) – If set to True, use total signal for noise estimate, otherwise MULTIACCUM equation is used.

  • quick_PSF (bool) – Rather than generate a spectrum-weighted PSF for planets, use the cached PSF scaled by the photon count through the bandpass. Resulting PSFs are slightly less accurate, but much faster. Default is True.

  • use_cmask (bool) – Use the coronagraphic mask image to attenuate planets or disk obscurred by a corongraphic mask feature.

  • zfact (float) – Zodiacal background factor (default=2.5)

  • ra (float) – Right ascension in decimal degrees

  • dec (float) – Declination in decimal degrees

  • thisday (int) – Calendar day to use for background calculation. If not given, will use the average of visible calendar days.

planet_spec(Av=0, **kwargs)[source]

Exoplanet spectrum.

Return the planet spectrum from Spiegel & Burrows (2012) normalized to distance of current target. Output is a pysynphot.spectrum.

Parameters

Av (float) – Extinction magnitude (assumes Rv=4.0).

Keyword Arguments
  • atmo (str) – A string consisting of one of four atmosphere types: [‘hy1s’, ‘hy3s’, ‘cf1s’, ‘cf3s’].

  • mass (float) – Number 1 to 15 Jupiter masses.

  • age (float) – Age in millions of years (1-1000).

  • entropy (float) – Initial entropy (8.0-13.0) in increments of 0.25

  • accr (bool) – Include accretion? Default: False.

  • mmdot (float) – From Zhu et al. (2015), the Mjup^2/yr value. If set to None then calculated from age and mass.

  • mdot (float) – Or use mdot (Mjup/yr) instead of mmdot.

  • accr_rin (float) – Inner radius of accretion disk (units of RJup; default: 2)

  • truncated (bool) – Full disk or truncated (ie., MRI; default: False)?

saturation_levels(ngroup=2, do_ref=False, image=None, **kwargs)[source]

Saturation levels

Create image showing level of saturation for each pixel. Saturation at different number of groups is possible with ngroup keyword. Returns an array the same shape as det_info.

Parameters
  • ngroup (int) – How many group times to determine saturation level? If this number is higher than the total groups in ramp, then a warning is produced. The default is ngroup=2, A value of 0 corresponds to the so-called “zero-frame,” which is the very first frame that is read-out and saved separately. This is the equivalent to ngroup=1 for RAPID and BRIGHT1 observations.

  • do_ref (bool) – Get saturation levels for reference soure instead of science

  • image (ndarray) – Rather than generating an image on the fly, pass a pre-computed slope image.

Keyword Arguments
  • quick_PSF (bool) – Rather than generate a spectrum-weighted PSF for planets, use the cached PSF scaled by the photon count through the bandpass. Resulting PSFs are slightly less accurate, but much faster. Default is True.

  • use_cmask (bool) – Use the coronagraphic mask image to attenuate planet or disk that is obscurred by a corongraphic mask feature.

  • zfact (float) – Zodiacal background factor (default=2.5)

  • ra (float) – Right ascension in decimal degrees

  • dec (float) – Declination in decimal degrees

  • thisday (int) – Calendar day to use for background calculation. If not given, will use the average of visible calendar days.

star_flux(fluxunit='counts', sp=None)[source]

Stellar flux.

Return the stellar flux in whatever units, such as vegamag, counts, or Jy.

Parameters
  • fluxunits (str) – Desired output units, such as counts, vegamag, Jy, etc. Must be a Pysynphot supported unit string.

  • sp (pysynphot.spectrum) – Normalized Pysynphot spectrum.