Utils API¶

class pylanetary.utils.core.Body(name, epoch=None, location=None)¶

instantiate object with attributes from yaml file of matching string name.

Example usage: from pylanetary.utils import Body jup = Body(‘Jupiter’)

jup.app_dia_max, jup.app_dia_min output> (<Quantity 50.1 arcsec>, <Quantity 30.5 arcsec>)

print(‘Jupiter is currently’, jup.distance, ‘ AU from the Earth with apparent size ‘, jup.app_dia, ‘ today = ‘, jup.epoch_datetime) output> Jupiter is currently 5.93796102228318 AU AU from the Earth with apparent size 33.2009 arcsec today = 2023-04-26 16:32:54

Parameters:

name (str, required.) – Body name string, example “Jupiter” will load Jupiter.yaml
epoch (astropy.time.Time, optional.) – The epoch at which to retrieve the ephemeris of the body. If not set, the current time will be used.
location (str, optional.) – JPL Horizons observatory code. If not set, center of Earth will be used.

pylanetary.utils.core.I_over_F(observed_flux, bp, target_sun_dist, target_omega)¶

definition from Hammel et al 1989, DOI:10.1016/0019-1035(89)90149-8

Parameters:

observed_flux (float, required.) – [erg s-1 cm-2 um-1] flux of target
bp (np.array, required) – ([wls, trans]) [[um], [-]] the filter transmission function. does not matter if normalized or not.
target_sun_dist (float, required.) – [AU] distance between sun and target
target_omega (float, required.) – [sr] for unresolved object, solid angle of that object for resolved object, solid angle of one pixel

Returns:

float – [um] effective filter wavelength
float – I/F

Notes

sun_flux_earth agrees with Arvesen 1969 in H band, doi:10.1364/AO.8.002215
needs handling of astropy units

pylanetary.utils.core.beam_area(beamx, beamy)¶

Parameters:

beamx (float, required) – [arcsec]
beamy (float, required) – [arcsec]

Returns:

area of a Gaussian beam

Return type:

float

pylanetary.utils.core.convolve_with_beam(data, beam, mode='gaussian')¶

Convolves input 2-D image with a Gaussian beam or an input PSF image

Parameters:

data (np.array, required.)
beam (float/int, 3-element array-like, np.array, or None, required.) – If float/int, this sets the fwhm [pixels] of either Airy disk or circular Gaussian beam, depending on “mode” parameter. If 3-element array-like, those are (fwhm_x, fwhm_y, theta_deg) for a 2-D Gaussian [pixels, pixels, degrees]. In this case, “Airy” mode not supported. if np.array of size > 3, assumes input PSF image if None or 0.0, simply returns original data
mode (str, optional, default "gaussian") – options “gaussian”, “airy”; what beam shape to use. Case insensitive. “airy” only accepts beam of dtype float or 1-element array-like (i.e., beam must be circular). this parameter has no effect if beam is a 2-D array.

Returns:

beam-convolved data

Return type:

np.array

pylanetary.utils.core.fourier_deconvolve(data, psf, psf_desired, gamma=0.0003)¶

Reproducing Pat Fry’s Fourier deconvolution method. see also Cunningham and Anthony.

Parameters:

data (np.array, required.) – must be square. needs odd shape
psf (np.array, required.) – must be square. needs odd shape
psf_desired (np.array, required.) – must have same shape as psf
gamma (float, optional, default 3e-4) – Tikhonov regularization parameter. prevents zeros in the denominator.

Returns:

deconvolved data

Return type:

np.array

pylanetary.utils.core.inverse_planck(B, freq)¶

Parameters:

B (float, required) – [Jy/sr] flux density
freq (float, required) – [GHz] frequency

Returns:

[K] brightness temperature

Return type:

float

pylanetary.utils.core.inverse_rayleigh_jeans(B, freq)¶

Rayleigh-Jeans approximation to inverse_planck()

Parameters:

B (float, required) – [Jy/sr] flux density
freq (float, required) – [GHz] frequency

Returns:

[K] brightness temperature

Return type:

float

pylanetary.utils.core.jybm_to_jysr(I, beamx, beamy)¶

Parameters:

I (float, required) – [Jy/beam] flux density
beamx (float, required) – [arcsec]
beamy (float, required) – [arcsec]

Returns:

[Jy/sr] flux density

Return type:

float

pylanetary.utils.core.jybm_to_tb(I, freq, beamx, beamy)¶

Parameters:

I (float, required) – [Jy/beam] flux density
freq (float, required) – [GHz] frequency
beamx (float, required) – [arcsec]
beamy (float, required) – [arcsec]

Returns:

[K] brightness temperature

Return type:

float

References

science.nrao.edu/facilities/vla/proposing/TBconv

Notes

uses the Rayleigh-Jeans approximation

pylanetary.utils.core.jysr_to_jybm(I, beamx, beamy)¶

Parameters:

I (float) – [Jy/sr] flux density
beamx (float, required) – [arcsec]
beamy (float, required) – [arcsec]

Return type:

[Jy/beam] flux density

pylanetary.utils.core.planck(tb, freq)¶

Parameters:

tb (float, required) – [K] brightness temperature
freq (float, required) – [GHz] frequency

Returns:

[Jy/sr] flux density

Return type:

float

pylanetary.utils.core.rayleigh_criterion(wl, d)¶

Parameters:

wl (float, required) – [m] wavelength
d (float, required) – [m] diameter of telescope

Returns:

[arcsec] Diffraction limit of a circular aperture

Return type:

float

pylanetary.utils.core.rayleigh_jeans(tb, freq)¶

Rayleigh-Jeans approximation to planck()

Parameters:

tb (float, required) – [K] brightness temperature
freq (float, required) – [GHz] frequency

Returns:

[Jy/sr] flux density

Return type:

float

pylanetary.utils.core.rebin(arr, z)¶

simple integer binning of numpy array in two dimensions

Parameters:

arr (np.array, required)
z (int, required.) – factor to multiply array size by. typically z<1 i.e., this is ndimage.zoom() for z<1

Returns:

2-D numpy array of shape arr.shape * z

Return type:

np.array

Notes

use this instead of ndimage.zoom for z < 1

pylanetary.utils.core.solar_spectrum()¶

Load and return Gueymard solar standard spectrum from 0 to 1000 um

References

https://doi.org/10.1016/j.solener.2003.08.039 accessed at https://www.nrel.gov/grid/solar-resource/spectra.html

Returns:

np.array – array of astropy Quantities. [um] wavelength
np.array – array of astropy Quantities. solar flux [erg s-1 cm-2 um-1]

pylanetary.utils.core.solid_angle(dS, d)¶

Approximate solid angle of small facet https://en.wikipedia.org/wiki/Solid_angle

Parameters:

dS (float, required) – [dist^2] flat area of facet
d (float, required) – [dist] distance to facet

Returns:

[sr] solid angle of facet

Return type:

float

Example

a = 210 #km, Proteus average radius d = 30 * 1.496e8 #distance to Neptune in km solid_angle(3.14*a**2, d)

pylanetary.utils.core.tb_to_jybm(Tb, freq, beamx, beamy)¶

from science.nrao.edu/facilities/vla/proposing/TBconv: I in Jy/bm, freq in GHz, returns tb in Kelvin

Parameters:

Tb (float, required) – [K] float or array-like, brightness temperature
freq (float, required) – [GHz] float or array-like, frequency
beamx (float, required) – [arcsec] float, FWHM of Gaussian beam in x direction
beamy (float, required) – [arcsec] float, FWHM of Gaussian beam in y direction