Utilities: Various constants and methods used by the Toolbox

pdrtpy.utils — utility subpackage for PDR Toolbox.

Submodules:

units — radiation field units, constants, and unit conversions paths — path and I/O helpers fits — FITS keyword utilities wcs — WCS and image array utilities helpers — general helpers

pdrtpy.utils.addkey(key, value, image)

Add a (FITS) keyword,value pair to the image header.

Parameters:

keystr

The keyword to add to the header.

valueany

The value for the keyword.

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to which to add the key,val.

pdrtpy.utils.check_units(input_unit, compare_to)

Check if the input unit is equivalent to another.

Parameters:

input_unitastropy.units.Unit, astropy.units.Quantity, or str

The unit to check.

compare_toastropy.units.Unit, astropy.units.Quantity, or str

The unit to check against.

Returns:

bool

True if the input unit is equivalent to compare unit, False otherwise.

pdrtpy.utils.comment(value, image)

Add a comment to an image header.

Parameters:

valuestr

The value for the comment.

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to which to add the comment.

pdrtpy.utils.convert_if_necessary(image)

Convert integrated intensity units if necessary.

Converts from \({\rm K~km~s}^{-1}\) to \({\rm erg~s^{-1}~cm^{-2}~sr^{-1}}\) by calling convert_integrated_intensity(). If no conversion is necessary, the image is returned unchanged.

Parameters:

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to convert. It must have a numpy.ndarray data member, astropy.units.Unit unit member or header BUNIT keyword with units \({\rm K~km~s}^{-1}\), and a header RESTFREQ keyword.

Returns:

astropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

An image with converted values and units.

pdrtpy.utils.convert_integrated_intensity(image, wavelength=None)

Convert integrated intensity from \({\rm K~km~s}^{-1}\) to \({\rm erg~s^{-1}~cm^{-2}~sr^{-1}}\).

Assumes \(B_\lambda d\lambda = 2kT/\lambda^3 dV\) where \(T dV\) is the integrated intensity in K km/s and \(\lambda\) is the wavelength. The derivation:

\[B_\lambda = 2 h c^2/\lambda^5 {1\over{exp[hc/\lambda k T] - 1}}\]

The integrated line is \(B_\lambda d\lambda\) and for \(hc/\lambda k T << 1\):

\[B_\lambda d\lambda = 2c^2/\lambda^5 \times (\lambda kT/hc)~d\lambda\]

The relationship between velocity and wavelength, \(dV = \lambda/c~d\lambda\), giving

\[B_\lambda d\lambda = 2\times10^5~kT/\lambda^3~dV,\]

with \(\lambda\) in cm, the factor \(10^5\) is to convert \(dV\) in \({\rm km~s}^{-1}\) to \({\rm cm~s}^{-1}\).

Parameters:

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to convert. It must have a numpy.ndarray data member, astropy.units.Unit unit member or header BUNIT keyword, and units must be K km/s.

wavelengthastropy.units.Quantity, optional

The wavelength of the observation. The default is to determine wavelength from the image header RESTFREQ keyword.

Returns:

astropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

An image with converted values and units.

pdrtpy.utils.dataminmax(image)

Set the data maximum and minimum in image header.

Parameters:

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to which to add the key,val.

pdrtpy.utils.dropaxis(w)

Drop the first single dimension axis from a World Coordinate System.

Returns the modified WCS if it had a single dimension axis or the original WCS if not.

Parameters:

wastropy.wcs.WCS

A WCS.

Returns:

astropy.wcs.WCS

pdrtpy.utils.firstkey(d)

Return the “first” key in a dictionary.

Parameters:

ddict

The dictionary.

pdrtpy.utils.fliplabel(label)

Given a label with a numerator and denominator separated by '/', return the reciprocal label.

For example, if the input label is '(x+y)/z' return 'z/(x+y)'. This method simply looks for the '/' and swaps the substrings before and after it.

Parameters:

labelstr

The label to flip.

Returns:

str

