# Source code for casatools.componentlist

#
# stub class definition file for docstring parsing
#

[docs]class componentlist:
"""
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).

"""

[docs]    def componentlist(self):
"""
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

"""

pass

[docs]    def open(self, filename='', nomodify=False, log=True):
"""
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.

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: Examples

::

cl.open('crux.cl')

"""

pass

[docs]    def asciitocomponentlist(self, filename='', asciifile='', refer='B1950', format='ST', direction='', spectrum='', flux='', log=True):
"""
This constructor will allow conversion of a number of ascii-file-based formats to componentlists.

.. rubric:: 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

.. rubric:: Returns

int

"""

pass

[docs]    def concatenate(self, list='', which=[-1], log=True):
"""
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.

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: 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.

"""

pass

[docs]    def fromrecord(self, record=''):
"""
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

.. rubric:: Parameters

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

.. rubric:: Returns

bool

.. rubric:: Examples

::

cl2 = cltool()

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

"""

pass

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

"""

pass

[docs]    def remove(self, which=[-1], log=True):
"""
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.

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def purge(self):
"""
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.

"""

pass

[docs]    def recover(self, log=True):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

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

"""

pass

[docs]    def indices(self):
"""
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.

"""

pass

[docs]    def sort(self, criteria='Polarization', log=True):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def isphysical(self, which=[-1]):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def sample(self, direction='J2000 00h00m00.00 90d00m00.0', pixellatsize='0.0deg', pixellongsize='0.0deg', frequency='1.4GHz'):
"""
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.

.. rubric:: 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

.. rubric:: Returns

doubleVec

"""

pass

[docs]    def rename(self, filename='', log=True):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

bool

.. rubric:: 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.

"""

pass

[docs]    def simulate(self, howmany=1, log=True):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

bool

.. rubric:: 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.

"""

pass

[docs]    def addcomponent(self, 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=''):
"""
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

.. rubric:: 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 either 'constant' or 'spectral index'
- index (double=1.0) - The spectral index
- optionalparms (doubleVec=[0.0]) - optional parameters in vector (for future use)
- label (string='') - The label for the component

.. rubric:: Returns

bool

"""

pass

[docs]    def close(self, log=True):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

bool

.. rubric:: Examples

::

See the example for the
rename function.

"""

pass

[docs]    def edit(self, which='', log=True):
"""
Start up the component editor gui (Not implemented yet)

.. rubric:: 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

.. rubric:: Returns

bool

"""

pass

[docs]    def done(self):
"""
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.

"""

pass

[docs]    def select(self, which=''):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def deselect(self, which=''):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def selected(self):
"""
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.

"""

pass

[docs]    def getlabel(self, which=''):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

string

.. rubric:: Examples

::

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

"""

pass

[docs]    def setlabel(self, which='', value='', log=True):
"""
The setlabel function is used to reassign the label (an arbitrary text string) of the specified components to a new value.

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def getfluxvalue(self, which=''):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

doubleVec

.. rubric:: 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.

"""

pass

[docs]    def getfluxunit(self, which=''):
"""
The getfluxunit function returns the units of the flux of the specified component. The actual values are obtained using the getfluxvalue function.

.. rubric:: Parameters

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

.. rubric:: Returns

string

.. rubric:: Examples

::

See the example for the
getfluxvalue function.

"""

pass

[docs]    def getfluxpol(self, which=''):
"""
The getfluxunit function returns the polarization representation of the flux of the specified component. The actual values are obtained using the getfluxvalue function.

.. rubric:: Parameters

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

.. rubric:: Returns

string

"""

pass

[docs]    def getfluxerror(self, which=''):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

doubleVec

"""

pass

[docs]    def setflux(self, which='', value='', unit='Jy', polarization='circular', error='', log=True):
"""
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.)

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def convertfluxunit(self, which='', unit='Jy'):
"""
The convertfluxunit function is used to convert the flux to another unit. The units *must* have the same dimensions as the Jansky.

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def convertfluxpol(self, which='', polarization='circular'):
"""
The convertfluxpol function is used to convert the flux to another polarization representation. There are are three representations used, namely , ’Stokes’, ’linear’ & ’circular’

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def getrefdir(self, which=''):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

record

.. rubric:: Examples

::

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

"""

pass

[docs]    def getrefdirra(self, which='', unit='deg', precision=6):
"""
Get the RA of the reference direction. (Not implemented not)

.. rubric:: 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

.. rubric:: Returns

string

"""

pass

[docs]    def getrefdirdec(self, which='', unit='deg', precision=6):
"""
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.

.. rubric:: 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

.. rubric:: Returns

string

.. rubric:: Examples

::

See the example for the
getrefdirra function.

"""

pass

