.. _quick_start:

Quickstart Guide
****************
The ``PythonLevel1Services`` package reads Osiris Level 1 data from HDF files stored on our servers, and stores the data as
xarray Dataset data structures. We currently have data on the Odin satellite's attitude, data from the OSIRIS optical
spectrograph (OS), housekeeping data on the instrument status, data from the OSIRIS three channel infrared detector (IRI)
and ECMWF data on atmospheric conditions. These data products are stored in HDF file format for several thousand orbits.

The ``PythonLevel1Services`` package is intended to be a pythonic interface to this data, while providing powerful
functionality to assist in the process of data analysis. There are two user modules within the package. These are:

* ``osirisl1services.readlevel1``
* ``osirisl1services.services``

The package requires the environment variable `ODINORBITDIR` to be set to the folder that points to the Level 1 orbital data,
e.g. `\\\\UTLS\\OsirisDataProducts\\Level1\\orbit`

To use the RSAS correction it is also necessary to specify the `ODINFLIGHTDIR` environment variable, e.g.,
`\\UTLS\OsirisDataProducts\OsirisConfigurationDatabase\flightduration`

Reading the Data
================
The python module within ``PythonLevel1Services`` that provides a user interface to the level 1 data products is
``osirisl1services.readlevel1``. The module contains several methods, each designed to read data from the level 1
HDF/Onyx files and store it in a usable data structure. We implement xarray's Dataset object as this data structure.

Each of these methods takes a :class:`readlevel1.Orbit` object as its first positional argument. The :class:`readlevel1.Orbit`
class handles the retrieval of the desired HDF file from the server. The output of every method is an xarray Dataset.
For example, when opening an attitude file, ::

    from osirisl1services.readlevel1 import open_level1_attitude

    att = open_level1_attitude(orbit=6432, load_pointing=True)

Most file opening methods take optional positional arguments which, if set True, load additional data. In the case
shown above, we also load pointing data which is used to calculate the instrument's line of sight and tangent position
information.

Using the Services
==================
Additional data analysis functionality is provided by the ``osirisl1services.services`` module within the python package.
This module contains methods designed to give the user more information and control over the level 1 data. The additional
functionality provided by this module includes the calculation of the satellite position, look vectors, latitude,
longitude, altitude, and solar zenith angle of tangent points. There is also a method that returns the set of scans
in an orbit which satisfy a maximum solar zenith angle. For example, ::

    from osirisl1services.readlevel1 import open_level1_spectrograph
    from osirisl1services.services import Level1Services

    spect = open_level1_spectrograph(scanno=6432012)

    print(spect.l1.latitude)
    print(spect.l1.altitude)
    print(spect.l1.sza)

For more examples see :ref:`data_examples`.