drivecasa.commands - Convenience routines for building command lists

This subpackage provides convenience functions for composing casapy data-reduction scripts.

While the casapy scripts can be composed by hand, use of convenience functions helps to prevent syntax errors, and allows for various optional extras such as forcing overwriting of previous datasets, automatic derivation of output filenames, etc.

drivecasa.commands.reduction - Data reduction commands

Note

All the data-reduction command composing functions have a common set of parameters:
  • script: The list to which the requested commands should be appended.
  • out_dir: The output directory to place output files in, using a derived filename.
  • out_path: Overrides out_dir, specifies an output file / directory path exactly.
  • overwrite: Deletes any pre-existing data at the output location - use with caution!

The composing functions return the paths to the files which should be created once the scripted command has been executed.

class drivecasa.commands.reduction.CleanMaps

A namedtuple for bunching together the paths to maps produced by clean.

Fields: ('image', 'model', 'residual', 'psf', 'mask')

drivecasa.commands.reduction.clean(script, vis_paths, niter, threshold_in_jy, mask='', modelimage='', other_clean_args=None, out_dir=None, out_path=None, overwrite=False)

Perform clean process to produce an image/map.

If out_path is None, then the output basename is derived by appending a .clean or .dirty suffix to the input basename. The various outputs are then further suffixed by casa, e.g. foo.clean.image, foo.clean.psf, etc. Since multiple outputs are generated, this function returns a CleanMaps object detailing the expected paths.

NB Attempting to run with pre-existing outputs and overwrite=False will not throw an error, in contrast to most other routines. From the CASA cookbook, w.r.t. the outputs:

“If an image with that name already exists, it will in general be overwritten. Beware using names of existing images however. If the clean is run using an imagename where <imagename>.residual and <imagename>.model already exist then clean will continue starting from these (effectively restarting from the end of the previous clean). Thus, if multiple runs of clean are run consecutively with the same imagename, then the cleaning is incremental (as in the difmap package).”

You can override this behaviour by specifying overwrite=True, in which case all pre-existing outputs will be deleted.

NB niter = 0 implies create a ‘dirty’ map, outputs will be named accordingly.

Warning

This function can accept a list of multiple input visibilities. This functionality is not extensively tested and should be considered experimental - the CASA cookbook is vague on how parameters should be passed in this use-case.

Returns:expected_map_paths – namedtuple,
listing paths for resulting maps.
Return type:CleanMaps
drivecasa.commands.reduction.concat(script, vis_paths, out_basename=None, out_dir=None, out_path=None, overwrite=False)

Concatenates multiple visibilities into one.

By default, output basename is derived by concatenating the basenames of the input visibilities, with the prefix concat_. However, this can result in something very long and unwieldy. Alternatively you may specify the exact out_path, or just the out_basename.

Returns:Path to concatenated ms.
drivecasa.commands.reduction.export_fits(script, image_path, out_dir=None, out_path=None, overwrite=False)

Convert an image ms to FITS format.

Returns:Path to resulting FITS file.
drivecasa.commands.reduction.import_uvfits(script, uvfits_path, out_dir=None, out_path=None, overwrite=False)

Import UVFITS and convert to .ms format.

If out_path is None, a sensible output .ms directory path will be derived by taking the FITS basename, switching the extension to .ms, and locating as a subdirectory of out_dir, e.g. if uvfits_path = '/my/data/obs1.fits', out_dir = '/tmp/junkdata' then the output data will be located at /tmp/junkdata/obs1.ms.

Parameters:
  • script – List to which the relevant casapy command line will be appended.
  • uvfits_path – path to input data file.
  • out_dir – Directory in which to place output file. None signifies to place output .ms in same directory as the original FITS file.
  • out_path – Provides an override to the automatic output naming system. If this is not None then the out_dir arg is ignored and the specified path used instead.
  • overwrite – Delete any pre-existing data at the output path (danger!).
Returns:

Path to newly converted ms.

drivecasa.commands.reduction.mstransform(script, vis_path, out_path, other_transform_args=None, overwrite=False)

Useful for pre-imaging steps of interferometric data reduction.

Guide: http://www.eso.org/~scastro/ALMA/casa/MST/MSTransformDocs/MSTransformDocs.html

Returns:out_path

drivecasa.commands.simulation - simulation commands

Provides convenience functions for composing casapy simulation scripts.

drivecasa.commands.simulation.close_sim(script)

Flush simulated data to disk and close simulator tool (sm.close())

cf https://casa.nrao.edu/docs/CasaRef/simulator.close.html

drivecasa.commands.simulation.corrupt(script)

Apply pre-configured simulated noise via sm.corrupt

cf https://casa.nrao.edu/docs/CasaRef/simulator.corrupt.html

drivecasa.commands.simulation.format_astropy_skycoord_as_casa_direction(skycoord)
Parameters:skycoord (astropy.coordinates.SkyCoord) – Sky position

Returns (str): casa me.direction instantiation expression.

