Fills the model column with the visibilities of a calibrator
The task sets the model visibility amp and phase of a specified source
(generally a calibrator). The simplest way is to enter the flux density
(I,Q,U,V) explicitly, but this is valid only for a point source.
For an extended source, the clean model (image.model) can be
specified and the model visibilities associated with this clean
model is placed in the visibility model column.
Models are available for 3C48, 3C138, 3C286 between 1.4 and 43 GHz.
3C147 is available above 4 GHz. These models are scaled to the precise
frequency of the data. Only I models are presently available.
The location of the models is system dependent: At the AOC and CV, the
models are in the directory::/usr/lib/casapy/data/nrao/VLA/CalModels or
/usr/lib64/casapy/data/nrao/VLA/CalModels (depending on whether 32 or 64
bit CASA was installed on the machine being used). In general (using
Python), the stock models should be in
casa['dirs']['data'] + '/nrao/VLA/CalModels'
setjy also looks for models in the current directory before trying
casa['dirs']['data'] + '/nrao/VLA/CalModels'.
setjy need only be run on the calibrator sources with a known flux
density and/or model.
Solar System Objects are supported via the 'Butler-JPL-Horizons 2012'
standard. This uses new brightness temperature models and a new flux
calculation code that replace the 'Butler-JPL-Horizons 2010' standard.
The older 'Butler-JPL-Horizons 2010' standard is still available
for comparison. Users may want to use predictcomp task to see the differeces.
Currently they are modeled as uniform temperature disks based
on their ephemerides at the time of observation (note that this may
oversimply objects, in particular asteroids). The object name is
obtained from the 'field' parameter. Recognized objects are listed
below, under 'standard'.
Note that fluxdensity, modimage, and standard interact in a possibly
confusing way! Generally, if fluxdensity[0] (Stokes I) is <= 0, it
will be ignored. If it is < 0, standard (which has a default) will
be used to calculate flux density as a function of frequency, even if
modimage is specified. If is is exactly 0 and modimage is given, the
brightness of the model image will be used as is. If fluxdensity([0])
is > 0, it will be used. The latter two options come at the price of
disabling frequency scaling, i.e. the same fluxdensity will be used for
all frequencies.
Keyword arguments:
vis -- Name of input visibility file
default: none. example: vis='ngc5921.ms'
field -- Select field using field id(s) or field name(s).
default: ''=all fields, but run setjy one field at a time.
[run listobs to obtain the list id's or names of calibrators]
If field is a non-negative integer, it is assumed to be a field
index. Otherwise, it is taken to be a field name (case sensitive
- it must match the name as listed by listobs).
field='0~2'; field ids 0,1,2
field='0,4,5~7'; field ids 0,4,5,6,7
field='3C286,3C295'; field named 3C286 and 3C295
field = '3,4C*'; field id 3, all names starting with 4C
spw -- Spectral window selection string.
default: '' = all spectral windows
Note that setjy only selects by spectral window, and ignores
channel selections. Fine-grained control could be achieved using
(and possibly constructing) a cube for modimage.
selectdata -- Other parameters for selecting part(s) of the MS
to operate on.
(Currently all time-oriented and most likely only of
interest when using a Solar System object as a calibrator.)
default: False
>>> selectdata=True expandable parameters
See help par.selectdata for more on these.
timerange -- Select data based on time range:
default: '' (all); examples,
timerange = 'YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss'
Note: if YYYY/MM/DD is missing date defaults to first
day in data set
timerange='09:14:0~09:54:0' picks 40 min on first day
timerange='25:00:00~27:30:00' picks 1 hr to 3 hr
30min on NEXT day
timerange='09:44:00' pick data within one integration
of time
timerange='>10:24:00' data after this time
For multiple MS input, a list of timerange strings can be
used:
timerange=['09:14:0~09:54:0','>10:24:00']
timerange='09:14:0~09:54:0''; apply the same timerange for
all input MSes
scan -- Scan number range.
default: '' (all)
example: scan='1~5'
For multiple MS input, a list of scan strings can be used:
scan=['0~100','10~200']
scan='0~100; scan ids 0-100 for all input MSes
Check 'go listobs' to insure the scan numbers are in order.
observation -- Observation ID range.
default: '' (all)
example: observation='1~5'
modimage -- Model image (I only) for setting the model visibilities.
modimage can be a cube, and its channels do not have to exactly
match those of vis. It is recommended to use modimage for
sources that are resolved by the observation, but the
Butler-JPL-Horizons standard supplies a basic model of what
several Solar System objects look like. default: '': do not use
a model image.
Each field must be done separately when using a model image. The
flux density of the image will be scaled from the frequency in
the model to that actually used (ignoring fluxdensity), unless
fluxdensity >= 0 (or fluxdensity[0] >= 0). If
fluxdensity([0]) is 0.0, the image's flux density will be used.
If fluxdensity([0]) > 0.0, it will be used (and spix and
reffreq if modimage is not a cube). Since the spectral index
usually varies with direction, applying a single spectral index
to a 2D modimage is typically not as good as using a cube.
Both the amplitude and phase are calculated. At the AOC or CV,
the models are located in casa['dirs']['data']
+ '/nrao/VLA/CalModels/', e.g.
/usr/lib/casapy/data/nrao/VLA/CalModels/3C286_L.im
lib64
If modimage does not start with '/', setjy will look for a match
in '.', './CalModels', and any CalModels directories within
the casa['dirs']['data'] tree (excluding certain branches).
Note that modimage should be deconvolved, i.e. a set of clean
components instead of an image that has been convolved with a
clean beam.
listmodels -- If True, do nothing but list candidates for modimage
(for extragalactic calibrators) that are present on the system. It looks for *.im* *.mod* in .,
CalModels, and CalModels directories in the casa['dirs']['data']
tree. It does not check whether they are appropriate for the MS!
If standard='Butler-JPL-Horizons 2012', Tb models (frequency-depended
brightness temperature models) for Solar System objects used in the
standard. For standard='Butler-JPL-Horizons 2010', the recognized
Solar System objects are listed.
scalebychan -- This determines whether the fluxdensity set in the model is
calculated on a per channel basis. If False then it only one
fluxdensity value is calculated per spw. (Either way, all channels
in spw are modified.) It is effectively True if fluxdensity[0] >
0.0.
default: True
fluxdensity -- Specified flux density [I,Q,U,V] in Jy
default: -1, uses [1,0,0,0] flux density for unrecognized sources,
and standard flux densities for ones recognized by 'standard',
including 3C286, 3C48, 3C147, and several planets, moons, and
asteroids. setjy will try to use standard if fluxdensity is not
positive.
Only one flux density can be specified at a time. The phases are
set to zero.
example fluxdensity=-1 will use standard for recognized
calibrators (like 3C286, 3C147 and 3C48, depending on
standard) and insert 1.0 for selected fields with
unrecognized sources.
example field = '1'; fluxdensity=[3.2,0,0,0] wil put in
a flux density of I=3.2 for field='1'
At present (June 2000), this is the only method to insert a
polarized flux density model.
example: fluxdensity=[2.63,0.21,-0.33,0.02]
will put in I,Q,U,V flux densities of 2.63,0.21,-0.33,
and 0.02, respectively, in the model column.
spix -- Spectral index for fluxdensity:
S = fluxdensity * (freq/reffreq)**spix
Default: 0 (no effect)
Only used if fluxdensity is being used.
N.B.: If fluxdensity is positive, and spix is nonzero, then reffreq
must be set too! (See below)
It is applied in the same way to all polarizations, and does
not account for Faraday rotation or depolarization.
reffreq -- The reference frequency for spix, given with units.
Default: '1GHz'; this is only here to prevent division by 0!
N.B.: If the flux density is being scaled by spectral index,
then reffreq must be set to whatever reference frequency is
correct for the given fluxdensity and spix. It cannot be
determined from vis. On the other hand, if spix is 0, then any
positive frequency can be used (and ignored).
Examples: '86.0GHz', '4.65e9Hz'
standard -- Flux density standard, used if fluxdensity[0] < 0.0
default: 'Perley-Butler 2010'; example: standard='Baars'
Options: 'Baars','Perley 90','Perley-Taylor 95',
'Perley-Taylor 99', 'Perley-Butler 2010', 'Perley-Butler 2013',
'Butler-JPL-Horizons 2010', and 'Butler-JPL-Horizons 2012'.
All but the last two are for extragalactic calibrators,
and the final two are for Solar System objects.
Extragalactic calibrators:
Following source names and their common aliases are recognized.
The last column shows which standards support for each source.
Note that the task does not do exact matching of the name and
it recognizes as long as the field name contains the string
listed below (e.g. 'PKS 1934-638' works).
-----------------------------------------------------------
3C Name B1950 Name J2000 Name Alt. J2000 Name standards*
3C48 0134+329 0137+331 J0137+3309 1,3,4,5,6
3C123 0433+295 0437+296 J0437+2940 2
3C138 0518+165 0521+166 J0521+1638 1,3,4,5,6
3C147 0538+498 0542+498 J0542+4951 1,3,4,5,6
3C196 0809+483 0813+482 J0813+4813 1,2
3C286 1328+307 1331+305 J1331+3030 1,2,3,4,5,6
3C295 1409+524 1411+522 J1411+5212 1,2,3,4,5,6
- 1934-638 - J1939-6342 1,3,4,5,6
-----------------------------------------------------------
* supported in: 1 - Perley-Butler 2010, 2 - Perley-Butler 2013,
3 - Perley-Taylor 99, 4 - Perley-Taylor 95, 5 - Perley 90, 6 - Baars
Solar system objects:
The 'Butler-JPL-Horizons 2012' standard is recommended over
'Butler-JPL-Horizons 2010' as the former uses updated models.
Recognized Solar System objects (for 'Butler-JPL-Horizons 2012') are:
Planets: Venus, Mars, Jupiter, Uranus, Neptune
Moons: Jupiter: Io, Europa, Ganymede, Callisto
Saturn: Titan
Asteroids: Ceres, Pallas**, Vesta**, Juno**
* Venus: model for ~300MHz to 350GHz, no atmospheric lines (CO,H2O,HDO, etc)
* Mars: tabulated as a function of time and frequency (30 - 1000GHz) based on
Rudy el tal (1988), no atmopheric lines (CO, H20, H2O2, HDO, etc)
* Jupiter: model for 30-1020GHz, does not include synchrotron emission
* Uranus: model for 60-1800GHz, contains no rings or synchrotron.
* Neptune: model for 2-2000GHz, the broad CO absorption line
is included, but contains no rings or syncrotron.
* Titan: model for 53.3-1024.1GHz, include many spectral lines
** not recommended (The temperature is not yet adjusted for
varying distance from the Sun. The model data can be scaled
after running setjy, but it is an involved process.)
The 'field' parameter must match the case of the field name(s)
in vis (as shown by listobs).
Flux density calculation with Solar System objects depends on
ephemerides. The setjy task looks for the data in
os.getenv('CASAPATH').split()[0] + '/data/ephemerides/JPL-Horizons'.
If no ephemeris for the right object at the right time is
present, the calculation will fail. Ask the helpdesk to make an
ephemeris. The very adventurous and well versed in python can
try it using CASA's recipes.ephemerides package:
import recipes.ephemerides as eph
help eph
CASA comes with ephemerides for several more objects, but they
are intended for use with me.framecomet(), and are not (yet)
suitable flux density calibrators. It is up to the observer to
pick a good flux density calibrator (bright, spherical and
featureless, on a circular orbit, in the right part of the sky,
and not too resolved). Even some of the objects listed above
may prove to require more sophisticated flux density models than
are currently implemented in CASA. For many objects running
casalog.filter('INFO1') before running setjy will send more
information to the logger. The cookbook also has an appendix
with descriptions of the models used by setjy (both
extragalactic and Solar System).
>>> standard="Butler-JPL-Horizons 2012" expandable parameter
useephemdir -- If True: use the direction from the ephemeris table for
the solar system object.
default: False -use the direction information in the MS(i.e. Field table)
usescratch -- If False: 'virtual' model is created. The model is saved in the header
and model visibilities are evaluated when calculating calibration or plotting in plotms.
If True: the model visibility will be evaluated and saved on disk in the MODEL_DATA
column. This will increase your ms in size by a factor of 1.5 (w.r.t. the case where
you only have the DATA and the CORRECTED_DATA column). Use True if you need to interact
with the MODEL_DATA in python, say.
*By running usescratch=T, it will remove the existing virtual model from previous runs.
usescratch=F will not remove the existing MODEL_DATA but in subsequent process
the virtual model with matching field and spw combination will be used if it exists
regardless of the presence of the MODEL_DATA column.
default: False 
1.8.0