|
|||
NRAO Home > CASA > CASA Task Reference Manual |
|
0.1.31 fluxscale
Requires:
Synopsis
Bootstrap the flux density scale from standard calibrators
Description
Bootstrap the flux density scale from standard calibrators:
After running gaincal on standard flux density calibrators (with or without an image model), and other calibrators with unknown flux densities (assumed 1 Jy), fluxscale applies the constraint that net system gain was, in fact, independent of field, on average, and that field-dependent gains in the input caltable are solely a result of the unknown flux densities for the calibrators. Using time-averaged gain amplitudes, the ratio between each ordinary calibrator and the flux density calibrator(s) is formed for each antenna and polarization (that they have in common). The average of this ratio over antennas and polarizations yields a correction factor that is applied to the ordinary calibrators’ gains. (See also more detailed discussion in Example section below.)
Arguments
Outputs |
| ||
fluxd |
| Dictionary containing the transfer fluxes and their
errors. | |
| allowed: | any |
|
| Default: | variant | |
Inputs |
| ||
vis |
| Name of input visibility file (MS)
| |
| allowed: | string |
|
| Default: |
| |
caltable |
| Name of input calibration table
| |
| allowed: | string |
|
| Default: |
| |
fluxtable |
| Name of output, flux-scaled calibration table
| |
| allowed: | string |
|
| Default: |
|
|
reference |
| Reference field name(s) (transfer flux scale FROM)
| |
| allowed: | stringArray |
|
| Default: |
|
|
transfer |
| Transfer field name(s) (transfer flux scale TO), ” -> all
| |
| allowed: | stringArray |
|
| Default: |
| |
listfile |
| Name of listfile that contains the fit information. Default
is ” (no file).
| |
| allowed: | string |
|
| Default: |
| |
append |
| Append solutions?
| |
| allowed: | bool |
|
| Default: | False |
|
refspwmap |
| Scale across spectral window boundaries. See help
fluxscale
| |
| allowed: | intArray |
|
| Default: | -1 |
|
gainthreshold |
| Threshold (% deviation from the median) on gain
amplitudes to be used in the flux scale calculation
| |
| allowed: | double |
|
| Default: | -1.0 |
|
antenna |
| antennas to include/exclude
| |
| allowed: | string |
|
| Default: |
|
|
timerange |
| sub selection by timerange
| |
| allowed: | string |
|
| Default: |
|
|
scan |
| sub selection by scan
| |
| allowed: | string |
|
| Default: |
|
|
incremental |
| incremental caltable
| |
| allowed: | bool |
|
| Default: | False |
|
fitorder |
| order of spectral fitting
| |
| allowed: | int |
|
| Default: | 1 |
|
display |
| display some statistics of flux scaling
| |
| allowed: | bool |
|
| Default: | False |
|
void
Example
After running gaincal on standard flux density calibrators (with or
without an image model), and other calibrators with unknown flux
densities (assumed 1 Jy), fluxscale applies the constraint that
net system gain was, in fact, independent of field, on average,
and that field-dependent gains in the input caltable are solely
a result of the unknown flux densities for the calibrators.
Using time-averaged gain amplitudes, the ratio between
each ordinary calibrator and the flux density calibrator(s) is
formed for each antenna and polarization (that they have in
common). For incremental=False(default), the median of
this ratio over antennas and polarizations yields a correction
factor that is applied to the ordinary calibrators’ gains. For
incremental=True, only the correction factors are written out
to the output fluxtable.
The square of the gain correction factor for each calibrator
and spw is the presumed flux density of that calibrator, and is
reported in the logger. The errors reported with this value
reflect the scatter in gain ratio over antennas and
polarizations, divided by the square root of the number of
antennas and polarizations available. If the flux densities
for multiple spws exist, fitted spectral index and (for nspw>2)
curvature are also reported. The fit is done for
log(flux density) = a_o + a_1*(log(frequency)) + a_2*(log(frequency))**2
where log(frequency) is with respect to the mean of log(frequency).
This reference frequency is reported in the logger along with the
flux density at that frequency. The fit results are also reported
in the returned Python dictionary (the solutions are in ’spidx’
in the following order: a_o [log(S) at the zero point], a_1 [spectral index],
and a_2 [curvature]. And their errors are in ’spidxerr’).
The MODEL_DATA column is currently _not_ revised to reflect the flux
densities derived by fluxscale. Use setjy to set the MODEL_DATA
column, if necessary.
The constant gain constraint is usually a reasonable assumption
for the electronic systems on typical antennas. It is
important that external time- and/or elevation-dependent
effects are separately accounted for when solving for the gain
solution supplied to fluxscale, e.g., gain curves,
opacity, etc. The fluxscale results can also be degraded
by poor pointing during the observation. The parameters, gainthreshold
and antenna (and timerange/scan) can be used to control the data to be used
in the flux derivation in such cases. The gainthreshold parameter sets the range of
the input gain to be used in terms of the percentage deviation from
their median values (per field, per spectral window). When the antenna
parameter is specified, the sub-parameters timerange and scan are also
available to fine tune the data selection for the flux derivation.
These parameters uses the general CASA data selection (msselection) syntax.
And these are ’AND’ operations except when the antenna selection is specified
with a negation (e.g. antenna="!6"). In that case, timerange and scan applied
to only those antennas appear in the antenna parameter. So, for example,
timerange=’>02:35:00’ with antenna=’!6,24’, will include the data with time greater than
02:35:00 for antenna ID 6 and 24 but for other antennas the timerange selection is not
applied.
Keyword arguments:
vis -- Name of input visibility file
default: none; example: vis=’ngc5921.ms’
caltable -- Name of input calibration table
default: none; example: caltable=’ngc5921.gcal’
This cal table was obtained from task gaincal.
fluxtable -- Name of output, flux-scaled calibration table
default: none; example: fluxtable=’ngc5921.gcal2’
The gains in this table have been adjusted by the
derived flux density each calibrator. The MODEL_DATA
column has NOT been updated for the flux density of the
calibrator. Use setjy to do this if it is a point source.
reference -- Reference field name(s)
The names of the fields with a known flux densities or
visibilities that have been placed in the MODEL column
by setjy or ft for a model not in the CASA system.
The syntax is similar to field. Hence field index or
names can be used.
default: none; example: reference=’1328+307’
transfer -- Transfer field name(s)
The names of the fields with unknown flux densities.
These should be point-like calibrator sources
The syntax is similar to field. Hence source index or
names can be used.
default: ’’ = all sources in caltable that are not specified
as reference sources. Do not include unknown target sources
example: transfer=’1445+099, 3C84’; transfer = ’0,4’
NOTE: All fields in reference and transfer must have solutions
in the caltable.
listfile -- Fit listfile name
The list file contains the flux density, flux density error,
S/N, and number of solutions (all antennas and feeds) for each
spectral window. NOTE: The nominal spectral window frequencies
will be included in the future.
default: ’’ = no fit listfile will be created.
append -- Append fluxscaled solutions to the fluxtable.
default: False; (will overwrite if already existing)
example: append=True
refspwmap -- Vector of spectral windows enabling scaling across
spectral windows
default: [-1]==> none.
Example with 4 spectral windows:
if the reference fields were observed only in spw=1 & 3,
and the transfer fields were observed in all 4 spws (0,1,2,3),
specify refspwmap=[1,1,3,3].
This will ensure that transfer fields observed in spws 0,1,2,3
will be referenced to reference field solutions only in
spw 1 or 3.
gainthreshold -- Threshold in the input gain solutions to be used in % deviation
from median values.
default: -1 (no threshold)
example: gainthreshold=0.15 (only used the gain solutions within 15%
(inclusive) of the median gain value (per field and per spw).
antenna --- Antenna selection to be included in the fluxscale determination.
General ms selection syntax is accepted such as antenna id (given as a string)
and antenna name.
default: ’’ (=All antennas will be used)
example: antenna=’!23’ (exclude antenna id, 23)
* Following sub-parameters are available when the antenna parameter is specified
timerange --- Select time range using the msselection syntax.
If the negation (e.g. ’!23’) is used in the antenna selection, it will apply
the time range selection only to the negated antenna(s). Otherwise, the selection
is global (i.e. applied to all antenna and to both reference and transfer fields.)
default: ’’ (all timerange)
example: timerange=">0:58:00"
scan --- Select scan(s) using the msselection syntax. As in the case of the timerange parameter
the selection will be applied to only the negated antenna(s) if the antenna parameter
is used with the negation ("!").
default: ’’ (all scans)
example: ’2~5’
incremental -- Create an incremental caltable containing only gain correction
factors ( flux density= 1/(gain correction factor)**2)
default: False; (older behavior = create flux-scaled gain table)
example: incremental=True (output a caltable containing flux scale factors.)
NOTE: If you use the incremental option, note that BOTH this incremental
fluxscale table AND an amplitude vs. time table should be supplied in applycal.
fitorder -- Polynomial order of the spectral fitting for valid flux densities
with multiple spws. Currently only support 1 (spectral index only) or
2 (spectral index and curvature). It falls back to a lower fitorder if
there are not enough solutions to fit with the requested fitorder.
default: 1
display -- Display statistics and/or spectral fitting results. Currently only a histogram
of the correction factors to derive the final flux density for each spectral window
will be plotted.
default: False
example: display=True
Returned dictionary:
when it is run as fluxres = fluxscale(vis=’my.ms’,...), the determined flux
densities and spectral index information are returned as a Python dictionary with
a format, {fieldIdstr: {spwIdstr: {’fluxd’:array([I,Q,U,V]),
’fluxdErr’: corresponding errors,
’numSol’: corresponding no. of solutions,
’fieldName’: field name,
’fitFluxd’: fitted flux density at the reference frequency,
’fitFluxdErr’: fitted flux density error,
’fitRefFreq’: reference frequency,
’spidx’: a_0, a_1, a_2
’spidxerr’: errors in a_0,a_1, a_2}
’freq’: (center) spw frequencies
’spwID’: list of spw IDs,
’spwName’: list of spw names}, where fieldIdstr and spwIdstr
are field Id and spw Id in string type, respectively.
More information about CASA may be found at the
CASA web page
Copyright © 2016 Associated Universities Inc., Washington, D.C.
This code is available under the terms of the GNU General Public Lincense
Home |
Contact Us |
Directories |
Site Map |
Help |
Privacy Policy |
Search