drivecasa.commands.simulation.format_astropy_time_as_casa_epoch(time)
Parameters:time (astropy.time.Time) – Reference time
Returns (str): casa me.epoch instantiation expression
(uses UTC conversion from astropy Time).
drivecasa.commands.simulation.make_componentlist(script, source_list, out_path, overwrite=True)

Build a componentlist and save it to disk.

Runs cl.done() to clear any previous entries, the cl.addcomponent for each source in the list, and finally cl.rename, cl.close.

cf https://casa.nrao.edu/docs/CasaRef/componentlist-Tool.html

Typically used when simulating observations.

Parameters:
  • script (list) – List of strings to append commands to.
  • source_list – List of (position, flux, frequency) tuples. Positions should be astropy.coordinates.SkyCoord instances, while flux and frequency should be quantities supplied using the astropy.units functionality.
  • out_path (str) – Path to save the component list at
  • overwrite (bool) – Delete any pre-existing component list at out_path.
drivecasa.commands.simulation.observe(script, stop_delay, start_delay=<Quantity 0.0 s>)

Simulate an empty-field observation’s UVW data with sm.observe

cf https://casa.nrao.edu/docs/CasaRef/simulator.observe.html

Parameters:
  • stop_delay (astropy.units.Quantity) – Time-span. Stop observing this long after the reference time defined by settimes().
  • start_delay (astropy.units.Quantity) – Time-span. Start observing this long after the reference time defined by settimes(). (Defaults to 0, so the observation starts immediately at the reference time).
drivecasa.commands.simulation.predict(script, component_list_path)

Use sm.predict to add synthetic source-visibilities to a MeasurementSet.

cf https://casa.nrao.edu/docs/CasaRef/simulator.predict.html

drivecasa.commands.simulation.set_simplenoise(script, noise_std_dev)

Use sm.setnoise to assign a simple fixed-sigma noise to visibilities.

cf https://casa.nrao.edu/docs/CasaRef/simulator.setnoise.html

NB should be followed by a call to corrupt to actually apply the noise addition.

drivecasa.commands.simulation.setauto(script, autocorr_weight=0.0)

Set autocorrelation weight with sm.setauto.

cf https://casa.nrao.edu/docs/CasaRef/simulator.setauto.html

Parameters:
  • script (list) – casapy script-list
  • autocorr_weight (float) – Weight to assign autocorrelations
drivecasa.commands.simulation.setconfig(script, telescope_name, antennalist_path)

Configure the telescope parameters with sm.setconfig

cf https://casa.nrao.edu/docs/CasaRef/simulator.setconfig.html

Parameters:
  • script (list) – casapy script-list
  • telescope_name (str) – e.g. ‘VLA’
  • antennalist_path (str) – antenna-list config file
drivecasa.commands.simulation.setfeed(script, mode='perfect X Y', pol=[''])

Set feed polarisation with sm.setfeed

cf https://casa.nrao.edu/docs/CasaRef/simulator.setfeed.html

Parameters:
  • script (list) – casapy script-list
  • mode (str) – choice between ‘perfect R L’ and ‘perfect X Y’
  • pol (str) – Polarization (undocumented).
drivecasa.commands.simulation.setfield(script, pointing_centre)

Set pointing centre of simulated field of view with sm.setfield.

cf https://casa.nrao.edu/docs/CasaRef/simulator.setfield.html

Parameters:
drivecasa.commands.simulation.setlimits(script, shadow_limit=0.001, elevation_limit=<Quantity 15.0 deg>)

Set shadowing / elevation limits before simulated data are flagged.

Runs sm.setlimits cf https://casa.nrao.edu/docs/CasaRef/simulator.setlimits.html

Parameters:
  • script (list) – casapy script-list
  • shadow_limit (float) – Maximum fraction of geometrically shadowed area before flagging occurs
  • elevation_limit (astropy.units.Quantity) – Minimum elevation angle before flagging occurs
drivecasa.commands.simulation.setpb(script, telescope_name, primary_beam_hwhm, frequency)

Configure Gaussian primary beam parameters for a measurement simulation.

Runs vp.setpbgauss cf https://casa.nrao.edu/docs/CasaRef/vpmanager.setpbgauss.html

Parameters:
  • script (list) – casapy script-list
  • telescope_name (str) – e.g. ‘VLA’
  • primary_beam_hwhm (astropy.units.Quantity) – HWHM radius, i.e. angular radius to point of half-maximum in primary beam.
  • frequency (astropy.units.Quantity) – Reference frequency for primary beam.
drivecasa.commands.simulation.setspwindow(script, freq_start, freq_resolution, freq_delta, n_channels, stokes='XX XY YX YY')

Define a spectral window with sm.setspwindow.

cf https://casa.nrao.edu/docs/CasaRef/simulator.setspwindow.html

Parameters:
drivecasa.commands.simulation.settimes(script, integration_time, reference_time)

Set integration time, reference time with sm.settimes

cf https://casa.nrao.edu/docs/CasaRef/simulator.settimes.html

The ‘reference time’ defines an epoch, start and stop are defined relative to that epoch.

Parameters: