Metadata-Version: 1.1
Name: ai.cdas
Version: 1.0.1
Summary: Python interface to CDAS data via REST API
Home-page: https://bitbucket.org/isavnin/ai.cdas
Author: Alexey Isavnin
Author-email: alexey.isavnin@gmail.com
License: MIT
Description: AI.CDAS: python interface to `CDAS <http://cdaweb.gsfc.nasa.gov/>`__ data
        =========================================================================
        
        This library provides access to CDAS database from python in a simple
        and fluid way through `CDAS REST
        api <http://cdaweb.gsfc.nasa.gov/WebServices/REST/>`__. It fetches the
        data either in `CDF (Common Data Format) <http://cdf.gsfc.nasa.gov/>`__
        or ASCII format and returns it in the form of dictionaries and numpy
        arrays.
        
        Dependencies
        ------------
        
        -  Python 2.7
        -  `numpy <http://www.numpy.org/>`__
        -  `requests <http://docs.python-requests.org/en/latest/>`__
        -  `wget <https://pypi.python.org/pypi/wget>`__
        
        Extra dependencies (at least one of the following)
        --------------------------------------------------
        
        -  `astropy <http://www.astropy.org/>`__
        -  `CDF <http://cdf.gsfc.nasa.gov/>`__ +
           `spacepy <http://spacepy.lanl.gov/doc/index.html>`__
        
        Examples
        --------
        
        **Example 1**: Retrieving observatory groups and associated instruments
        which measure plasma and solar wind:
        
        ::
        
            #!python
        
            from ai import cdas
            import json # for pretty output
        
            obsGroupsAndInstruments = cdas.get_observatory_groups_and_instruments('istp_public', instrumentType='Plasma and Solar Wind')
            print json.dumps(obsGroupsAndInstruments, indent=4)
        
        **Example 2**: Getting STEREO-A datasets using regular expressions for
        dataset id and label:
        
        ::
        
            #!python
        
            from ai import cdas
            import json # for pretty output
        
            datasets = cdas.get_datasets('istp_public', idPattern='STA.*', labelPattern='.*STEREO.*')
            print json.dumps(datasets, indent=4)
        
        **Example 3**: Fetching a list of variables in one of STEREO datasets:
        
        ::
        
            #!python
        
            from ai import cdas
            import json # for pretty output
        
            variables = cdas.get_variables('istp_public', 'STA_L1_MAGB_RTN')
            print json.dumps(variables, indent=4)
        
        **Example 4**: This snippet of code gets magnetic field data from
        STEREO-A spacecraft for 01.01.2010 and plots it (requires pylab, which
        is part of scipy):
        
        ::
        
            #!python
        
            from ai import cdas
            import pylab
        
            data = cdas.get_data('sp_phys', 'STA_L1_MAG_RTN', '20100101T000000Z', '20100101T235959Z', ['BFIELD'])
            pylab.plot(data['Epoch'][...], data['BFIELD'][...,3])
            pylab.show()
        
        Documentation
        -------------
        
        The functions implemented in AI.CDAS library follow strictly the
        description of CDAS REST web-service documented
        `here <http://cdaweb.gsfc.nasa.gov/WebServices/REST/>`__.
        
        First, AI.CDAS library has to be imported:
        
        ::
        
            #!python
        
            from ai import cdas
        
        Dataviews
        ~~~~~~~~~
        
        Provides descriptions of dataviews that are available from CDAS.
        
        ::
        
            #!python
        
            dataviews = cdas.get_dataviews()
        
        Observatory groups
        ~~~~~~~~~~~~~~~~~~
        
        Provides descriptions of observatory groups that are available from
        CDAS.
        
        ::
        
            #!python
        
            observatoryGroups = cdas.get_observatory_groups(dataview, instrumentType=None)
        
        **instrumentType** is an instrument type value
        (/InstrumentTypes/InstrumentTypeDescription/Name) from those returned by
        a *cdas.get\_instrument\_types* request. Omitting this parameter
        indicates that no **observatoryGroups** are eliminated based upon their
        **instrumentType** value.
        
        For example, the following snippet of code gets the observatory groups
        with instrument type 'Plasma and Solar Wind' from the dataview 'Public
        data from current space physics missions' (*istp\_public*):
        
        ::
        
            #!python
        
            observatoryGroups = cdas.get_observatory_groups('istp_public', instrumentType='Plasma and Solar Wind')
        
        Instrument types
        ~~~~~~~~~~~~~~~~
        
        Provides descriptions of the instrument types that are available from
        CDAS.
        
        ::
        
            #!python
        
            instrumentTypes = cdas.get_instrument_types(dataview, observatory=None, observatoryGroup=None)
        
        **observatory** is an observatory group value
        (/Observatories/ObservatoryDescription/Name) from those returned by a
        *cdas.get\_observatories* request. Omitting this parameter indicates
        that no **instrumentTypes** are eliminated based upon their
        **observatory** value.
        
        **observatoryGroup** is an observatory group value
        (/ObservatoryGroups/ObservatoryGroupDescription/Name) from those
        returned by a *cdas.get\_observatory\_groups* request. Omitting this
        parameter indicates that no **instrumentTypes** are eliminated based
        upon their **observatoryGroup** value.
        
        Instruments
        ~~~~~~~~~~~
        
        Provides descriptions of the instrument that are available from CDAS.
        
        ::
        
            #!python
        
            instruments = cdas.get_instruments(dataview, observatory=None)
        
        **observatory** is an observatory value
        (/Observatories/ObservatoryDescription/Name) from those returned by a
        *cdas.get\_observatories* request. Omitting this parameter indicates
        that no **instruments** are eliminated based upon their **observatory**
        value.
        
        Observatories
        ~~~~~~~~~~~~~
        
        Provides descriptions of the observatories that are available from CDAS.
        
        ::
        
            #!python
        
            observatories = cdas.get_observatories(dataview, instrument=None, instrumentType=None)
        
        **instrument** is an instrument value
        (/Instruments/InstrumentDescription/Name) from those returned by a
        *cdas.get\_instruments* request. Omitting this parameter indicates that
        no **observatories** are eliminated based upon their **instrument**
        value.
        
        **instrumentType** is an instrument type value
        (/InstrumentTypes/InstrumentTypeDescription/Name) from those returned by
        a *cdas.get\_instrument\_types* request. Omitting this parameter
        indicates that no **observatories** are eliminated based upon their
        **instrumentType** value.
        
        Observatory groups and instruments
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Provides descriptions of the observatory groups (and associated
        instruments) that are available from CDAS. This is a
        convenience/performance alternative to making multiple calls to
        *cdas.get\_observatory\_groups*, *cdas.get\_observatories*, and
        *cdas.get\_instruments*.
        
        ::
        
            #!python
        
            observatoryGroupsAndInstruments = cdas.get_observatory_groups_and_instruments(dataview, instrumentType=None)
        
        **instrumentType** is an instrument type value
        (/InstrumentTypes/InstrumentTypeDescription/Name) from those returned by
        a *cdas.get\_instrument\_types* request. Omitting this parameter
        indicates that no **observatoryGroupsAndInstruments** are eliminated
        based upon their **instrumentType** value.
        
        Datasets
        ~~~~~~~~
        
        Provides descriptions of the datasets that are available from CDAS.
        
        ::
        
            #!python
        
            datasets = cdas.get_datasets(dataview, observatoryGroup=None, instrumentType=None, observatory=None, instrument=None, startDate=None, stopDate=None, idPattern=None, labelPattern=None, notesPattern=None)
        
        **observatoryGroup** is an observatory group value
        (/ObservatoryGroups/ObservatoryGroupDescription/Name) from those
        returned by a *cdas.get\_observatory\_groups* request. Omitting this
        parameter indicates that no **datasets** are eliminated based upon their
        **observatoryGroup** value.
        
        **instrumentType** is an instrument type value
        (/InstrumentTypes/InstrumentTypeDescription/Name) from those returned by
        a *cdas.get\_instrument\_types* request. Omitting this parameter
        indicates that no **datasets** are eliminated based upon their
        **instrumentType** value.
        
        **observatory** is an observatory group value
        (/Observatories/ObservatoryDescription/Name) from those returned by a
        *cdas.get\_observatories* request. Omitting this parameter indicates
        that no **datasets** are eliminated based upon their **observatory**
        value.
        
        **instrument** is an instrument value
        (/Instruments/InstrumentDescription/Name) from those returned by a
        *cdas.get\_instruments* request. Omitting this parameter indicates that
        no **datasets** are eliminated based upon their **instrument** value.
        
        **startDate** is a basic format (minimal number of separators) ISO 8601
        date specifying the start of a time interval (e.g., 20000101T000000Z).
        If this parameter is ommited, the time interval will begin infinitely in
        the past.
        
        **stopDate** is a basic format (minimal number of separators) ISO 8601
        date specifying the end of a time interval (e.g., 20100101T000000Z). If
        this parameter is omitted, the time interval will end infinitely in the
        future.
        
        **idPattern** is a java.util.regex compatible regular expression that
        must match the dataset's identifier value. Omitting this parameter is
        equivalent to ".\*".
        
        **labelPattern** is a java.util.regex compatible regular expression that
        must match the dataset's label text. Omitting this parameter is
        equivalent to ".\*". Embedded matching flag expressions (e.g., (?i) for
        case insensitive match mode) are supported and likely to be useful in
        this case.
        
        **notesPattern** is a java.util.regex compatible regular expression that
        must match the dataset's notes text. Omitting this parameter is
        equivalent to ".\*". Embedded matching flag expressions (e.g., (?s) for
        dotall match mode) are supported and likely to be useful in this case.
        
        Inventory
        ~~~~~~~~~
        
        Provides descriptions of the data inventory that is available within a
        dataset.
        
        ::
        
            #!python
        
            inventory = cdas.get_inventory(dataview, dataset)
        
        Variables
        ~~~~~~~~~
        
        Provides descriptions of the variables that is available from a dataset.
        
        ::
        
            #!python
        
            variables = cdas.get_variables(dataview, dataset)
        
        Data
        ~~~~
        
        Provides data from a dataset.
        
        ::
        
            #!python
        
            data = cdas.get_data(dataview, dataset, startTime, stopTime, variables, cdf=True)
        
        **startTime** is the beginning time of an interval in basic (minimal
        number of separators) ISO 8601 format. Extended ISO 8601 format is not
        allowed.
        
        **stopTime** is the ending time of an interval in basic (minimal number
        of separators) ISO 8601 format. Extended ISO 8601 format is not allowed.
        
        **variables** is the comma separated list of variable names identifying
        the data to get. The names should be from those returned by the
        *cdas.get\_variables* operation. At least one variable name must be
        specified.
        
        **cdf** is the flag for choosing either CDF of ASCII format for data
        download. If you have CDF library and SpacePy installed it is highly
        recommended to use cdf=True always. CDF files are smaller and are faster
        to download. If you do not have CDF+SpacePy but you have AstroPy library
        installed you can download data in ASCII format using cdf=False.
        
Keywords: coordinated data analysis web cdaweb cdas spdf research space physics data facility nasa science
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2.7
