.. ICARTT documentation master file, created by
   sphinx-quickstart on Thu Feb 10 09:33:37 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

icartt
============================

icartt is an ICARTT file format reader and writer

The ICARTT data format is described here: https://www-air.larc.nasa.gov/missions/etc/IcarttDataFormat.htm

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Installation
------------

.. include:: ../../INSTALL.rst

Example
------------

Using an existing dataset
^^^^^^^^^^^^^^^^^^^^^^^^^^

::

   import icartt

   # load a new dataset from an existing file
   ict = icartt.Dataset('path/to/example.ict')

   # list variable names
   ict.varnames
   # e.g. ['Fractional_Day', 'UTC', 'JDAY', 'INDEX', 'FLIGHT', 'LOCAL_SUN_TIME', ...

   # get data for variable 'UTC':
   ict['UTC']

   # some metadata
   ict.organization
   ict.dataSource
   ict.mission

   # add data, depending of format and type of variable:
      - file type 1001, add value of independent variable:
      ivar.append(234.4)

      - file type 1001, add value of dependent variable:
      ivar.append(234.4, 18.2)

      
      - file type 2110, add value of independent (unbounded) variable:
      ivar.append(234.4)

      - file type 2110, add value of independent (bounded) variable:
      ivar.append(234.4, 9148.2)

      - file type 2110, add value of dependent variable:
      ivar.append(234.4, 9148.2, 34.2)

   # write to (other) file:
   with open('path/to/output.ict', 'wb') as f:
      ict.write(f)

Creating a new dataset
^^^^^^^^^^^^^^^^^^^^^^^

::

import icartt
import datetime

ict                                    = icartt.Dataset(format=icartt.Formats.FFI1001)

ict.PIName                             = 'Knote, Christoph'
ict.PIAffiliation                      = 'Faculty of Medicine, University Augsburg, Germany'
ict.dataSourceDescription              = 'Example data'
ict.missionName                        = 'MBEES'
ict.dateOfCollection                   = datetime.datetime.today()
ict.dateOfRevision                     = datetime.datetime.today()

ict.dataIntervalCode                   = [ 0 ]

ict.independentVariable                = icartt.Variable(  'Time_Start',
                                                            'seconds_from_0_hours_on_valid_date',
                                                            'Time_Start',
                                                            'Time_Start',
                                                            vartype=icartt.VariableType.IndependentVariable,
                                                            scale=1.0, miss=-9999999)

#ict.independentBoundedVariable        = None
#ict.auxiliaryVariables                = ...

ict.dependentVariables['Time_Stop']    = icartt.Variable(   'Time_Stop',
                                                            'seconds_from_0_hours_on_valid_date',
                                                            'Time_Stop',
                                                            'Time_Stop',
                                                            scale=1.0, miss=-9999999)

ict.dependentVariables['Payload']      = icartt.Variable(   'Payload',
                                                            'some_units',
                                                            'Payload',
                                                            'Payload',
                                                            scale=1.0, miss=-9999999)

ict.specialComments.append("Some comments on this dataset:")
ict.specialComments.append("They are just examples!")
ict.specialComments.append("Adapt as needed.")


ict.endDefineMode()


# Three ways to add data:

# 1) simple (single data line)

ict.data.add( Time_Start = 12.3, Time_Stop = 12.5, Payload = 23789423.2e5 )

# Let's check:

ict.write()

# Seems to have worked!

# 2) as dictionary (single data line)

ict.data.add( **{ 'Time_Start': 12.6, 'Time_Stop': 13.1, 'Payload': 324235644.1e5 } )

# (note, we are merely exploding the dictionary to resemble method 1)

# 3) as NumPy array (bulk)

import numpy as np

data = np.array( [ (13.4, 14.0, 2348925e5), (14.1, 14.9, 23425634e5) ] )
ict.data.addBulk( data )

# Note: you are responsible to ensure that the order of elements in a data line
# corresponds to variable listing below:
print( [ x for x in ict.variables ] )

# Note: for single lines, you still need to make it an array!
data = np.array( [ (15.4, 15.0, 52452495290e5) ] )

API
----

.. module:: icartt

Variable
^^^^^^^^^^

.. autoclass:: Variable
   :members:

Dataset
^^^^^^^^^^

.. autoclass:: Dataset
   :members:

Formats
^^^^^^^^^^

.. autoenum:: Formats

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`