componentlist¶

class componentlist[source]¶

A tool for the manipulation of groups of components

A componentlist is a tool that contains functions that manipulate components. A component is a functional representation of the sky brightness - point source, disk, Gaussian, etc.

Note for those new to CASA: components are not used explicitly in cleaning, rather the model is stored as an image. Components are useful for e.g. simulation and modifying images (ia.modify), but one will not in general have a clean component list associated with cleaning data.

The simplest way to make a componentlist tool is to use cl.addcomponent:

cl.done()   # it is safest to close it before beginning
# add a single point source component with 
# Stokes I=2.3Jy and other Stokes parameters 0  
cl.addcomponent(dir='J2000 10h30m00 -20d00m00.0', flux=[2.3,0,0,0])  
cl.rename("myList.cl")  # save to disk

One can open a list on disk with cl.open(filename).

Componentlists can be converted to/from records (python dictionaries) with cl.torecord() and cl.fromrecord(record).

Methods Summary

`add`	The add function adds a component to the component list.
`addcomponent`	The addcomponent function is a convenience function that ties together the simulate function, and the various set functions.
`asciitocomponentlist`	This constructor will allow conversion of a number of ascii-file-based formats to componentlists.
`close`	The close function resets the componentlist to its default state.
`componentlist`	Use this constructor to construct a componentlist tool that does not contain any components.
`concatenate`	The concatenate function copies the specified component(s), from the specified to list, to the end of the current list.
`convertfluxpol`	The convertfluxpol function is used to convert the flux to another polarization representation.
`convertfluxunit`	The convertfluxunit function is used to convert the flux to another unit.
`convertfrequnit`	The convertfrequnit function changes the specified components to use a new unit for the reference frequency.
`convertrefdir`	The convertrefdir function changes the specified components to use a new direction reference frame.
`convertshape`	Change the units of the shape parameters (Not implemented yet)
`deselect`	The deselect function is used to remove the “selected” mark from specified components in the list.
`done`	The done function frees up all the memory associated with a componentlist tool.
`edit`	Start up the component editor gui (Not implemented yet)
`fromrecord`	This function allows the componentlist records that are returned by other functions (for e.g from imageanalysis tool) be converted to a tool to be manipulated or to be saved on disk
`getcomponent`	The component function returns a record, showing the current state of the specified component in the list.
`getfluxerror`	The getfluxerror function returns the error in the flux of the specified component using the current units and the current polarization representation.
`getfluxpol`	The getfluxunit function returns the polarization representation of the flux of the specified component.
`getfluxunit`	The getfluxunit function returns the units of the flux of the specified component.
`getfluxvalue`	The getfluxvalue function returns the value of the flux of the specified component using the current units and the current polarization representation.
`getfreq`	Get the reference frequency (Not implemented yet)
`getfreqframe`	Get the reference frequency frame (Not implemeted yet)
`getfrequnit`	Get the reference frequency unit (Not implemeted yet)
`getfreqvalue`	Get the reference frequency value (Not implemeted yet)
`getlabel`	The getlabel function returns the label associated with the specified component.
`getrefdir`	The getrefdir function returns, as a direction measure, the reference direction for the specified component.
`getrefdirdec`	The getrefdirdec function returns the declination of the reference direction of the component as a formatted string.
`getrefdirframe`	The getrefdirframe function returns the reference frame of the reference direction of the component as a string.
`getrefdirra`	Get the RA of the reference direction.
`getshape`	The getshape function returns the shape parameters of a component in a record.
`getspectrum`	The getspectrum function returns the spectral parameters of a component in a record.
`indices`	The indices function will returns a vector of non-negative integers that can be used to index through the list.
`iscomponentlist`	This global function can be used to determine if the supplied argument is a componentlist tool.
`isphysical`	The isphysical function is used to check if the specified components meet a number of criteria that must be True if the component could be used to model a physical process.
`length`	The length function returns a non-negative integer that indicates how many components the list currently contains.
`open`	Use this constructor to construct a componentlist tool by reading the data from an table.
`purge`	The remove function deletes components from the list but does not remove them from memory.
`recover`	The recover function appends components to the end of the list that have been deleted with the remove function.
`remove`	The remove function removes the specified component(s) from the list.
`rename`	The rename function is used to specify the name of the table associated with this componentlist.
`replace`	The replace function replaces the components from the list with the specified components from another list.
`sample`	The sample function will returns a vector containing the flux in Janskys/pixel of all the components in the list, in the specified direction, at the specified frequency.
`select`	The select function is used to mark the specified components as “selected”.
`selected`	The selected function is used to determine which components in a list are selected.
`setflux`	The setflux function is used to reassign the flux of the specified components to a new value.
`setfreq`	The setfreq function sets the reference frequency of the specified components to a new value.
`setfreqframe`	The setfreqframe function sets the reference frame for the reference frequency of the specified components.
`setlabel`	The setlabel function is used to reassign the label (an arbitrary text string) of the specified components to a new value.
`setrefdir`	The setrefdir function sets the reference direction of the specified components to a new value.
`setrefdirframe`	The setrefdirframe function sets the reference frame for the reference direction of the specified components (what a mouthful)!
`setshape`	The setshape function changes the shape of the specified components to the user specified shape.
`setspectrum`	The setspectrum function changes the spectrum of the specified components
`setstokesspectrum`	The setstokesspectrum function changes the spectrum of the specified components to the user specified spectrum.
`shapetype`	The shapetype function returns the current shape of the specified component.
`simulate`	The simulate function adds simulated components to the list.
`sort`	The sort function can sort all the components in a list using a variety of criteria.
`spectrumtype`	The spectrumtype function returns the current spectral shape of the specified component.
`summarize`	The summarize function summarizes the contents of the specified components to the logger.
`torecord`	This function allows the componentlist to be converted to a record.

add(thecomponent='', iknow=True)[source]¶

The add function adds a component to the component list. You cannot add components to a list that has been opened read only. To use this function you need to know the details of the record format. however this has been deprecated and you are urged to use the set functions, in conjunction with the simulate function to add a component to the list.

Parameters

thecomponent (record='') - A record that represents a component. any record that contains the required fields
iknow (bool=True) - Suppress the warning message

