.. Copyright 2009-2012 Peter Williams

   This file is part of miriad-python.

   Miriad-python is free software: you can redistribute it and/or
   modify it under the terms of the GNU General Public License as
   published by the Free Software Foundation, either version 3 of the
   License, or (at your option) any later version.

   Miriad-python is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with miriad-python.  If not, see <http://www.gnu.org/licenses/>.

.. _datahighlev:
.. sectionauthor:: Peter Williams <peter@newton.cx>

High-Level Access to MIRIAD Data: :mod:`miriad`
===============================================

.. module:: miriad
   :synopsis: Talk about MIRIAD datasets naturally in Python.
.. moduleauthor:: Peter Williams <peter@newton.cx>

On the commandline, you refer to datasets by their filenames. The
:mod:`miriad` module provides two fundamental classes,
:class:`~VisData` and :class:`~ImData`, which analogously let you
refer to datasets in a Python program. Instances of these class are
lightweight and provide features to make it easy to perform common
operations on your data.

To instantiate one of these classes, just call the constructor with
a filename as an argument::

  from miriad import VisData, ImData
  vis = VisData ('./fx64c-3c147-1400')
  im = ImData ('./residual.rm')

It's important to understand that these objects are *references* to
datasets, and as such the underlying file doesn't have to exist when
you create the object. Also, creating one of these objects is a very
cheap operation.

Both :class:`miriad.VisData` and :class:`miriad.ImData` are subclasses of a more
generic class, :class:`miriad.Data`. Instances of this class have methods
and properties that provide common functionality regarding MIRIAD
datasets. One set of functionality is checking basic properties of the
dataset on disk:

* :attr:`Data.exists` to see if it exists on disk.
* :attr:`Data.mtime` to check when it was last modified. This requires
  that the dataset exists; the variant attribute :attr:`~Data.umtime`
  returns unconditionally. (Hence the "u" prefix to its name.)
* :meth:`Data.realPath` to get its canonical filename.

You can also perform some basic operations. (From here on out, we will
drop the ''Data'' prefix in the names we show. Also, note that you can
click on the link associated with all of these function or property
names to access the more detailed reference documentation for that item.)

* :meth:`~Data.moveTo` renames a dataset.
* :meth:`~Data.copyTo` copies it.
* :meth:`~Data.delete` deletes it.
* :meth:`~Data.apply` configures a MIRIAD task object
  (:class:`mirexec.TaskBase`) to run on this dataset
  via the :mod:`mirexec` subsystem. See :ref:`executing` for more
  information. See also the verbose variant
  :meth:`~Data.xapply`.

You can create more :class:`~Data` instances with filenames
similar to existing ones:

* :meth:`~Data.vvis` creates a new :class:`VisData`
  instance referencing a similar filename.
* :meth:`~Data.vim` creates a new :class:`ImData`
  instance referencing a similar filename.

And you can open the dataset with :meth:`~Data.open` to get
access to its contents. See :ref:`datalowlev` for more information.

You may also wish to enable tracing of MIRIAD task execution in
*miriad-python* by calling :func:`basicTrace`. There are a few more
rarely-used members of :class:`~Data` not mentioned here that are
documented in the :ref:`API reference <miriadapiref>` below.

Visibility Datasets
-------------------

The :class:`~VisData` subclass of :class:`~Data` has
additional routines specifically useful for UV data:

* :meth:`~VisData.catTo` runs :command:`uvcat` on a dataset
  to produce a copy of it.
* :meth:`~VisData.averTo` runs :command:`uvaver` on a dataset
  to produce an averaged copy of it.
* :meth:`~VisData.lwcpTo` creates a "lightweight copy" of a
  dataset, duplicating its metadata but not the visibilities,
  which makes certain common operations much faster.
* :meth:`~VisData.readLowlevel` opens the dataset directly
  for lowlevel access to the visibility data.

Besides these routines, the :class:`~VisData` subclass
implements several generic methods specified in :class:`~Data`,
so you should always create a :class:`~VisData` instance when
you know that you're referring to a visibility dataset.

Image Datasets
--------------

The :class:`~ImData` subclass of :class:`~Data` is used
for referencing image data. It currently does not have any routines
specifically applicable to image data, but it implements
several of the :class:`~Data` methods correctly, so you should
always create a :class:`~ImData` instance when you know that
you're referring to an image dataset.

:mod:`miriad` API Reference
---------------------------
.. _miriadapiref:

This section presents a detailed API reference for the :mod:`miriad`
module.

Dataset Classes
^^^^^^^^^^^^^^^

.. autoclass:: Data
   :members:

.. autoclass:: VisData
   :members:

.. autoclass:: ImData
   :members:

Tracing Task Execution
^^^^^^^^^^^^^^^^^^^^^^

The :mod:`miriad` module also provides infrastructure for tracing task
execution and operations on datasets.


.. data:: launchTrace

   Traces the execution of commands.

   Should be a callable or :const:`None`. Will be called by
   :func:`trace`, which is invoked every time a MIRIAD task is
   executed via :mod:`mirexec` or a dataset is renamed, copied, or
   deleted. *launchTrace* should take one argument, which will be a
   list of strings representing the commandline that is being invoked.
   If none, :func:`trace` has no effect.

   The function :func:`basicTrace` sets *launchTrace* to a simple
   default.

.. autofunction:: trace

.. autofunction:: basicTrace