The reciprocal label.

Raises:

ValueError

If the input label has no '/'.

pdrtpy.utils.float_formatter(quantity, precision)

Format a quantity as a LaTeX string with the given number of significant figures.

Parameters:

quantityastropy.units.Quantity

The quantity to format.

precisionint

The number of significant figures.

Returns:

str

pdrtpy.utils.get_rad(key)

Get radiation field symbol (LaTeX) given radiation field unit.

If key is unrecognized, 'FUV' is returned.

Parameters:

keystr or astropy.units.Unit

Input field unit name, e.g. 'Habing', 'Draine'.

Returns:

str

LaTeX string for the radiation field symbol, e.g. \(G_0\), \(\chi\).

pdrtpy.utils.get_table(filename, format='ipac', path=None, **kwargs)

Return an astropy Table read from the input filename.

Parameters:

filenamestr

Input filename, no path.

formatstr, optional

File format. Default: "ipac".

pathstr, optional

Path to filename relative to models directory. Default of None means look in the tables directory.

**kwargsdict

Additional arguments to pass to Table.read, e.g. header_start, data_start.

Returns:

astropy.table.Table

pdrtpy.utils.get_testdata(filename)

Get fully qualified pathname to FITS test data file.

Parameters:

filenamestr

Input filename, no path.

pdrtpy.utils.get_xy_from_wcs(data, quantity=False, linear=False)

Get the x,y axis vectors from the WCS of the input image.

Parameters:

dataastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The input image.

quantitybool, optional

If True, return the arrays as astropy.units.Quantity. If False, return numpy.ndarray. Default: False.

linearbool, optional

If True, returned arrays are in linear space; if False, in log space. Default: False.

Returns:

numpy.ndarray or astropy.units.Quantity

The axis values as arrays. Values are center of pixel.

pdrtpy.utils.has_single_axis(w)

Check if the input WCS has any single dimension axes.

Parameters:

wastropy.wcs.WCS

A WCS.

Returns:

bool

True if the input WCS has any single dimension axes, False otherwise.

pdrtpy.utils.history(value, image)

Add a history record to an image header.

Parameters:

valuestr

The value for the history record.

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to which to add the HISTORY.

pdrtpy.utils.is_even(number)

Check if number is even.

Parameters:

numberfloat

A number.

Returns:

bool

True if even, False otherwise.

pdrtpy.utils.is_image(image)

Check if a Measurement is an image.

To be an image it must have a header with axes keywords and a WCS. This is to distinguish Measurements that have a data array with more than one member from a true image.

Parameters:

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to check. It must have a numpy.ndarray data member and astropy.units.Unit unit member or a header BUNIT keyword.

Returns:

bool

True if it is an image, False otherwise.

pdrtpy.utils.is_odd(number)

Check if number is odd.

Parameters:

numberfloat

A number.

Returns:

bool

True if odd, False otherwise.

pdrtpy.utils.is_rad(input_unit)

pdrtpy.utils.is_ratio(identifier)

Is the identifier a ratio (as opposed to an intensity).

Returns:

bool

pdrtpy.utils.mask_union(arrays)

Return the union mask (logical OR) of the input masked arrays.

This is useful when doing arithmetic on images that don’t have identical masks and you want the most restrictive mask.

Parameters:

arraysnumpy.ma.masked_array

Masked arrays to unionize.

Returns:

mask

pdrtpy.utils.model_dir()

Project model directory, including trailing slash.

Returns:

str

pdrtpy.utils.now()

Return a string representing the current date and time in ISO format.

Returns:

str

pdrtpy.utils.rescale_axis_units(x, from_unit, from_ctype, to_unit, loglabel=True)

Rescale axis units and return updated axis values and label.

Parameters:

xastropy.units.Quantity

Axis values.

from_unitstr

Original unit string.

from_ctypestr

Original CTYPE string.

to_unitstr or None

Target unit string, or None to keep original.

loglabelbool, optional

If True, prefix label with 'log(...)'. Default: True.

