(core module)=
# **core module**  
These functions allows to open/read three type of data: native _febus_ file, _reducted_ file or ZMQ _socket_ data stream.
Data can be read with different parameters that allow to define time/space range, time/space decimation, etc

The module relies upon two classes: 
- **A1File** to deal with files
- **A1Section** to deal with data once a file has been read

## __Basic functions/methods__

```{eval-rst}
 .. autofunction:: core.open
```

```{eval-rst}
 .. automethod:: core.A1File.read
```


```{eval-rst}
 .. automethod:: core.A1File.close
```

## __More functions and classes__
### A1File class
This class is used to initiate I/O operations on files and it allows to inspect all metadata without reading all content
```{eval-rst}
 .. autoclass:: core.A1File
```

### A1Section class
This class is the container to manipulate metadata and data with a number of utility functions/methods
```{eval-rst}
 .. autoclass:: core.A1Section
```

### Plotting A1Section

```{eval-rst}
 .. automethod:: core.A1Section.plot
 .. automethod:: core.A1Section.rplot
```

### A1Section to obspy_stream or xarray
```{eval-rst}
 .. automethod:: core.A1Section.obspy_stream
 .. automethod:: core.A1Section.xarray
```

### and more A1Section methods
```{eval-rst} 
 .. automethod:: core.A1Section.save
 .. automethod:: core.A1Section.synchronize
 .. automethod:: core.A1Section.is_transposed
 .. automethod:: core.A1Section.concat 
 .. automethod:: core.A1Section.index
 .. automethod:: core.A1Section.set_item 
 .. automethod:: core.A1Section.min_header 
 
```

### Internals
```{eval-rst}
 .. autofunction:: core.parse_trange
 .. autofunction:: core.parse_drange
 .. autofunction:: core.tcp_address 
```

## About Febus-Optics DAS-A1 file format
This format uses HDF5 container and defines several groups; datasets; group attributes; dataset attributes.
This paragraph documents the Version 2.3.5 of the format.

### H5 organization
Abbreviations: G=group only, GA=Group with attributes, D=Dataset only, DA=Dataset with attributes

                        localhost.localdomain(G)                   
                                 |
                                 |
                                 ---         .....             -----         ....
                                 |                               |
                                 |                               |
                              Source1(GA)                     SourceK   
                                 |
                                 |
                       --------------------     ....       -----
                       |                  |                  |
                       |                  |                  |
                     time(D)           Zone1(GA)          ZoneK
                                          |
                                          |
                                  -----------------------------    .....
                                  |                |                  
                                  |                |
                               Channel1(D)      Channel2(D)
                                 


1. **Metadata** are stored as group attributes. There are **Source attributes** and **Zone attributes** which respectively contains the following informations (some data are duplicated, e.g. Version):

- **Source Attributes**:

'AmpliPower', 'BlockOverlap', 'BlockRate', 'DataDomain', 'FiberLength', 'Hostname', 'Oversampling', 'PipelineTracker', 'PulseRateFreq', 'PulseWidth', 'SamplingRate', 'SamplingRes', 'Version', 'WholeExtent'

   ```
   # Example for reading Source attribute using h5py:
   >>> import h5py
   >>> f = h5py.File('my_file.h5')
   >>> blockRate = f['localhost.localdomain/Source1'].attrs['BlockRate']
   ```
           
- **Zone attributes**:

'AmpliPower', 'BlockOverlap', 'BlockRate', 'Components', 'DataDomain', 'DerivationTime', 'Extent', 'FiberLength', 'GaugeLength', 'Hostname', 'Origin', 'Oversampling', 'PipelineTracker', 'PulseRateFreq', 'PulseWidth', 'SamplingRate', 'SamplingRes', 'Spacing', 'Version'

2. **Data** are stored in datasets ***localhost.localdomain/Source?/Zone?/Channel?***. There are as many datasets as channels acquired simultaneously. Each dataset contains an array of dimension [**NBLOCK x NTIME x NSPACE**].
Each block contains NTIME time samples and NSPACE channel samples. Blocks are written at the <_BlockRate_> frequency, and they overlap with a <_BlockOverlap_> percentage. 


3. **Time information** is stored in dataset ***localhost.localdomain/Source?/time***. This vector contains the absolute time for each of the NBLOCK block of data.
   ```
   # Example for reading time vector using h5py:
   >>> import h5py
   >>> f = h5py.File('my_file.h5')
   >>> block_times = f['localhost.localdomain/Source1/time'][:]
   ```

4. **Time block storage scheme**: the following diagram displays how data is written by block.
![time block storage scheme](time_block.png "time block storage scheme")