[docs]    def getrefdirframe(self, which=''):
"""
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’.

.. rubric:: Parameters

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

.. rubric:: Returns

string

.. rubric:: Examples

::

See the example for the
getrefdirra function.

"""

pass

[docs]    def setrefdir(self, which=1, ra='', dec='', log=True):
"""
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’.

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def setrefdirframe(self, which='', frame='', log=True):
"""
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.

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def convertrefdir(self, which='', frame=''):
"""
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.

.. rubric:: 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'

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def shapetype(self, which=''):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

string

.. rubric:: Examples

::

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

"""

pass

[docs]    def getshape(self, which=''):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

record

.. rubric:: Examples

::

See the examples for the
setshape and
convertshape
functions.

"""

pass

[docs]    def setshape(self, 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):
"""
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.

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

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

.. rubric:: 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

.. rubric:: Returns

bool

"""

pass

[docs]    def spectrumtype(self, which=''):
"""
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. Currently there are two spectral shapes available. These are ’Constant’ and ’Spectral Index’. This function returns one of these two strings.

.. rubric:: Parameters

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

.. rubric:: Returns

string

.. rubric:: Examples

::

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

"""

pass

[docs]    def getspectrum(self, which=''):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

record

.. rubric:: Examples

::

See the examples for the
setspectrum and
getspectrum
functions.

"""

pass

[docs]    def setstokesspectrum(self, which='', type='spectral index', index=[0.0], tabularfreqs=[1.0e11], tabulari=[1.0], tabularq=[0.0], tabularu=[0.0], tabularv=[0.0], reffreq='1.4GHz', frame='LSRK'):
"""
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 (:math:\alpha\_0) is the spectral index of stokes I (:math:I(\nu)=I(\nu\_0)({{\nu}\over{\nu\_0}})^{\alpha\_0})

The second element (:math:\alpha\_1) is a spectral index for the fractional linear polarization ( :math:\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}). :math:\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 :math:\theta= \alpha\_2 (\lambda^2 - \lambda\_0^2) of the linear polarization at frequency :math:\nu w.r.t frequency :math:\nu\_0.

The fourth element is a spectral index for the fractional spectral polarization ( :math:{{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.

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: 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
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

"""

pass

[docs]    def setspectrum(self, which='', type='spectral index', index=0.0, tabularfreqs=[1.0e11], tabularflux=[1.0], tabularframe='LSRK'):
"""
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 either ’constant’or ’spectral index’. 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 to fully specify the spectrum by using the index argument.

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’

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.

.. rubric:: 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 (double=0.0) - The spectral index.
- 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') - The frame for which the frequencies given are in

.. rubric:: Returns

bool

.. rubric:: 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.

"""

pass

[docs]    def getfreq(self, which=''):
"""
Get the reference frequency (Not implemented yet)

.. rubric:: Parameters

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

.. rubric:: Returns

record

"""

pass

[docs]    def getfreqvalue(self, which=''):
"""
Get the reference frequency value (Not implemeted yet)

.. rubric:: Parameters

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

.. rubric:: Returns

double

"""

pass

[docs]    def getfrequnit(self, which=''):
"""
Get the reference frequency unit (Not implemeted yet)

.. rubric:: Parameters

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

.. rubric:: Returns

string

.. rubric:: Examples

::

See the example for the
getfreqvalue function.

"""

pass

[docs]    def getfreqframe(self, which=''):
"""
Get the reference frequency frame (Not implemeted yet)

.. rubric:: Parameters

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

.. rubric:: Returns

string

.. rubric:: Examples

::

See the example for the
getfreqvalue function.

"""

pass

[docs]    def setfreq(self, which='', value='', unit='GHz', log=True):
"""
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

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def setfreqframe(self, which='', frame='TOPO', log=True):
"""
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.

.. rubric:: 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

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def convertfrequnit(self, which='', unit='GHz'):
"""
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’.

.. rubric:: 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'

.. rubric:: Returns

bool

.. rubric:: Examples

::

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

"""

pass

[docs]    def getcomponent(self, which='', iknow=False):
"""
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.

.. rubric:: 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

.. rubric:: Returns

record

"""

pass

[docs]    def add(self, thecomponent='', iknow=True):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

bool

"""

pass

[docs]    def replace(self, which='', list='', whichones=[-1]):
"""
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.

.. rubric:: 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

.. rubric:: Returns

bool

"""

pass

[docs]    def summarize(self, which=-1):
"""
The summarize function summarizes the contents of the specified components to the logger.

.. rubric:: Parameters

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

.. rubric:: Returns

bool

"""

pass

[docs]    def iscomponentlist(self, tool=''):
"""
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.

.. rubric:: Parameters

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

.. rubric:: Returns

bool

"""

pass