Returns

bool

addcomponent(flux='', fluxunit='Jy', polarization='Circular', dir='J2000 00h00m00.0 90d00m00.0', shape='disk', majoraxis='2.0arcmin', minoraxis='1.0arcmin', positionangle='0.0deg', freq='LSRK 1.415GHz', spectrumtype='spectral index', index='1.0', optionalparms=[0.0], label='')[source]¶

The addcomponent function is a convenience function that ties together the simulate function, and the various set functions. This function adds a component to the end of the list. For a description of the arguments see the following functions. [flux, fluxunit, polarization] See setflux [ra, raunit, dec, decunit] See setrefdir [dirframe] See setrefdirframe [shape, majoraxis, minoraxis, positionangle] See setshape [freq] A frequency quantity which is split into a value and units and passed to the setfreq function [freqframe] See setfreq [spectrumtype, index] The spectral index alpha such that flux density S as a function of frequency nu is: S nu**alpha. See also the setspectrum or setstokesspectrum functions. [label] See setlabel

Parameters

flux (any='') - The flux value. A vector with four real or complex numbers
fluxunit (string='Jy') - The units of the flux. Any string with the same dimensions as the Jansky
polarization (string='Circular') - The polarization of the value field. ‘Stokes’, ‘linear’ or ‘circular’
dir (any='J2000 00h00m00.0 90d00m00.0') - The direction measure of the source, it can a be any direction measure from the measures tool or a string of the type ‘J2000 10h30m00 -20d00m00.0’ or a vector of strings of the type [‘J2000’, ‘10:30:00.00’, ‘-20.00.00.0’]. Basically the string or strings should have the direction frame and quantities for Ra and Dec
shape (string='disk') - The new shape type. A string that is either ‘point’, ‘Gaussian’, or ‘disk’
majoraxis (any='2.0arcmin') - The width (FWHM in the case of a Gaussian) of the larger axis. A quantity with angular units
minoraxis (any='1.0arcmin') - The width (FWHM in the case of a Gaussian) of the smaller axis. A quantity with angular units
positionangle (any='0.0deg') - The rotation of the axes with respect to the reference frame. A quantity with angular units
freq (any='LSRK 1.415GHz') - The reference frequency. A quantity with units equivalent to the ‘Hz’ and frame or a frequency measure, e.g [‘TOPO’, ‘1.6GHz’], or simply default frame (LSRK) ‘1.6GHz’
spectrumtype (string='spectral index') - The spectrum type, a string that is one of ‘constant’, ‘spectral index’, or ‘plp’
index (any='1.0') - The spectral index or coeffecients for plp.
optionalparms (doubleVec=[0.0]) - optional parameters in vector (for future use)
label (string='') - The label for the component

Returns

bool

Examples

cl.open('my.cl')
cl.addcomponent(
  shape='point', flux=[1.0, 0.0, 0.0, 0.0], dir='J2000 19h00m00 -20d00m00',
  spectrumtype='plp', index=[1, 2, 3]
)

In this example, a point source with a power log polynomial
spectrum having the specified indices is added.

asciitocomponentlist(filename='', asciifile='', refer='B1950', format='ST', direction='', spectrum='', flux='', log=True)[source]¶

This constructor will allow conversion of a number of ascii-file-based formats to componentlists.

Parameters

