utils — Generic (CASA-independent) utilities module.

This module contains utility functions that do NOT rely on CASA.

class admit.util.utils.Dtime(label='.', report=True)

Class to help measuring the wall clock time between tagged events Typical usage: dt = Dtime() ... dt.tag(‘a’) ... dt.tag(‘b’)

Methods

end()
get_mem()	Read memory usage info from /proc/pid/status Return Virtual and Resident memory size in MBytes.
reset([report])
show()
tag(mytag)
time()	pick the actual OS routine that returns some kind of timer

end()

get_mem()

Read memory usage info from /proc/pid/status Return Virtual and Resident memory size in MBytes.

reset(report=True)

show()

tag(mytag)

time()

pick the actual OS routine that returns some kind of timer time.time : wall clock time (include I/O and multitasking overhead) time.clock : cpu clock time

admit.util.utils.add_new_at()

Method to add a new AT to the ADMIT infrastructure. Alternatively, the command line tool dtdGenerator can be used.

Parameters:None Returns:None

admit.util.utils.add_new_bdp()

Method to add a new BDP to the ADMIT infrastructure. Alternatively, the command line tool dtdGenerator can be used.

Parameters:None Returns:None

admit.util.utils.admit_dir(file, out=None)

create the admit directory name from a filename

This filename can be a FITS file (usually with a .fits extension or a directory, which would be assumed to be a CASA image or a MIRIAD image.

If out is set and non-blank, this (+.admit) will be the output name, overriding file

It can be an absolute or relative address

x.fits -> x.admit x.fits.gz -> x.admit x.admit -> x.admit (+warning) x -> x.admit

admit.util.utils.admit_root(path=None)

Return the root directory of the ADMIT environment

Typically in ADMIT/etc there are files needed by certain functions and other TBD locations. For now we are using getenv(), but in deployment this may not be the case.

Parameters:

path : string

Optional path appended to the ADMIT root

Returns:

String containing the absolute address of the admit root directory,

with the optional path appended

admit.util.utils.assert_files(files)

Assert that files exist, if not, throw an exception

Parameters:

files : list

Files to be checked

Returns:

None

admit.util.utils.casa_argv(argv)

Processes casarun arguments into C-style argv list.

Modifies the argv from a casarun script to a classic argv list such that the returned argv[0] is the casarun scriptname.

Parameters:

argv : list of str

Argument list.

Returns:

sargv

Script name plus optional arguments

Notes

Does not depend on CASA being present.

admit.util.utils.compareversions(version1, version2)

Method to compare two version numbers or strings. The comparison is first done on the major version number, if they are the same then the minor version numbers are compared, if these are the same then the sub version numbers are compared. Returns 1 if version1 > version2, 0 if version1 == version2, and -1 if version1 < version2.

Parameters:

version1 : str or tuple

The first version to compare. If it is a string then it is converted to a tuple of ints before comparison.

version2 : str or tuple

The first version to compare. If it is a string then it is converted to a tuple of ints before comparison.

Returns:

Int, 1 if version1 > version2, 0 if version1 == version2, and -1 if version1 < version2.

admit.util.utils.equal(f1, f2, relerror=1e-06)

Determine if two numbers are identical within a relative margin

Parameters:

f1 : float

first number

f2 : float

second number

relerror : float

The relative error to allow between the two numbers

Returns:

True if the two numbers are near enough identical, False otherwise

admit.util.utils.find_files(directory, pattern)

Find files with a given pattern down a directory tree. This is a generator function.

Parameters:

directory : str

Root directory to start search

pattern : str

Pattern to match

Returns:

list of file names

See also

Admit.find_files

Examples

find_files(‘/tmp/a’, ‘*.fits’)

admit.util.utils.fitgauss1D(x, y, par=None, width=-1.0)

Method for fitting a 1D gaussian to a spectral line

Parameters:

x: array like

The x co-ordinates of the spectrum, note the center of the spectral line should be near 0.0 if possible

y: array like

The y co-ordinates (intensity) of the spectrum

par: array like

The initial guesses for the fit parameters, the fitter works best if the center parameter is near 0.0 3 parameters: PeakY, CenterX, FWHM.

width: float

If positive, this is the assumed width (or step) in the x array, which is needed if only 1 point is given. Otherwise ignored.

Returns:

A tuple containing the best fit parameters (as a list) and the covariance

of the parameters (also as a list)

admit.util.utils.fitgauss1Dm(xdat, ydat, usePeak=False, dx=-1.0)

gaussfit helper function this will get a reasonable gauss even if you only have 2 points assumes evenly spaced data in xdat, so it can extract a width. It can be used like fitgauss1D(), but uses the first three moments of the distribution to “match” that of a gauss. area preserving if you wish. If you set usePeak, it will pick the highest value in your data. Warning: if you must fit negative profiles, be sure to rescale before you come into this routine.

admit.util.utils.format_chem(form)

Method to format a chemical formula for display, specifically adding subscripts and superscripts

Parameters:

formula : str

The chemical formula, usually obtained from splatalogue

Returns:

string containing the formatted formula

admit.util.utils.freqtovel(freq, delta)

Method to convert between offset frequency and offset velocity

Parameters:

freq : float

The base frequency

delta : float

The change in frequency

Returns:

The offset velocity (in km/s) corresponding to the frequency shift.

admit.util.utils.gaussian1D(x, intensity, center, fwhm)

Method for generating a 1D gaussian, primarily by the line fitting routine

Parameters:

x : array like

list of points to generate the gaussian for

intensity : float

intensity of the gaussian, arbitrary units

center : float

The center position (peak) of the gaussian in the same units as x

fwhm : float

FWHM of the gaussian in the same units as x. Recall FMWHM = 2*sqrt(2*ln(2)) sigma ~ 2.355 sigma for a gaussian with variance sigma.

Returns:

a list of intensities for the gaussian, one for each entry in x

admit.util.utils.getBDP(file)

Convenience method to convert a bdp file into a BDP object. It calls the BDPReader class to do the work.

Parameters:

file : str

File name (including any relative or absolute path) of the bdp file to be parsed and converted to a BDP object.

Returns:

BDP object of appropriate type based on the given input file.

admit.util.utils.getButton(buttonid, onclick, label)

Generates HTML for a button that will call a javascript method with the id as its argument. The button class will be livedisplay (see admit.css) so it only is visible in pages viewed with http.

Parameters:

buttonid: str

String for the button id tag

onclick: str

Name of the javascript method to be called via the onclick tag

label: str

Label for button that will be displayed to user

Returns:

str

HTML button element

admit.util.utils.getClass(typ, name, init=None)

Get an instance of an ADMIT class

Parameters:

typ : str

package name, e.g. ‘at’ or ‘bdp’, ‘admit.’ wil be prepended to this.

name : str

The name of the class to retrieve, must have proper capitalization

init : dict

Initialization parameters. Default: None

Returns:

An instance of the requested class

admit.util.utils.getFiles(basedir)

Generates a list of all BDP files that are in the baseDir and any subdirectories

Parameters:

None

Returns:

List

List of BDP files that need to be read in from disk

admit.util.utils.get_references(filename)

Read a references file , which contain two columns, one with frequencies (or any float), one with line (references), a string. They are returned as a dictionary { freq:line, ... } to be used for plotting references in e.g. APlot.makespec()

Lines starting with the usual comment symbol ‘#’ are skipped Blank lines are skipped Duplicate entries are skipped

Used by e.g. LineID_AT and passed to APlot.makespec()

It is recommended that the filename is relative to $ADMIT, e.g. “etc/co_lines.tab”, as for an absolute filename reference the ADMIT product is not formally portable.

admit.util.utils.getmass(formula)

Method to calculate the rough mass of a molecule

Parameters:

formula : str

The chemical formula, usually obtained from splatalogue

Returns:

int of the rough mass

admit.util.utils.getplain(formula)

Method to make a chemical formula more readable for embedding in filenames Examples:

CH3COOHv=0 -> CH3COOH

g-CH3CH2OH -> CH3CH2OH

(CH3)2COv=0 -> (CH3)2CO

cis-CH2OHCHOv= -> CH2OHCHO

g’Ga-(CH2OH)2 -> (CH2OH)2

Parameters:

formula : str

The chemical formula to process

Returns:

String of the more readable formula

admit.util.utils.interpolatespectrum(spec, left=0.0, right=0.0)

Method to interpolate over bad points in a spectrum. Bad points generally come from masked pixels in an image. On read in these show up as exactly 0.0 or +/-inf, or nan in the spectrum. Edge channels that are bad are just converted to 0.0.

Parameters:

spec : numpy array

The input spectrum to process

left : float

The value to assign bad edge channels to on the left side of the spectrum. Defualt: 0.0

right : float

The value to assign bad edge channels to on the right side of the spectrum. Defualt: 0.0

Returns:

A numpy array with the same length as the input with nan values converted to

iterpolated values between good points, and bad edge values.

admit.util.utils.iscloseinE(v1, v2)

Method to determine if two spectral lines are very close in energy

Parameters:

v1 : float

Energy of first transition.

v2 : float

Energy of second transition

Returns:

True/False whether or not the energies are very close

admit.util.utils.isexotic(species)

Method to determine if a molecule contains an “exotic” atom. In this case an exotic atom is one that is uncommon, but possible to be detected in the right environment.

Parameters:

species : str

The chemical formula for the molecule

Returns:

True if the molecule contains an “exotic” element, False otherwise.

admit.util.utils.isotopecount(formula)

Method to count the number of isotopes in a molecule

Parameters:

formula : str

The chemical formula to analyze

Returns:

An integer of the number of less common isotopes found

admit.util.utils.issameinfreq(f1, f2, relerror=1e-06)

admit.util.utils.merge(a, b)

Merge two overlapping segments together. Segments are given as a two item list of the end points. There is no actually check that the input segments overlap or are continguous.

Parameters:

a : two item list

One of the segments to merge

b

: two item list

The second segment to merge

Returns:

list

A list of the merged segment end points

admit.util.utils.mergesegments(segs, nchan)

Method to merge all input segments into a single list. Any overlaping segments are merged into one that encompases all the channels.

Parameters:

segs : list

list of Segments tuples in channel space

nchan: int

number of channels in parent spectrum

Returns:

merged list of segments

admit.util.utils.on_error_retry(exception, callback, timeout=2, timedelta=0.1)

A generic method for doing retries with timeout.

Parameters:

exception : Exception

An Exception class to handle exceptions from the callback.

callback : function

The callback method to invoke

timeout : float

timeout in seconds before giving up. default: 2

timedelta : float

number of seconds to sleep before retries. default: 0.1

Examples

>>> for retry in on_error_retry(SomeSpecificException, do_stuff):
>>>     retry()

@todo: a better reference should be given, per our discussion in mid Sepetember stolen from stackoverflow.

admit.util.utils.parseversion(version)

Method to parse a version string from an AT or a BDP to turn it into ints so it can be easily compared.

Parameters:

version : str

The string to parse

Returns:

Tuple containing the major, minor, and sub version numbers (all ints)

admit.util.utils.remove(item)

Remove a file or directory.

The method determines if it is a file or directory and removes it appropriately.

Parameters:

item : str

Item to be deleted

Returns:

None

admit.util.utils.rename(item1, item2)

Rename a file or directory, but ensuring the destination is removed first

Parameters:

item1 : string

Source file/directory name

item2 : string

Destination file/directory name

Returns:

None

admit.util.utils.rm(file)

Remove a file

Parameters:

file : str

File to be deleted

Returns:

None

admit.util.utils.rmdir(dir)

Remove a directory. Calls shutil.rmtree and errors are supressed

Parameters:

dir : str

Directory to be deleted

Returns:

None

admit.util.utils.rreplace(s, old, new, occurrence=1)

Replace portion of a string (from the right side). Handy utility to change a filename extension, e.g. rreplace(‘a/b/c.fits’, ‘fits’, ‘im’) -> ‘a/b/c.im’

Parameters:

s : str

The string to process

old : str

The substring to replace

new : str

Whet to replace the ‘old’ substring with

occurrence : int

The number of occurrences to replace Default: 1

admit.util.utils.setkey(obj, key, val)

Method to set the key of an arbitrary class. The class must have an attribute named ‘keys’. The existence and data type of the given key are checked and if it does not exist, or changes data type then an exception is raised.

Parameters:

obj : class instance

The class whose key is being set

key : str

The name of the item to change

val : varies

The value to change key to

Returns:

None

admit.util.utils.specingest(chan=None, freq=None, velocity=None, spec=None, file=None, separator=None, restfreq=None, vlsr=None)

Convenience method to convert input data (either files or arrays) into a CubeSpectrum_BDP. If files are used then then the columns containing the frequency and the intensity must be given (channel numbers are optional). Any number of files can be given, but all spectra must have the same length as they are assumed to come from the same data source. Blank lines and lines starting with a comment ‘#’ will be skipped, additionally any line with too few columns will be skipped. If arrays are used an input then both the frequency and intensity must be specified (the channel numbers are optional). Both lists and numpy arrays are accepted as inputs. Multidimmensional arrays are supported with the following parameters:

• A single frequency list can be given to cover all input spectra, otherwise the shape of the frequency array must match that of the spectra

• A single channel list can be given to cover all input spectra, otherwise the shape

  of the channel array must match that of the spectra

• All spectra must have the same length

If a channel array is not specified then one will be constructed with the following parameters:

• The channel numbers will start at 0 (casa convention)
• The first entry in the spectrum will be considered the first channel, regardless of whether the frequency array increases or decreases.

Additionally, if there is velocity axis, but no frequency axis, a frequency axis can be constructed by specifying a rest frequency (restfreq), and vlsr.

The convert method will return a single CubeSpectrum_BDP instance holding all input spectra along with an image of each.

Parameters:

chan : array or int

An array holding the channel numbers for the data, multidimmensional arrays are supported. If an integer is specified then it is the number of the column in the file which contains the channel numbers, column numbers are 1 based. Default: None

freq : array

An array holding the frequencies for the data, multidimmensional arrays are supported. If an integer is specified then it is the number of the column in the file which contains the frequencies, column numbers are 1 based. Default: None

velocity : array

An array holding the velocity for the data, multidimmensional arrays are supported. If an integer is specified then it is the number of the column in the file which contains the velcoties, column numbers are 1 based. If this parameter is specified then restfreq and vlsr must also be specified. Default: None

spec : array

An array holding the intesities of the data, multidimmensional arrays are supported. If an integer is specified then it is the number of the column in the file which contains the intensities, column numbers are 1 based. Default: None

file : list or str

A single file name or a list of file names to be read in for spectra. Default: None

separator : str

The column separator for reading in the data files. Default: None (any whitespace)

restfreq : float

The rest frequency to use to convert the spectra from velocity to frequency units. The rest frequency is in GHz. Default: None (no conversion done)

vlsr : float

The reference velocity for converting a velocity axis to frequency. The units are km/s. If this is not set then it is assumed that the vlsr is 0.0. Default: None

Returns:

CubeSpectrum_BDP instance containing all of the inpur spectra.

admit.util.utils.tmp_file(prefix, tmpdir='/tmp')

Create a temporary file in /tmp.

Parameters:

prefix : str

starting name of the filename in <tmpdir>/<pattern>

tmpdir

Returns:

Unique filename

admit.util.utils.undoppler(sky, vel)

Method to convert from sky frequency to source rest frequency

Parameters:

sky : float, list, or numpy array

The sky frequency

vel : float

The source vlsr in km/s

Returns:

The input value converted to rest frequency, in the same form that the input

was given. If the the absolute value of the input velocity is less

than 1E-8 km/s (0.01 cm/s), it is assumed to be zero and ‘sky’ is

returned.

admit.util.utils.veltofreq(vel, freq)

Method to convert between offset velocity and offset frequency

Parameters:

vel : float

The offset velocity

freq : float

The base frequency

Returns:

The offset frequency corresponding to the velocity shift.

admit.util.utils.ztovrad(z)

Convert (optical) z to the linear radio convention recession velocity