exportuvfits

exportuvfits(vis, fitsfile='', datacolumn='corrected', field='', spw='', antenna='', timerange='', writesyscal=False, multisource=True, combinespw=True, writestation=True, padwithflags=False, overwrite=False)[source]

Convert a CASA visibility data set to a UVFITS file:

[Description] [Examples] [Development] [Details]

Parameters
  • vis (path) - Name of input visibility file

  • fitsfile (string=’’) - Name of output UV FITS file

  • datacolumn (string=’corrected’) - Visibility file data column

  • field ({string, stringVec, int, intVec}=’’) - Select field using field id(s) or field name(s)

  • spw (string=’’) - Select spectral window/channels

  • antenna (string=’’) - Select data based on antenna/baseline

  • timerange (string=’’) - Select data based on time range

  • writesyscal (bool=False) - Write GC and TY tables (not yet available)

  • multisource (bool=True) - Write in multi-source format?

  • combinespw (bool=True) - Export the spectral windows as IFs

    combinespw = True
    • padwithflags (bool=False) - Fill in missing data with flags to fit IFs

  • writestation (bool=True) - Write station name instead of antenna name

  • overwrite (bool=False) - Overwrite output file if it exists?

Description

The task exportuvfits takes a MeasurementSet and exports it to a UVFITS format file.

UVFITS is a general format dataset used to transfer data between different software systems. In CASA, exportuvfits is mainly developed to transfer data from CASA to AIPS, but it also serves the UVFITS format used in other software packages (e.g., MIRIAD). A UVFITS file is written in floating point format. exportuvfits accepts a number of parameters that can control what is written out (see e.g. the spw, multisource, combinespw parameter descriptions).

Warning

Exporting of MSs with Nant>255 via exportuvfits is implemented according to AIPS Memo 117, but should be considered experimental and datasets transported this way may not behave as expected in other packages (e.g., AIPS).

Warning

Some external software packages (e.g., GILDAS) cannot easily read CASA UVFITS files when more than one spectral window are exported in exportuvfits. In those cases, please export a single spectral window at a time by setting the ‘spw’ parameter.

The parameters of field, spw, antenna, and timerange select the data that are exported from the MS dataset. The datacolumn parameter chooses which data-containing column of the MS is to be written out to the UVFITS file. Choices are: ‘data’, ‘corrected’, ‘model’, and ‘weight’.

The multisource parameter determines whether the UVFITS file is a multi-source file or a single-source file, if you have a single-source MS or choose only a single source. Multi-source UVFITS files have multiple source IDs in the source (SU) table. Some programs (i.e. difmap) only accept single-source format files. Note that if you select more than one source in field, then the multisource parameter will be overridden to be True regardless.

MSes where the tuning changed with time should be exported to multiple UVFITS files using spw to select one tuning (set of simultaneous spectral windows) per file (e.g. 10 minutes at 4.8 GHz followed by 15 minutes at 8.4 GHz).

The combinespw parameter allows combination of all spectral windows at one time. If True, then all spectral windows must have the same shape. In other words, they should have the same number of channels and polarizations, and each channel must have the same width, and each IF (Intermediate Frequency) must be present (even if flagged) throughout the entire observation. If these conditions are met, all spectral windows are exported as a set of IFs in a single FREQID setup instead of giving each spectral window its own FREQID in the FITS file. (IF and FREQID are the identification number of a spectral window and the spectral set up of a baseband in the FITS file, respectively.) If these conditions are not met the data must be exported using multiple FREQIDs, the UVFITS equivalent of a general spectral window. This matters since many (sub)programs will work with multiple IFs, but not multiple FREQIDs. For example, a UVFITS file with multiple FREQIDs can be read by AIPS, but you may find that you have to separate the FREQIDs with split before you can do very much with them.

You can fill in missing data as needed to fit the IF structure using padwithflags option. To do that, not only set padwithflags =True, but also combinespw= True. This is appropriate if the MS had a few frequency-dependent flags applied, and was then time-averaged by split, or when exporting for use by difmap. If the spectral windows were observed at different times, padwithflags =True will add a large number of flags, making the output file significantly longer. It does not yet support spectral windows with different widths.

It is recommended to perform any required data averaging using other tasks (e.g., split or mstransform) before exporting the UVFITS file with exportuvfits.