filename (string='') - Name of output component list table
asciifile (string='') - Name of input ascii file
refer (string='B1950') - Input reference frame
format (string='ST') - Name of format (only ST supported)
direction (record='') - Direction measure (for relative coordinates)
spectrum (record='') - Default spectrum field, valid spectrum field [type=”Constant”, frequency=[type=”frequency” , refer=”LSR” , m0=[unit=”GHz” , value=1.0]]
flux (record='') - Default flux field, valid flux field [value=[0.0, 0.0, 0.0, 0.0], unit=’Jy’, polarization=”Stokes”]
log (bool=True) - Send a message to the logger

Returns

int

close(log=True)[source]¶

The close function resets the componentlist to its default state. In this state it contains no components and is not associated with any table.

This function flushes all the components in memory to disk if the componentlist is associated with a table. The table is then closed, and the contents of the list deleted.

If the list is not associated with a table its contents are still deleted and memory used by the list is released.

Parameters

log (bool=True) - Send a message to the logger

Returns

bool

Examples

See the example for the
rename function.

componentlist()[source]¶: Use this constructor to construct a componentlist tool that does not contain any components. Components can be appended to the list using the addcomponent or simulate functions, and the list can be stored to disk by giving it a name with cl.rename

concatenate(list='', which=[- 1], log=True)[source]¶

The concatenate function copies the specified component(s), from the specified to list, to the end of the current list. The components are specified by numbering them from one to the length of the list. You cannot append components to a list that has been opened read only but the list you are copying from may be readonly.

You use a vector of indices to copy a number of components at once. By default all components are copied.

Parameters

list (any='') - list to copy from. Can be a componentlist record or a componentlist file name from disk
which (intVec=[-1]) - which components to copy, -1 unset
log (bool=True) - Send a message to the logger

Returns

bool

Examples

   cl.addcomponent(flux=1.0, dir='J2000 19h00m00 -40d00m00')
   cl.addcomponent(flux=2.0, dir='J2000 19h10m00 -40d00m00')
   cl.addcomponent(flux=3.0, dir='J2000 19h00m00 -40d00m00')
   cl2 = cltool();
   cl2.concatenate(cl.torecord(), [0,2]);
   cl.done()
   cl2.rename('part_list.cl');
   cl2.done()
We make a 3 component component list and
copies the first and third component to another a componentlist
that was initially empty. These components are then saved to the
table called part_list.cl.

  cl.close() ### make sure we start with empty componentlist
  cl.concatenate('crux.cl', [0,2]);
  cl.rename('crux-copy.cl');
  cl.done()

This example reads a componentlist from a casa table and
copies the first and third component to another a componentlist
that was initially empty. These components are then saved to the
table called crux-copy.cl.

convertfluxpol(which='', polarization='circular')[source]¶

The convertfluxpol function is used to convert the flux to another polarization representation. There are are three representations used, namely , ’Stokes’, ’linear’ & ’circular’

Parameters

which (int='') - A vector of indices specifying the components to modify. A vector with indices between 0 and one less than the list length, inclusively
polarization (string='circular') - The new polarization representation

Returns

bool

Examples

cl.open('centarusA.cl')
print cl.getfluxvalue(1)
cl.convertfluxpol(1, 'linear')
print cl.getfluxvalue(1)

convertfluxunit(which='', unit='Jy')[source]¶

The convertfluxunit function is used to convert the flux to another unit. The units must have the same dimensions as the Jansky.

Parameters

which (int='') - A vector of indices specifying the components to modify. A vector with indices between 0 and one less than the list length, inclusively
unit (string='Jy') - The units of the flux. Any string with the same dimensions as the Jansky

Returns

bool

Examples

cl.open('crux.cl')
print cl.getfluxvalue(1)
cl.convertflux(1, 'WU')
print cl.getfluxvalue(1)

convertfrequnit(which='', unit='GHz')[source]¶

The convertfrequnit function changes the specified components to use a new unit for the reference frequency. Using this function will change the frequency value also so that the overall reference frequency is not changed. It will affect the values and units obtained with setfreqvalue function.

Any unit can be used that has the same dimensions as the ’Hz’.

Parameters

which (int='') - An index specifying the component to modify. An integer between 0 and one less than the list length, inclusively
unit (string='GHz') - The new frequency unit. Any string with the same dimensions as the ‘Hz’

Returns

bool

Examples

cl.open('centarusA.cl');
cl.convertfrequnit(1, 'kHz');

convertrefdir(which='', frame='')[source]¶

The convertrefdir function changes the specified components to use a new direction reference frame. Using this function will change the right-ascension and declination of the component(s), unlike the setrefdirframe which does not.

Please see the setrefdirframe function for a description of what frames are allowed.

Parameters

which (int='') - A vector of indices specifying the components to modify. A vector with indices between 0 and one less than the list length, inclusively
frame (string='') - The new reference frame A string like ‘B1950’, ‘J2000’ or ‘galactic’

Returns

bool

Examples

cl.open('crux.cl');
cl.convertrefdirframe(0, 'J2000');

convertshape(which='', majoraxis='rad', minoraxis='rad', positionangle='rad')[source]¶

Change the units of the shape parameters (Not implemented yet)

Parameters

which (int='') - A vector of indices specifying the components to modify. A vector with indices between 0 and one less than the list length, inclusively
majoraxis (string='rad') - The units to use on the larger axis. A string with angular units
minoraxis (string='rad') - The units to use on the smaller axis. A string with angular units
positionangle (string='rad') - The units to use for the rotation of these axes. A string with angular units

Returns

bool

deselect(which='')[source]¶

The deselect function is used to remove the “selected” mark from specified components in the list. This function wiil be used in conjunction with the planned graphical user interface and no other functions in the componentlist will behave differently if a component is marked as “selected” or not.

Components are not selected when the list is initially read from disk or when a new component is added to the list using the simulate function. function. Deselecting a component that is already deselected is perfectly valid and results in no change.

Parameters

which (intVec='') - A vector of indices Indices must be between 0 and one less than the list length, inclusively

Returns

bool

Examples

cl.open('crux.cl')
cl.select([1,3])
cl.deselect([2,3])

done()[source]¶: The done function frees up all the memory associated with a componentlist tool. After calling this function the componentlist tool cannot be used, either to manipulate the current list, or to open a new one. This function does not delete the disk file associated with a componentlist, but it will shut down the server process if there are no other componentlist tools being used.

edit(which='', log=True)[source]¶

Start up the component editor gui (Not implemented yet)

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length
log (bool=True) - Send a message to the logger

Returns

bool

fromrecord(record='')[source]¶

This function allows the componentlist records that are returned by other functions (for e.g from imageanalysis tool) be converted to a tool to be manipulated or to be saved on disk

Parameters

record (record='') - a component list record

Returns

bool

Examples

cl2 = cltool()

cl2.fromrecord(ia.findsources())
cl2.rename('sourcesfound.cl')
cl2.done()

getcomponent(which='', iknow=False)[source]¶

The component function returns a record, showing the current state of the specified component in the list.

Modifying the record that is returned by this function does not modify the component in the list. To do this you must remove the component from the list, using the remove function, and add the modified component using the add function, or use the replace object function. This function will be removed in a future release of and you are urged to use the get functions to extract information about a component.

Parameters

which (int='') - index of which component to extract. integers between 0 and one less than the length of the list, inclusively
iknow (bool=False) - Suppress the warning message

Returns

record

getfluxerror(which='')[source]¶

The getfluxerror function returns the error in the flux of the specified component using the current units and the current polarization representation. The functions getfluxvalue & getfluxunit & getfluxpol & can be used to get the value, units and polarization representation that corresponds to the specified error.

No error calculations are done by this tool. The error can be stored and retreived and if any of the parameters of the flux change the user is responsible for updating the errors.

Parameters

which (int='') - Index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

doubleVec

getfluxpol(which='')[source]¶

The getfluxunit function returns the polarization representation of the flux of the specified component. The actual values are obtained using the getfluxvalue function.

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

string

getfluxunit(which='')[source]¶

The getfluxunit function returns the units of the flux of the specified component. The actual values are obtained using the getfluxvalue function.

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

string

Examples

See the example for the
getfluxvalue function.

getfluxvalue(which='')[source]¶

The getfluxvalue function returns the value of the flux of the specified component using the current units and the current polarization representation. The functions getfluxunit & getfluxpol & can be used to get the units and polarization representation that corresponds to the supplied value.

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

doubleVec

Examples

  cl.open('crux.cl');
  flux = cl.getfluxvalue(1);
  unit = cl.getfluxunit(1);


This example returns the values, units, polarization and error of the
first component in the list.

getfreq(which='')[source]¶

Get the reference frequency (Not implemented yet)

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

record

getfreqframe(which='')[source]¶

Get the reference frequency frame (Not implemeted yet)

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

string

Examples

See the example for the
getfreqvalue function.

getfrequnit(which='')[source]¶

Get the reference frequency unit (Not implemeted yet)

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

string

Examples

See the example for the
getfreqvalue function.

getfreqvalue(which='')[source]¶

Get the reference frequency value (Not implemeted yet)

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

double

getlabel(which='')[source]¶

The getlabel function returns the label associated with the specified component. The label is an arbitrary text string that can be used to tag a component.

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

string

Examples

cl.open('crux.cl')
cl.getlabel(1)

getrefdir(which='')[source]¶

The getrefdir function returns, as a direction measure, the reference direction for the specified component. The reference direction is for all the currently supported component shapes the direction of the centre of the component.

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

record

Examples

cl.open('crux.cl')
dir = cl.getrefdir(1)

getrefdirdec(which='', unit='deg', precision=6)[source]¶

The getrefdirdec function returns the declination of the reference direction of the component as a formatted string. If the reference frame is something other than J2000 or B1950 the value returned is the longitude or the altitude.

See the getrefdirra function for a description of the unit and precision arguments.

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively
unit (string='deg') - The angular unit of the returned value. Any string containing an angular unit or ‘angle’ or ‘time’
precision (int=6) - The number of digits in the returned string. Numbers between 1 and 16 make the most sense

Returns

string

Examples

See the example for the
getrefdirra function.

getrefdirframe(which='')[source]¶

The getrefdirframe function returns the reference frame of the reference direction of the component as a string. The returned string is always in upper case. Common frames are, ’J2000’, ’B1950’ and ’GALACTIC’.

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

string

Examples

See the example for the
getrefdirra function.

getrefdirra(which='', unit='deg', precision=6)[source]¶

Get the RA of the reference direction. (Not implemented not)

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively
unit (string='deg') - The angular unit of the returned value. Any string containing an angular unit or ‘angle’ or ‘time’
precision (int=6) - The number of digits in the returned string. Numbers between 1 and 16 make the most sense

Returns

string

getshape(which='')[source]¶

The getshape function returns the shape parameters of a component in a record. As different shapes can have a differing number and type of parameters the shape parameters are returned in a record with fields that correspond to parameters relevant to the current shape.

For a point shape there are only two fields; type and direction. These are the shape type, and the reference direction. These values are also returned by the shapetype and getrefdir functions.

For both the Gaussian and disk shapes there are three additional fields; majoraxis, minoraxis, positionangle. These are angular quantities, and hence are records with a value and a unit.

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

record

Examples

See the examples for the
setshape and
convertshape
functions.  

getspectrum(which='')[source]¶

The getspectrum function returns the spectral parameters of a component in a record. As different spectral shapes can have a differing number and type of parameters the spectral parameters are returned in a record with fields that correspond to parameters relevant to the current spectral shape.

For a constant spectrum there are only two fields; type and frequency. These are the spectral type, and the reference frequency. These values are also returned by the spectrumtype and getfreq functions.

For the spectral index spectral shape there is also an index field. This contains a vector with four numbers, these are the spectral indicies for the I,Q,U,V components of the flux.

The dictionary associated with a power log polynomial spectrum has the following structure:

’coeffs’: array([ 1., 2., 3.]), ’frequency’: ’type’: ’frequency’, ’m0’: ’value’: 1.4200000000000002, ’unit’: ’GHz’, ’refer’: ’LSRK’, ’type’: ’Power Logarithmic Polynomial’, ’error’: array([ 0., 0., 0.])

The ’error’ value is currently not used.

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

record

Examples

See the examples for the
setspectrum and
getspectrum
functions.  

indices()[source]¶: The indices function will returns a vector of non-negative integers that can be used to index through the list. This vector always contains the integers starting at one and increasing sequentially to the length of the list. Its main use is in for loops as is illustrated in the example below.

iscomponentlist(tool='')[source]¶

This global function can be used to determine if the supplied argument is a componentlist tool. If so it returns True, otherwise it returns False.

Parameters

tool (any='') - The variable that you wish to test

Returns

bool

isphysical(which=[- 1])[source]¶

The isphysical function is used to check if the specified components meet a number of criteria that must be True if the component could be used to model a physical process. These criteria are: 1. I >= sqrt(Q**2 + U**2 + V**2) 2. That the flux, when represented using the Stokes representation, has a zero imaginary value.

The “Flux properties” section of the ComponentModels module documentation describes how it is possible to generate a component which has non-zero imaginary value in the Stokes representation.

It is possible to check a number of components at once by specifying the indicies of all the components. The returned value will only be True if all the specified components are physical.

Parameters

which (intVec=[-1]) - A vector of indices Indices must be between 0 and one less than the list length, inclusively

Returns

bool

Examples

cl2 = cltool()
cl2.simulate(2)
cl2.setflux(1, value=[10, 1+3j, 1-4j, 0], polarization="linear");
print cl2.isphysical([0,1])

length()[source]¶: The length function returns a non-negative integer that indicates how many components the list currently contains.

open(filename='', nomodify=False, log=True)[source]¶

Use this constructor to construct a componentlist tool by reading the data from an table. To ensure that this table contains all the necessary columns and to allow the table format to be enhanced in the future, it is highly recommended that the table be created using a componentlist tool.

The table that contains the componentlist may be opened read-only by setting the readonly flag to True. When this is done some of the functions in the componentlist tool cannot be used. These include the “set”, “convert”, “remove”, “replace”, “purge”, “recover”, and “sort” functions.

Parameters

filename (string='') - The filename of the table
nomodify (bool=False) - Should the table be opened read only
log (bool=True) - Send a message to the logger

Returns

bool

Examples

cl.open('crux.cl')

purge()[source]¶: The remove function deletes components from the list but does not remove them from memory. They remain accessible and can be obtained with the recover function. The purge function frees up the memory occupied by the removed components. You cannot use the recover function to obtain the removed components after the purge function has been called.

recover(log=True)[source]¶

The recover function appends components to the end of the list that have been deleted with the remove function. This does not include components that were removed before the purge function was last executed.

Parameters

log (bool=True) - Send a message to the logger

Returns

bool

Examples

cl.open('crux.cl')
cl.remove(1)
cl.recover()

remove(which=[- 1], log=True)[source]¶

The remove function removes the specified component(s) from the list. Components are specified by numbering them from one to the length of the list. So removing component one will remove the first component. After using this function all the remaining components will be shuffled down so that component two becomes component one. You cannot remove components from a list that has been opened read only.

You can specify a vector of indices to remove a number of components at once. For example in a five element list removing elements [1,3,5] will result in a two element list, now indexed as elements one and two, containing what was previously the second and fourth components.

Components that have been deleted using this function are not lost. The recover function can be used to get them back unless the purge function has been executed. Then they are completely gone.

Parameters

which (intVec=[-1]) - indices of which component(s) to remove a vector containing unique integers between 0 and one less than the length of the list, -1 for all
log (bool=True) - Send a message to the logger

Returns

bool

Examples

cl.open('crux.cl')
cl.remove(1)

rename(filename='', log=True)[source]¶

The rename function is used to specify the name of the table associated with this componentlist.

When a componentlist is created it is not associated with an casa table. So when the componentlist is removed from memory its contents are lost. But if a name is attached to the componentlist, using the rename function, then its contents are saved in a table with the specified name when the componentlist is closed

NOTE: that by just using rename the componentlist is not ensured to be on disk; to be sure use close after rename

If the componentlist is created using the open() constructor then this function will rename the table associated with the list to the user specified name. You cannot rename a componentlist that has been opened read only.

Parameters

filename (string='') - The filename of the table
log (bool=True) - Send a message to the logger

Returns

bool

Examples

cl.simulate(1);
cl.setshape(0, 'gaussian', '35mas', '27mas', '-10d')
cl.setflux(0, [1.0, 0.2, 0.1, 0.01]);
cl.rename('smallblob.cl');
cl.close();

cl.open('smallblob.cl')
n=cl.length()

This example starts with an  empty componentlist tool and then adds
one component to it. The parameters of this component are then
modified to change the shape and flux and the list saved in the
casa table called 'smallblob.cl' The data is not written to
disk until the list is closed, and when it is the componentlist is
reset. So you need to reopen it if you want to interact with it.

replace(which='', list='', whichones=[- 1])[source]¶

The replace function replaces the components from the list with the specified components from another list. The source list can be opened readonly and the length of the vectors in the first and third arguments must the the name.

You cannot replace components in a list that has been opened read only.

Parameters

which (int='') - A vector of indices specifying the components to replace. A vector with indices between 0 and one less than the list length, inclusively
list (record='') - The list containing the components to copy. A componentlist tool
whichones (intVec=[-1]) - A vector of indices specifying the components to copy A vector with indices between 1 and the length of the list in the second argument

Returns

bool

sample(direction='J2000 00h00m00.00 90d00m00.0', pixellatsize='0.0deg', pixellongsize='0.0deg', frequency='1.4GHz')[source]¶

The sample function will returns a vector containing the flux in Janskys/pixel of all the components in the list, in the specified direction, at the specified frequency. The returned vector always contains four elements corresponding to the Stokes parameters I,Q,U,V.

Parameters

direction (any='J2000 00h00m00.00 90d00m00.0') - The direction to sample any valid direction measure. A valid Direction measure or vector of string or string, e.g me.direction(‘J2000’,’19h30m00’, ‘-20d00m00’) or [‘J2000’,’19h30m00’, ‘-20d00m00’] or ‘J2000 19h30m00 -20d00m00’
pixellatsize (any='0.0deg') - the x-size of the in pixels to use when sampling any quantity that has angular units.
pixellongsize (any='0.0deg') - the y-size of the in pixels to use when sampling any quantity that has angular units.
frequency (any='1.4GHz') - The frequency to sample at Any frequency measure

Returns

doubleVec

select(which='')[source]¶

The select function is used to mark the specified components as “selected”. This function will be used in conjunction with the planned graphical user interface. Other functions functions in the componentlist tool will behave no differently if a component is marked as “selected”.

Components are not selected when the list is initially read from disk or when a new component is added to the list using the simulate function.

Parameters

which (intVec='') - A vector of indices. Indices must be between 0 and one less than the list length, inclusively

Returns

bool

Examples

cl.open('crux.cl')
cl.select([1,3])

selected()[source]¶

The selected function is used to determine which components in a list are selected. It returns a vector with indices that indicate which components are selected. A zero length vector is returned if no components are selected.

Components are marked as selected using the select function. This function will be used in conjunction with the graphical user interface and other functions in the componentlist tool will behave no differently if a component is marked as “selected” or not.

setflux(which='', value='', unit='Jy', polarization='circular', error='', log=True)[source]¶

The setflux function is used to reassign the flux of the specified components to a new value. The flux value, unit and polarization can be specified and any number of components can be set to the new value. (Currently, the parameter, error is ignored.)

Parameters

which (int='') - A vector of indices specifying the components to modify. A vector with indices between 0 and one less than the list length, inclusively
value (any='') - The flux values for the specified components A vector with four real or complex numbers
unit (string='Jy') - The units of the flux. Any string with the same dimensions as the Jansky
polarization (string='circular') - The polarization of the value field
error (any='') - The error in the value field. A complex vector of length four.
log (bool=True) - Send a message to the logger

Returns

bool

Examples

cl.open('crux.cl');
cl.setflux(0, [1,0,0,0], unit='jy', 
        polarization='Stokes', error=[.3, 0, 0, 0])

setfreq(which='', value='', unit='GHz', log=True)[source]¶

The setfreq function sets the reference frequency of the specified components to a new value. The frequency is defined by separately specifying the value and its units. Use the setfreqframe function to set the frequency reference frame

Parameters

which (int='') - An index specifying the component to modify An integer between 0 and one less than the list length, inclusively
value (double='') - The new frequency value. A number
unit (string='GHz') - The units of the frequency. Any string with the same dimensions as the ‘Hz’
log (bool=True) - Send a message to the logger

Returns

bool

Examples

cl.open('centarusA.cl')
cl.setfreq(1, 1.415, 'GHz')

setfreqframe(which='', frame='TOPO', log=True)[source]¶

The setfreqframe function sets the reference frame for the reference frequency of the specified components.

Currently the reference frame does not include additional information like when are where the observation took place. Hence no conversion between reference frames is available. In the interim I recommend you always use the same frame.

Parameters

which (int='') - An index specifying the component to modify. An integer between 0 and one less than the list length, inclusively
frame (string='TOPO') - The new reference frame, A string like ‘LSRK’, ‘LSRD’, ‘GEO’ or ‘TOPO
log (bool=True) - Send a message to the logger

Returns

bool

Examples

cl.open('centarusA.cl')
cl.setfreqframe(0, 'LSRK')

setlabel(which='', value='', log=True)[source]¶

The setlabel function is used to reassign the label (an arbitrary text string) of the specified components to a new value.

Parameters

which (int='') - An index specifying the component to modify. An integer between 0 and one less than the list length, inclusively
value (string='') - The label for the specified components
log (bool=True) - Send a message to the logger

Returns

bool

Examples

cl.open('centarusA.cl')
cl.setlabel(1, 'Core')

setrefdir(which=1, ra='', dec='', log=True)[source]¶

The setrefdir function sets the reference direction of the specified components to a new value. The direction is defined by separately specifying the right ascension and the declination.

The right ascension is specified as a string or a real number

Ra can be in standard angle units ’deg’, ’rad’, or time formatted as such ’HH:MM:SS.sss’ eg., ’19:34:63.8’ or angle formatted as such ’+DDD.MM.SS.sss’ eg., ’127.23.12.37’.

Similarly the declination is specified as a string or a real number and the decunit can be any angular unit or ’angle’ or ’time’.

Parameters

which (int=1) - A vector of indices specifying the components to modify. A vector with indices between 0 and one less than the list length, inclusively
ra (any='') - The RA of the new direction, A formatted string or a number
dec (any='') - The declination of the new direction. A formatted string or a number
log (bool=True) - Send a message to the logger

Returns

bool

Examples

cl.simulate(3)
cl.setrefdir(0, '12:26:35.9', '-63.5.56')
cl.setrefdir(1, '12h26m35.9', '-63d5m56')
cl.setrefdir(2, '-173.35deg', '-1.10128rad')
cl.rename('testcls.cl')  
cl.close() # write to disk

setrefdirframe(which='', frame='', log=True)[source]¶

The setrefdirframe function sets the reference frame for the reference direction of the specified components (what a mouthful)!

Currently the reference frame does not include additional information like when and where the observation took place. Hence only reference frames that are independent of this information can be used. This includes the common ones of ’J2000’, ’B1950’, and ’Galactic’. The measures module contains a complete listing of all possible reference frames. The parsing of the reference frame string is case-insensitive.

Parameters

which (int='') - A vector of indices specifying the components to modify. A vector with indices between 0 and one less than the list length, inclusively
frame (string='') - The new reference frame, A string like ‘B1950’, ‘J2000’ or ‘galactic’
log (bool=True) - Send a message to the logger

Returns

bool

Examples

cl.open('crux.cl');
cl.setrefdirframe(0, 'B1950');

setshape(which='', type='disk', majoraxis='1.0arcmin', minoraxis='1.0arcmin', positionangle='0.0deg', majoraxiserror='0.0arcmin', minoraxiserror='0.0arcmin', positionangleerror='0.0deg', optionalparms=[0.0], log=True)[source]¶

The setshape function changes the shape of the specified components to the user specified shape.

The type argument defines what the sort of new shape to use. This can be either ’point’, ’Gaussian’, or ’disk’. The parsing of this string is case insensitive.

If the shape type is ’point’ then the remaining arguments in this function are ignored. There are no other parameters needed to specify a point shape.

But if the shape is ’Gaussian’, or ’disk’, the remaining arguments are needed to fully specify the shape. The majoraxis, minoraxis and positionangle arguments are quantities (see the quanta module for a definition of a quantity). Hence they can be specified either as with string eg., ’1arcsec’ or with a record eg., [value=1, unit=’deg’].

The major axis is the width of the larger axis. For the Gaussian shape this is the full width at half maximum. And the minor axis is the width of the orthogonal axis. The positionangle is the specifies the rotation of these two axes with respect to a line connecting the poles of the current direction reference frame. If the angle is positive the the north point of the component moves in the eastern direction.

Parameters

which (int='') - A vector of indices specifying the components to modify. A vector with indices between 0 and one less than the list length, inclusively
type (string='disk') - The new shape type. A string that is either ‘point’, ‘Gaussian’, or ‘disk’
majoraxis (any='1.0arcmin') - The width of the larger axis. A quantity with angular units
minoraxis (any='1.0arcmin') - The width of the smaller axis. A quantity with angular units
positionangle (any='0.0deg') - The rotation of the axes with respect to the reference frame. A quantity with angular units
majoraxiserror (any='0.0arcmin') - Error of width of the larger axis. A quantity with angular units
minoraxiserror (any='0.0arcmin') - Error of the width of the smaller axis. A quantity with angular units
positionangleerror (any='0.0deg') - Error of the rotation of the axes with respect to the reference frame. A quantity with angular units
optionalparms (doubleVec=[0.0]) - optional parameters in a vector (for future use)
log (bool=True) - Send a message to the logger

Returns

bool

Examples

cl.open('crux.cl', nomodify=False)
cl.setshape(3, 'disk',  '45mas', '45mas')
print cl.getshape(3)['majoraxis']

setspectrum(which='', type='spectral index', index='0.0', tabularfreqs=[100000000000.0], tabularflux=[1.0], tabularframe='LSRK')[source]¶

The setspectrum function changes the spectrum of the specified components to the user specified spectrum.

The type argument defines what the sort of new spectrum to use. This can be one of ‘constant’, ‘tabular’, ‘plp’, or ‘spectral index’. Minimal match, case insensitive.

If the spectrum type is ‘constant’ then the remaining arguments in this function are ignored. There are no other parameters needed to specify a constant spectrum. The reference frequency is set to be the same value as the component being replaced. Although this is unimportant for a constant spectrum, it may be important if the spectral model of the component in question is changed again later. See rules to how the reference frequencies of various spectral models are set in the description below.

If the spectrum is ‘spectral index’, the ‘index’ argument is needed to fully specify the spectrum by using the index argument. The index parameter may be in the form of a single numerical value, or an array containing a numerical value. In the case of the array containing multiple values, the zeroth value is used as the value of index, while subsequent values are tacitly ignored. The functional form of this model is

R = x^(alpha)

where R = I_nu/I_nu0 is the ratio of the intensities at observed frequency nu and the reference frequency nu_0, x = nu/nu_0, and alpha is the specified spectral index. The reference frequency is tacitly set to that of the component being replaced. and can be changed by a subsequent call to setfreq().

If spectrum = ‘plp’, then the spectral model is set to a power log polynomial. The functional form of this model is

R = x^(c_0 + c_1*(ln(x)) + c_2*(ln(x))^2 + c_3*(ln(x))^3 + … + c_n*(ln(x))^n)

where R = I_nu/I_nu0 is the ratio of the intensities at observed frequency nu and the reference frequency nu_0, x = nu/nu_0, ln is the natural logarithm, and c_0 … c_n are the coefficients specified by index. In this case, index should be an array of numerical values, and the array length is unconstrained. The reference frequency is tacitly set to that of the component being replaced, and can be changed by a subsequent call to setfreq().

If the spectrum is ‘tabular’, then ‘index’ is ignored but the three parameters ‘tabularfreqs’, ‘tabularflux’ and ‘tabularframe’ are considered. ‘tabularfreqs’ and ‘tabularflux’ have to be list of same lengths and larger than 2. You need at least 2 samples to interpolate the spectral value in between. The flux of the source is interpolated from these values. Extrapolation outside the range given in ‘tabularfreqs’ is not done. ‘tabularfreqs’ should be float values in ‘Hz’ ‘tabularflux’ should be float values in ‘Jy’ The reference frequency is chosen to be the zeroth element of tabularfreqs.

You should ensure that the reference frequency is set to the value you desire, using the setfreq function if you change to the spectral index shape.

Parameters

which (int='') - The index specifying the component to modify. A value between 0 and one less than the list length, inclusively
type (string='spectral index') - The new spectrum type. A string that is one of ‘constant’, ‘spectral index’ ‘tabular’, or ‘plp’ (caseless, minimum match)
index (any='0.0') - The spectral index or coefficients for plp.
tabularfreqs (doubleVec=[1.0e11]) - The frequencies of for the tabular values, in Hz
tabularflux (doubleVec=[1.0]) - tabular flux density values, in Jy (same length as tabularfreqs)
tabularframe (string='LSRK') - For tabular models, the frame of the provided frequencies.

Returns

bool

Examples

cl.open('centarusA.cl')
cl.setspectrum(2, 'spectral index', -0.5)
print cl.getcomponent(2)['spectrum']['index']
cl.done()

This example revises the model for Centaurus-A changing the
spectral index of all the components in the left lobe. The
output from the print statement is "[-0.5 0 0 0]"

cl.addcomponent(shape='point', flux=[1.0, 0.0, 0.0, 0.0], dir='J2000 19h00m00 -20d00m00')
cl.setspectrum(which=0, type='tabular', tabularfreqs=[1.0e9, 1.1e9, 1.4e9], tabularflux=[1.0, 0.9, 0.75])
cl.rename('my19hcomp.cl')
cl.done()

In this example a component is created from scratch as a point
source The spectrum is set to, say, measured values at 3
frequencies (1GHz, 1.1GHz and 1.4GHz) to 1.0Jy, 0.9Jy, 0.75Jy
respectively.  Any frequency in between the range 1 to 1.4 GHz
the flux will be estimated by interpolation.

cl.open('my.cl')
cl.addcomponent(shape='point', flux=[1.0, 0.0, 0.0, 0.0], dir='J2000 19h00m00 -20d00m00')
cl.setspectrum(which=0, type='plp', index=[1, 2, 3])

In this example, the initial component's spectrum is modified to a power log polynomial
with the specified indices.

setstokesspectrum(which='', type='spectral index', index=[0.0], tabularfreqs=[100000000000.0], tabulari=[1.0], tabularq=[0.0], tabularu=[0.0], tabularv=[0.0], reffreq='1.4GHz', frame='LSRK')[source]¶

The setstokesspectrum function changes the spectrum of the specified components to the user specified spectrum. This is different from setspectrum as it provides ways to control variation of all 4 Stokes parameters with frequency. If only I variation is needed please use setspectrum

The type argument defines what the sort of new spectrum to use. This can be either ’constant’ or ’spectral index’ or ’tabular’. The parsing of this string is case insensitive.

If the spectrum type is ’constant’ then the remaining arguments in this function are ignored. There are no other parameters needed to specify a constant spectrum.

But if the spectrum is ’spectral index’, the ’index’ argument is needed. It is a 4 element vector.

The first element (\(\alpha_0\)) is the spectral index of stokes I (\(I(\nu)=I(\nu_0)({{\nu}\over{\nu_0}})^{\alpha_0}\))

The second element (\(\alpha_1\)) is a spectral index for the fractional linear polarization ( \(\sqrt{{{(Q(\nu)^2+U(\nu)^2)}\over{I(\nu)^2}}} = \sqrt{{{(Q(\nu_0)^2+U(\nu_0)^2)}\over{I(\nu_0)^2}}}({{\nu}\over{\nu_0}})^{\alpha_1}\)). \(\alpha_1=0\) implies constant fractional linear polarization w.r.t frequency.

The third element is a “Rotation Measure” factor, i.e angle of rotation \(\theta= \alpha_2 (\lambda^2 - \lambda_0^2)\) of the linear polarization at frequency \(\nu\) w.r.t frequency \(\nu_0\).

The fourth element is a spectral index for the fractional spectral polarization ( \({{V(\nu)}\over{I(\nu)}} = {{V(\nu_0)}\over{I(\nu_0)}}({{\nu}\over{\nu_0}})^{\alpha_3}\)

If the spectrum is ’tabular’, then index is ignored but the six parameters tabularfreqs, tabulari, tabularq, tabularu, tabularv and tabularframe are considered. tabularfreqs and tabulari, tabularq, tabularu, tabularv have to be list of same lengths and larger than 2. You need at least 2 samples to interpolate the spectral value in between. The Stokes parameters of the source is interpolated from these values. Extrappolation outside the range given in tabularfreqs is not done. tabularfreqs should be float values in ’Hz’ tabulari, tabularq, tabularu, tabularv should be float values in ’Jy’

You should ensure that the reference frequency is set to the value you desire, using the setfreq function if you change to the spectral index shape.

Parameters

which (int='') - The index specifying the component to modify. A value between 0 and one less than the list length, inclusively
type (string='spectral index') - The new spectrum type. A string that is either ‘constant or ‘spectral index’ or ‘tabular’
index (doubleVec=[0.0]) - The spectral index.
tabularfreqs (doubleVec=[1.0e11]) - The frequencies of for the tabular values, in Hz
tabulari (doubleVec=[1.0]) - tabular Stokes I values, in Jy (same length as tabularfreqs)
tabularq (doubleVec=[0.0]) - tabular Stokes Q values, in Jy (same length as tabularfreqs)
tabularu (doubleVec=[0.0]) - tabular Stokes U values, in Jy (same length as tabularfreqs)
tabularv (doubleVec=[0.0]) - tabular Stokes V values, in Jy (same length as tabularfreqs)
reffreq (any='1.4GHz') - The reference frequency for spectral index
frame (string='LSRK') - The frame for which the frequencies given are in

Returns

bool

Examples

   This example add a point source model and revises the model point source spectral variation  changing the spectral index  and setting the reference flux to be at 2GHz.
  I is assigned a spectral index of 1. fractional linear pol is assigned a spectral index of 0.4 and similarly for fraction circular pol and the linear pol angle is kept fixed with frequency.

 cl.addcomponent(shape='point', flux=[10.0, 0.4, -0.2, 0.1], dir='J2000 19h00m00 -20d00m00')
 cl.setstokesspectrum(which=0, type='spectral index', index=[1.0, 0.4, 0, 0.4], reffreq='2.0GHz')
 cl.rename('my19hcomp.cl')
 cl.done()



In this example a componentlist  is created from scratch and 2 sources are added
One whose spectral variation is defined by a spectral index and the other one as 
tabular values. Both components have full Stokes parameters spectral variation 
defined.

cl.done()  ### effectively resets state of cl tool
###add first component
cl.addcomponent(flux=[10, 0.5, -0.3, 0.2], dir='J2000 15h22m00 5d04m00')
cl.setstokesspectrum(which=0, type='spectral index', index=[1.0, 0.4, 0, 0.4], reffreq='2.0GHz')
###adding second component; flux value is unimportant as the tabular values will 
###will set it
cl.addcomponent(flux=[1.0, 0, 0, 0],dir='J2000 15h22m30 5d05m00')
##define the IQUV flux variation as tabular values at different frequencies.
cl.setstokesspectrum(which=1, type='tabular', tabularfreqs=[1.0e9, 1.1e9, 1.2e9, 1.3e9, 1.4e9, 1.5e9, 1.6e9], tabulari=[10.0, 10.1, 10.2, 10.2, 10.25, 10.3, 1.4], tabularq=[0.2, 0.2, 0.22, 0.23, 0.22, 0.24, 0.25], tabularu=[-0.1, -0.12, -0.13, -0.13, -0.12, -0.14, -0.15], tabularv=[0.1, 0.2, 0.2, 0.2, 0.3, 0.1, 0.15])
###saving the componentlist to disk
cl.rename('two_comp.cl')
cl.done()  ###done is needed to sync to disk

shapetype(which='')[source]¶

The shapetype function returns the current shape of the specified component. The shape defines how the flux of the component varies with direction on the sky. Currently there are three shapes available. These are ’Point’, ’Gaussian’, and ’Disk’. This function returns one of these four strings.

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

string

Examples

cl.open('crux.cl')
print 'The first component has a', cl.shapetype(0), ' shape'

simulate(howmany=1, log=True)[source]¶

The simulate function adds simulated components to the list. The simulation criterion is very simple, all the components added are identical! They are point sources at the J2000 north pole with a flux in Stokes I of 1 Jy, and zero in the other polarizations. The spectrum is constant. The ’set’ functions (eg. setflux, setfreq) can be used to change these parameters to desired ones.

The howmany argument indicates how many components to append to the list.

Parameters

howmany (int=1) - How many components to simulate, greater than zero
log (bool=True) - Send a message to the logger

Returns

bool

Examples

  cl.simulate(2)
  cl.setflux(1, [2.78, 0, 0, 0]);
  cl.rename('test.cl');
  cl.close();



This example creates a componentlist with two components.  The setflux function is used to
modify the second component.  The list is then saved on disk. 
I use short scripts like this a lot during testing. 

sort(criteria='Polarization', log=True)[source]¶

The sort function can sort all the components in a list using a variety of criteria. Currently the following criteria are available: Flux: Sorts the list so that the brightest components, as defined by Stokes I, are at the beginning of the list. Position: Sorts the list so that components that are closest to a reference position, which is currently fixed at (ra,dec)=(0,0), are at the beginning of the list. Polarization: Sorts the list so that components with the largest fractional polarization, sqrt(Q**2+U**2+V**2)/I, are at the front of the list. Components where I=0 are placed at the end of the list. The parsing of the string containg the sorting criteria is case insensitive. You cannot sort a list that has been opened read only.

Parameters

criteria (string='Polarization') - a string containg the criteria to use to sort the list
log (bool=True) - Send a message to the logger

Returns

bool

Examples

cl.open('crux.cl')
cl.sort('Polarization')

spectrumtype(which='')[source]¶

The spectrumtype function returns the current spectral shape of the specified component. The spectral shape defines how the flux of the component varies with frequency. Returns one of “Constant”, “Spectral Index”, “Tabular Spectrum”, and “Power Logarithmic Polynomial”.

Parameters

which (int='') - An index specifying which component. An integer between 0 and one less than the list length, inclusively

Returns

string

Examples

cl.open('crux.cl')
print 'The first component has a', cl.spectrumtype(1), ' spectrum'

summarize(which=- 1)[source]¶

The summarize function summarizes the contents of the specified components to the logger.

Parameters

which (int=-1) - An index specifying which component. Unset or an integer between 0 and one less than the list length, inclusive

Returns

bool

torecord()[source]¶: This function allows the componentlist to be converted to a record. Usually useful to pass to other functions in image analysis for e.g