Ingest_AT — Ingests a (FITS) data cube.

This module defines the Ingest_AT class.

class admit.at.Ingest_AT.Ingest_AT(**keyval)

Ingest an image (cube) into ADMIT, normally to bootstrap a flow.

See also Ingest_AT for the design document.

Ingest an image cube (usually FITS, but a CASA image or MIRIAD image are also natively supported by CASA) into CASA. Expect I/O penalties if you use FITS or MIRIAD because CASA images are tiled.

A number of selections and corrections to the cube can be made, as specified by the keywords. Notably, a sub-cube can be taken out of the cube by trimming off spatial and spectral edges, a primary beam correction can be made as well.

Internally ADMIT will store images as 4D CASA images, with any missing 3rd or 4th axis created redundantly (FREQ as axis 3, and POL as axis 4)

Keywords

file: string

Input filename.

Usually ‘basename.fits’ where ‘basename’ can be long, and can involve a directory hierarchy. The admit directory will be ‘basename.admit’, which will include the whole directory path if one was given.

A symbolic link within ADMIT will then be used to resolve this as a local file.

An absolute address is advised to be used if your working directory can change in a flow.

If a CASA image is given, a symlink is used when no modifications (e.g. box=) are used, but this will cause uncertain integrity of the input BDP, as other clients could be modifying it. A MIRIAD image can also be given, but I/O (like with FITS) will be slower.

[no default]

basename: string

New short basename (like an alias) of the output file.

This is meant to override a possibly long basename in the input file. The alias keyword in the baseclass can still be used to create basename-alias type filenames. Warning: if you use a dash in your basename, there is a good risk this will be confused with the alias separator in the basename in a flow, as these are “basename-alias.extension”. Default: empty string, basename inherited from the input file name.

pb: string

If given, this is the filename of the Primary Beam by which the input file needs to be multiplied to get a noise flat image for processing the ADMIT flow. The ALMA pipeline product of the Primary Beam should be in ‘longname.pb.fits’ where the flux flat cube is ‘longname.pbcor.fits’ Note: PB correction is slow. Default: empty string, no PB correction is done.

usepb: boolean

If True, the PB is actually used in an assumed flux flat input file to create a noise flat input BDP. If False, it is assumed the user has given a noise flat file, and the PB can be used downstream to compute proper PB corrected fluxes. Note that the PB is always stored as an 2D image, not as a cube. Default: True

box: blc,tlc (a list of 2, 4 or 6 integers)

Select a box region from the cube. For example box=[xmin,ymin,xmax,ymax], which takes all channels, or [xmin,ymin,zmin,xmax,ymax,zmax], which also selects a range in channels. You can also select just some channels, with box=[zmin,zmax]. As always, pixels and channels are 0 based in CASA. Arbitrary CASA regions are not implemented here, we only support a box/edge selection.

edge: Z_start,Z_end (a list of 1 or 2 integers)

You can use edge= to remove edge channels, e.g. if box= was not specified, or when only an XY box was given. If box contains 2 or 6 numbers, any edge specification would be ignored. If one number is given, the edge rejection is the same at the upper and lower end. Default: not used.

smooth: [nx,ny,[nz]] (a list of 2 or 3 integers)

You can convolve your cube spatially, and optionally spectrally as well, by supplying the number of pixels by which it is convolved. Spatially the FWHM is used. If nz is 1, a Hanning smooth is applied, else a boxcar of size nz is used. See also Smooth_AT — Creates a smoothed version of a cube., where a common beam can be computed or supplied. A future version should contain a decimation option. By default no smoothing is applied.

mask: boolean

If True, a mask needs to be created where the cube has 0’s. This option is automatically bypassed if the input CASA image had a mask. [False]

vlsr: float (km/s)

VLSR of the source (km/s). If not set, the frequency at the center of the band is compared with the rest frequency from the header, which we call VLSRc. If the input file is not FITS, or header items are missing if the input file is CASA or MIRIAD already, unexpected things may happen. This VLSR (or VLSRc) is added to the ADMIT summary, which will be used downstream in the flow by other AT’s (e.g. LineID) Default: -999999.99 (not set).

restfreq: float (GHz)

An alternative method providing the source VLSR would be to specify the true restfreq (f0) where the fits header has a ‘fake’ restfreq (f). This technique is sometimes used by the PI to avoid complex high-z doppler calculations and supply the redshifted line directly. In this case VLSR = c * (1-f/f0), in the radio definition, with z in the optical convention of course. We call this VLSRf. NOTE: clarify/check if the “1+z” velocity scale of the high-z object is correct. Default: -1.0 (method not used). Units must be GHz!

Input BDPs

None. The input is specific via the file= keyword.

Output BDPs

SpwCube: count: 1

The output spectral window cube. The convention is that the name of the BDP inherits from the basename of the input fits cube,and adding an extension “im”. Each AT has a hidden keyword called alias=, use this keyword if you want to modify the cube name to “alias.im”, and hence the BDP to “alias.im.bdp”. Note this is an exception from the usual rule, where alias= is used to create a dashed-prefix to an extension, e.g. “x.alias-y”.

Image_BDP: 1

Output PB Map. If the input PB is a cube, the central channel (being representative for the avarage PB across the spectrum window) is used. New extension will be ”.pb”

Parameters:

keyval : dictionary, optional

Keyword-value pairs, directly passed to the contructor for ease of assignment.

Attributes

_version

(string) Version ID for some future TBD use. Also should not be documented here, as underscore attributes are for internal usage only.

Methods

addinput(item[, slot])	Add a BDP input to an AT.
addinputbdp(item[, slot, insert])	Add a BDP to the _bdp_in list.
addoutput(item[, slot])	Add a BDP output product to an AT.
addoutputbdp(item[, slot, insert])	Add a BDP to the _bdp_out list.
baseDir([path])	Get/set project base directory.
bestMatch(at1, at2)	Determines the better match of two tasks to the current one.
checkfiles()	Check if the files from all the BDP_out’s in an AT exist.
checktype(item)	Check the type of an object to see if it is a BDP.
clearinput()	Clear the input BDP list.
clearoutput([delete])	Clear the output BDP list.
copy()	Creates an independent duplicate of the task.
delete()	Method to delete the AT and underlying BDPs.
delinput(slot)	Delete a specific BDP in the _bdp_in list.
deloutput(slot)	Delete a specific BDP in the _bdp_out list.
dir([filename])	Absolute directory reference of the ADMIT project.
dryrun()	Method to do a dry run of the AT, generally just checks input values for errors.
enabled([state])	Returns current task enabled setting, with optional reset.
execute([args])	Executes the task.
freeAlias(aliases[, alias])	Deletes alias reservation, if present.
get(attrib)	Method to get the given attributes value
getProject()	Retrieves project ID associated with the task.
getVersion()	Return the version string.
getdtd(fl)	Method to write out the dtd data.
geteffectivelevel()	Method to get the effective logging level of the logging subsystem
getkey(key)	Retrieval value for a key.
getloggername()	Method to get the name of the logger for this AT instance
getlogginglevel()	Method to get the current logging level of the AT
haskey(key)	Query if a key exists for an AT.
html(inheader)	Method to represent the current AT in HTML format.
id([strip])	Returns task ID number.
isAutoAlias([withEmpty, compat])	Whether the task alias appears to be auto-generated.
isequal(at)	Method to determine if two ATs are the same.
isstale()	Returns whether the AT is out of date.
len2()	Returns the length of _bdp_in and _bdp_out in a tuple.
link()	Increments the task link count.
markChanged()	Mark an AT that it’s state was changed, so it would need to be rerun.
markUpToDate()	Resets _stale to indicate that the AT does not need to be run.
merge(at[, aliases])	Merges attributes from another task.
mkdir(dirname)	Make a directory in the ADMIT hierarchy.
mkext(filename, ext[, alias])	Return a new filename with a new extension with optional ADMIT alias.
newId(tid)	Assigns the task a new ID number.
reset(a)	Performs an in-place shallow copy.
run()
running([state])	Returns current task execution flag, with optional reset.
save()	Save (write) any BDPs connected to this AT.
set(item, val)	Method to set protected attributes, rather than direct access
setAlias(aliases[, alias, auto])	Sets and registers the task alias, guaranteed unique among registered aliases.
setProject(pid)	Adds a project ID to task ID.
set_bdp_in([bdpin])	Validate the _valid_bdp_in list and digest it into the appropriate attributes.
set_bdp_out([bout])	Validate the _valid_bdp_out list and digest it into the appropriate attributes.
seteffectivelevel(level)	Method to set the effective logging level of the logging subsystem
setkey([name, value, isinit])	Set keyword value.
setloggername(name)	Method to set the name of the logger for this AT instance
setlogginglevel(level)	Method to set the logging level
show()	Return the AT type.
statusicons()	return some html icons representing the enabled/stale status of this task
summary()	Returns the summary dictionary from the AT, for merging into the ADMIT Summary object.
unlink()	Decrements the task link count.
userdata()	Returns the user dictionary from the AT, for merging into the ADMIT userdata object.
validateinput([describe])	Method to validate the _bdp_in’s against a dictionary of expected types.
validatekeys()	Method to error check all input keys.
write(node)	Method to write the AT to disk.

run()

summary()

Returns the summary dictionary from the AT, for merging

into the ADMIT Summary object.

Ingest_AT adds the following to ADMIT summary:

  Key      type        Description
--------  ------       -----------
fitsname  string      Pathless filename of FITS cube
casaname  string      Pathless filename of CASA cube
object    string      Object (or field) name
naxis     integer     Number of axes
naxisn    integer     size of axis n (n=1 to naxis0)
crpix1    float       Reference pixel axis 1 (n=1 to naxis)
crvaln    float       axis value at CRPIX1 (n=1 to naxis)
ctypen    string      axis type 1 (n=1 to naxis0
cdeltn    float       axis increment 1 (n=1 to naxis)
cunitn    string      axis unit 1 (n=1 to naxis)
equinox   string      equinox
restfreq  float       rest frequency, Hz
bmaj      float       beam major axis, radians
bmin      float       beam minor axis, radians
bpa       float       beam position angle, deg
bunit     string      units of pixel values
telescop  string      telescope name
observer  string      observer name
date-obs  string      date of observation
datamax   float       maximum data value
datamin   float       minimum data value
badpixel  float       fraction of invalid pixels in the cube (a number between 0 and 1)
vlsr      float       Object line-of-sight velocity (km/s)