A NOTE ON WEIGHTS: If the MS has no WEIGHT_SPECTRUM column, or if it does but that column contains no data, exportuvfits will compute for each visibility the weight it writes to the UVFITS file by dividing the associated WEIGHT column value in the MS by the number of channels in the relevant spectral window within which that visibility is located.

Optionally, the parameter overwrite can be use to overwrite existing uvfits files with the same name as that specified in the fitsfile parameter.

Examples

Create a uvfits file from an MS, overwriting the output file if it already exists.

exportuvfits(vis="my.ms", fitsfile="my.uvfits",
datacolumn="corrected", overwrite=True)
Development

No additional development details

Parameter Details

Detailed descriptions of each function parameter

vis (path) - Name of input visibility file
Default: none
Example: vis=’ngc5921.ms’
fitsfile (string='') - Name of output UV FITS file
Default: none
Example: vis=’ngc5921XC1.fits’
datacolumn (string='corrected') - Visibility file data column
Default: corrected
Options: ‘data’(raw)|’corrected’|’model’|’weight’
Example: datacolumn=’model’
field ({string, stringVec, int, intVec}='') - Select field using field id(s) or field name(s)
Default: ‘’ –> all fields

Use ‘go listobs’ to obtain the list id’s or
names. If field string is a non-negative integer,
it is assumed a field index, otherwise, it is
assumed a field name.
Examples:
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 (string='') - Select spectral window/channels
Examples:
spw=’0~2,4’; spectral windows 0,1,2,4 (all
channels)
spw=’<2’; spectral windows less than 2
(i.e. 0,1)
spw=’0:5~61’; spw 0, channels 5 to 61,
INCLUSIVE
spw=’*:5~61’; all spw with channels 5 to 61
spw=’0,10,3:3~45’; spw 0,10 all channels, spw
3, channels 3 to 45.
spw=’0~2:2~6’; spw 0,1,2 with channels 2
through 6 in each.
spw=’0:0~10;15~60’; spectral window 0 with
channels 0-10,15-60. (NOTE ‘;’ to separate
channel selections)
spw=’0:0~10^2,1:20~30^5’; spw 0, channels
0,2,4,6,8,10, spw 1, channels 20,25,30
type ‘help par.selection’ for more examples.
antenna (string='') - Select data based on antenna/baseline
Subparameter of selectdata=True
Default: ‘’ (all)
If antenna string is a non-negative integer, it
is assumed an antenna index, otherwise, it is
assumed as an antenna name

Examples:
antenna=’5&6’; baseline between antenna
index 5 and index 6.
antenna=’VA05&VA06’; baseline between VLA
antenna 5 and 6.
antenna=’5&6;7&8’; baselines with
indices 5-6 and 7-8
antenna=’5’; all baselines with antenna index
5
antenna=’05’; all baselines with antenna
number 05 (VLA old name)
antenna=’5,6,10’; all baselines with antennas
5,6,10 index numbers
timerange (string='') - Select data based on time range
Subparameter of selectdata=True
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
writesyscal (bool=False) - Write GC and TY tables. Not yet available.
Default: False
multisource (bool=True) - Write in multi-source format?
Default: True
Set to False if only one source is selected.
Note: diffmap does not work on multisource uvfits
files, so if planning on using diffmap on the
resulting uvfits file, select a single source and
set multisource = False. Otherwise use True. (If
multiple sources are selected, a multi-source
file will be written no matter what the setting
of this parameter).
combinespw (bool=True) - Export the spectral windows as IFs?
Default: True
If True, export the spectral windows as
IFs. All spectral windows must have same
shape. Otherwise multiple windows will use
multiple FREQIDs.
writestation (bool=True) - Write station name instead of antenna name
Default: True
padwithflags (bool=False) - Fill in missing data with flags to fit IFs
Subparameter of combinespw=True
Default: True

If True, and combinespw is True, fill in missing
data as needed to fit the IF structure. This is
appropriate if the MS had a few
frequency-dependent flags applied, and was then
time-averaged by split, or when exporting for use
by difmap. If the spectral windows were observed
at different times, padwithflags=True will add a
large number of flags, making the output file
significantly longer. It does not yet support
spectral windows with different widths.
overwrite (bool=False) - Overwrite output file if it exists?
Default: False
Options: False|True