# Fetching

The target audience of this document is a member of the FOT who wishes to access archived engineering data for 
the purpose of data analysis.

```{py:currentmodule} jeta.archive.fetch
```

## Acronyms and Terms
* MSID - an object model of an mnemonic (or measurand).
* API - Application Programming Interface
* CLI - Command-Line Interface

## Fetch API Classes
### MSID Class API
```{eval-rst}
.. autoclass:: MSID
   :show-inheritance:
   :members:
```

### MSIDSet Class API
```{eval-rst}
.. autoclass:: MSIDset
   :show-inheritance:
   :members:
```

### Msid Class API
```{eval-rst}
.. autoclass:: Msid
   :show-inheritance:
   :members:
```

### Msidset
```{eval-rst}
.. autoclass:: Msidset
   :show-inheritance:
   :members:
```

## CLI Example

This next section will demostrate the usage of the fetch module. These examples are presented
as if being executed on a command-line such as a unix terminal. However, the example should work 
the same in a Jupyter notebook environment.

### Ex. 1: Fetch The Archive Coverage For An MSID

It maybe useful to learn the archive coverage interval for a specific msid. This can be accomplished by using the
`fetch.get_time_range` function.

```python
   # Returns date range as unix timestamp by default
   fetch.get_time_range(<msid>)
   (2458664.5208374076, 2458666.5249855556)

   # Returns date range in ISO format
   fetch.get_time_range(<msid>, "iso")
   ('2019-06-30 00:30:00.352', '2019-07-02 00:35:58.752')
```
    

### Ex. 2: Fetch All Archived Data For A Single Mnemonic

Import the fetch submodule from the archive module. You'll get a message indicating the location where
the system will attempt to fetch telemetry.

```python
   from jeta.archive import fetch
   fetch: using ENG_ARCHIVE=</path/to/archive> for archive path
   msid = fetch.MSID(<msid>) # where <msid> is the MSID 
```

### Ex. 3: Fetch A Range Of Archived Data for Single Mnemonic

Import the fetch submodule from the archive module. You'll get a message indicating the location where
the system will attempt to fetch telemetry. As part of the fetch you will specific the `tstart` and `tstop`
in the Day Of Year (DOY) -- `yday` in the `astropy.time.Time` module -- format. Percision for the user supplied times
is to the millisecond level (i.e. YYYY:DOY:HH:MM:SS.sss).

```python
   from jeta.archive import fetch
   fetch: using ENG_ARCHIVE=</path/to/archive> for archive path
   msid = fetch.Msid('<msid>', '2019:001', '2019:002') # where <msid> is the MSID 
```

### Ex. 4: Plotting An MSID

To fetch data for a single mnenmonic create a instance of the *Msid (Mnemonic System Identifier)* class.

```python
   msid = fetch.Msid('<msid>', '2019:001', '2019:002')
   msid.plot() # will create an inline/widget plot in a jupyter notebook or new plot window in a desktop environment
```

This returns the python data structure (Msid Object) containing the data requested in the specified range. The
objects ``plot()`` method can then be called to display a plot of the data. The plot is generated by matplotlib.


### Ex. 5: Fetching Multiple MSIDs At Once Using MSIDSet

For some operations it may be useful to retrieve a set of Msid. To do this use the **MsidSet Object** in place of the Msid.
```python
   fetch.Msidset([MNEMONIC_1, 'MNEMONIC_2'], '2019:001', '2019:365')
   Msidset(
      [
         (
            'MNEMONIC_1', 
            <MSID start=2019:001:12:00:00.000 stop=2019:365:12:00:00.000 len=701 dtype=float64>
         ),
         (
            'MNEMONIC_2',
            <MSID start=2019:001:12:00:00.000 stop=2019:365:12:00:00.000 len=175 dtype=bytes48>
         )
      ]
   )
```