Returns:

tuple

(x, xlabel) with rescaled axis values and axis label string.

pdrtpy.utils.root_dir()

Project root directory, including trailing slash.

Returns:

str

pdrtpy.utils.root_path()

Project root directory as path.

Returns:

pathlib.Path

pdrtpy.utils.setkey(key, value, image)

Set the value of an existing keyword in the image header.

Parameters:

keystr

The keyword to set in the header.

valueany

The value for the keyword.

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to which to add the key,val.

pdrtpy.utils.signature(image)

Add AUTHOR and DATE keywords to the image header.

Author is 'PDR Toolbox', date as returned by now().

Parameters:

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to which to add the key,val.

pdrtpy.utils.squeeze(image)

Remove single-dimensional entries from image data and WCS.

Parameters:

imageastropy.nddata.CCDData or Measurement

The image to convert. It must have a numpy.ndarray data member and astropy.units.Unit unit member.

Returns:

astropy.nddata.CCDData or Measurement

An image with single axes removed (same type as input).

pdrtpy.utils.table_dir()

Project ancillary tables directory, including trailing slash.

Returns:

str

pdrtpy.utils.testdata_dir()

Project test data directory, including trailing slash.

Returns:

str

pdrtpy.utils.to(unit, image)

Convert the image values to another unit.

While generally this is intended for converting radiation field strength maps between Habing, Draine, cgs, etc, it will work for any image that has a unit member variable. So, e.g., it would work to convert density from \({\rm cm^{-3}}\) to \({\rm m^{-3}}\). If the input image is a Measurement, its uncertainty will also be converted.

Parameters:

unitstr or astropy.units.Unit

The unit to convert to.

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to convert. It must have a numpy.ndarray data member and astropy.units.Unit unit member.

Returns:

astropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

An image with converted values and units.

pdrtpy.utils.toDraine(image)

Convert a radiation field strength image to Draine units (\(\chi\)).

\({\rm 1~Draine = 2.72\times10^{-3}~erg~s^{-1}~cm^{-2}}\)

between 6eV and 13.6eV (912-2066 \(\unicode{xC5}\)). See Weingartner and Draine 2001, ApJS, 134, 263, section 4.1

Parameters:

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to convert. It must have a numpy.ndarray data member and astropy.units.Unit unit member.

Returns:

astropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

An image with converted values and units.

pdrtpy.utils.toHabing(image)

Convert a radiation field strength image to Habing units \((G_0)\).

\({\rm G_0 \equiv 1~Habing = 1.6\times10^{-3}~erg~s^{-1}~cm^{-2}}\)

between 6eV and 13.6eV (912-2066 \(\unicode{xC5}\)). See Weingartner and Draine 2001, ApJS, 134, 263, section 4.1

Parameters:

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to convert. It must have a numpy.ndarray data member and astropy.units.Unit unit member.

Returns:

astropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

An image with converted values and units.

pdrtpy.utils.toMathis(image)

Convert a radiation field strength image to Mathis units.

\({\rm 1~Mathis = 1.81\times10^{-3}~erg~s^{-1}~cm^{-2}}\)

between 6eV and 13.6eV (912-2066 \(\unicode{xC5}\)). See Weingartner and Draine 2001, ApJS, 134, 263, section 4.1

Parameters:

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to convert. It must have a numpy.ndarray data member and astropy.units.Unit unit member.

Returns:

astropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

An image with converted values and units.

pdrtpy.utils.tocgs(image)

Convert a radiation field strength image to \({\rm erg~s^{-1}~cm^{-2}}\).

Parameters:

imageastropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

The image to convert. It must have a numpy.ndarray data member and astropy.units.Unit unit member.

Returns:

astropy.io.fits.ImageHDU, astropy.nddata.CCDData, or Measurement

An image with converted values and units.

pdrtpy.utils.warn(cls, msg)

Issue a warning.

Parameters:

clsclass

The calling class.

msgstr

The warning message.