channelarchiver 1.0.0

Python client for the EPICS Channel Archiver.

Copyright (c) 2015 Robbie Clarken

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Description: .. image:: https://travis-ci.org/RobbieClarken/channelarchiver.svg
:target: https://travis-ci.org/RobbieClarken/channelarchiver

A python client for retrieving data from an `EPICS Channel Archiver
<https://ics-web.sns.ornl.gov/kasemir/archiver/>`_.

To get started just import the ``Archiver`` class and specify the
address of your Channel Archiver server:

.. code:: python

from channelarchiver import Archiver
archiver = Archiver('http://cr01arc01/cgi-bin/ArchiveDataServer.cgi')

You then fetch data with the ``archiver.get()`` method:

.. code:: python

>>> data = archiver.get('SR00IE01:INJECTION_EFFICIENCY_MONITOR', '2013-08-11', '2013-08-12')
>>> print(data)
time value status severity
2013-08-11 00:00:02 96.9351518 NO_ALARM NO_ALARM
2013-08-11 00:04:20 94.5171233 NO_ALARM NO_ALARM
2013-08-11 00:08:38 85.0604361 LOW_ALARM MINOR
...
>>> data.values
[96.935, 94.517, ..., 97.253]

The returned ``ChannelData`` object has the following fields:

- ``channel``: The channel name.
- ``times``: A list of datetimes.
- ``values``: A list of the channel's values corresponding to
``times``.
- ``severities`` and ``statuses``: Diagnostic information about the
channel state for each time.
- ``units``: The units of ``values``.
- ``states``: String values for enum type channels.
- ``data_type``: Whether the channel values are string, enum, int or
double (see ``codes.data_type``).
- ``elements``: The number of elements in an array type channel.
- ``display_limits``, ``warn_limits``, ``alarm_limits``: Low and high
limits
- ``display_precision``: The recommended number of decimal places to to
display values with in user interfaces.
- ``archive_key``: The archive the data was retrieved from.
- ``interpolation``: The interpolation method that was used (see
``codes.interpolation``).

Get multiple channels
~~~~~~~~~~~~~~~~~~~~~

If you pass a list of channel names to ``.get()`` you will get a list of
data objects back:

.. code:: python

>>> channels = ['SR00TUM01:X_TUNE', 'SR00TUM01:Y_TUNE']
>>> x, y = archiver.get(channels, '2013-08-24 09:00', '2013-08-24 19:00')
>>> print(x.values)
[0.291, 0.290, ..., 0.289]
>>> print(y.values)
[0.216, 0.217, ..., 0.213]

Times and timezones
~~~~~~~~~~~~~~~~~~~

The start and end times over which to fetch data can be datetimes
or strings in ISO 8601 format (eg ``2013-08-10T21:30:00``).

If no timezone is specified, your local timezone will be used. If a timezone is given,
the returned channel data times will also be in this timezone.

.. code:: python

>>> start = datetime.datetime(2012, 6, 1, tzinfo=pytz.UTC)
>>> end = datetime.datetime(2012, 6, 30, tzinfo=pytz.UTC)
>>> data_in_utc = archiver.get('BR00EXS01:TUNNEL_TEMPERATURE_MONITOR', start, end)

Interpolating
~~~~~~~~~~~~~

You can control how much data is returned from the archiver with the
``limit`` parameter. This is roughly equal to how many data points will
be returned but the actual value will differ depending on how much data is
available and the interpolation method.

The interpolation method is determined by the ``interpolation`` parameter. The
allowed values are the ``'raw'``, ``'spreadsheet'``, ``'averaged'``, ``'plot-binning'``
and ``'linear'``. The default value is ``'linear'``.

.. code:: python

>>> from channelarchiver import codes
>>> channel = 'SR00MOS01:FREQUENCY_MONITOR'
>>> data = archiver.get(channel, '2012', '2013', limit=10000, interpolation='raw')

Speeding up data retrieval
~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, for each ``.get`` call ``Archive`` will scan the archives to
determine which one contains data for the specified channels. This will
cause a slight delay in retrieving the data. This can be avoided by
calling the ``.scan_archives()`` method once and then passing
``scan_archives=False`` to ``.get()``:

.. code:: python

>>> archiver.scan_archives()
>>> d1 = archiver.get('SR02GRM01:DOSE_RATE_MONITOR', '2013-07', '2013-08', scan_archives=False)
>>> d2 = archiver.get('SR11BCM01:LIFETIME_MONITOR', '2013-07', '2013-08', scan_archives=False)

Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Scientific/Engineering
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: License :: OSI Approved :: MIT License