Ingest_AT — Ingests a (FITS) data cube.¶
This module defines the Ingest_AT class.
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)
- file: string
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.
- 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, as 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.
- 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 ”.bp”
keyval : dictionary, optional
Keyword-value pairs, directly passed to the contructor for ease of assignment.
_version (string) Version ID for some future TBD use. Also should not be documented here, as underscore attributes are for internal usage only.
Add a BDP input to an AT.
addinputbdp(item[, slot, insert])
Add a BDP to the _bdp_in list.
Add a BDP output product to an AT.
addoutputbdp(item[, slot, insert])
Add a BDP to the _bdp_out list.
Get/set project base directory.
Determines the better match of two tasks to the current one.
Check if the files from all the BDP_out’s in an AT exist.
Check the type of an object to see if it is a BDP.
Clear the input BDP list.
Clear the output BDP list.
Creates an independent duplicate of the task.
Method to delete the AT and underlying BDPs.
Delete a specific BDP in the _bdp_in list.
Delete a specific BDP in the _bdp_out list.
Absolute directory reference of the ADMIT project.
Method to do a dry run of the AT, generally just checks input values for errors.
Returns current task enabled setting, with optional reset.
Executes the task.
Deletes alias reservation, if present.
Method to get the given attributes value
Retrieves project ID associated with the task.
Return the version string.
Method to write out the dtd data.
Method to get the effective logging level of the logging subsystem
Retrieval value for a key.
Method to get the name of the logger for this AT instance
Method to get the current logging level of the AT
Query if a key exists for an AT.
Method to represent the current AT in HTML format.
Returns task ID number.
Whether the task alias appears to be auto-generated.
Method to determine if two ATs are the same.
Returns whether the AT is out of date.
Returns the length of _bdp_in and _bdp_out in a tuple.
Increments the task link count.
Mark an AT that it’s state was changed, so it would need to be rerun.
Resets _stale to indicate that the AT does not need to be run.
Merges attributes from another task.
Make a directory in the ADMIT hierarchy.
mkext(filename, ext[, alias])
Return a new filename with a new extension with optional ADMIT alias.
Assigns the task a new ID number.
Performs an in-place shallow copy.
Returns current task execution flag, with optional reset.
Save (write) any BDPs connected to this AT.
Method to set protected attributes, rather than direct access
setAlias(aliases[, alias, auto])
Sets and registers the task alias, guaranteed unique among registered aliases.
Adds a project ID to task ID.
Validate the _valid_bdp_in list and digest it into the appropriate attributes.
Validate the _valid_bdp_out list and digest it into the appropriate attributes.
Method to set the effective logging level of the logging subsystem
setkey([name, value, isinit])
Set keyword value.
Method to set the name of the logger for this AT instance
Method to set the logging level
Return the AT type.
return some html icons representing the enabled/stale status of this task
Returns the summary dictionary from the AT, for merging into the ADMIT Summary object.
Decrements the task link count.
Returns the user dictionary from the AT, for merging into the ADMIT userdata object.
Method to validate the _bdp_in’s against a dictionary of expected types.
Method to error check all input keys.
Method to write the AT to disk.
- 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)