<a id="api-data-recorder"></a>

# Data Recorder Module

### *class* joulescope.data_recorder.DataReader

Read Joulescope data from a file.

#### close()

Close the recording file.

#### data_get(start, stop, increment=None, units=None, out=None)

Get the samples with statistics.

* **Parameters:**
  * **start** – The starting sample id (inclusive).
  * **stop** – The ending sample id (exclusive).
  * **increment** – The number of raw samples.
  * **units** – The units for start and stop.
    ‘seconds’ or None is in floating point seconds relative to the view.
    ‘samples’ is in stream buffer sample indices.
  * **out** – The optional output np.ndarray((N, STATS_FIELD_COUNT), dtype=DTYPE) to populate with
    the result.  None (default) will construct and return a new array.
* **Returns:**
  The np.ndarray((N, STATS_FIELD_COUNT), dtype=DTYPE) data.

#### *property* duration

The data file duration, in seconds.

#### get_reduction(start=None, stop=None, units=None, out=None)

Get the fixed reduction with statistics.

* **Parameters:**
  * **start** – The starting sample identifier (inclusive).
  * **stop** – The ending sample identifier (exclusive).
  * **units** – The units for start and stop.
    ‘seconds’ or None is in floating point seconds relative to the view.
    ‘samples’ is in stream buffer sample indices.
* **Returns:**
  The The np.ndarray((N, STATS_FIELD_COUNT), dtype=DTYPE)
  reduction data which normally is memory mapped to the underlying
  data, but will be copied on rollover.

#### *property* input_sampling_frequency

The original input sampling frequency.

#### normalize_time_arguments(start, stop, units=None)

Normalize time arguments to range.

* **Parameters:**
  * **start** – The start time or samples.
    None gets the first sample, equivalent to self.sample_id_range[0].
  * **stop** – The stop time or samples.
    None gets the last sample, equivalent to self.sample_id_range[1].
  * **units** – The time units which is one of [‘seconds’, ‘samples’]
    None (default) id equivalent to ‘samples’.
* **Returns:**
  (start_sample, stop_sample).

When units==’samples’, negative values are interpreted in standard
Python notation relative to the last sample.  None

#### open(filehandle)

Open a recording file.

* **Parameters:**
  **filehandle** – The seekable filehandle or filename string.

#### *property* output_sampling_frequency

The output sampling frequency.

#### *property* reduction_frequency

The reduction frequency or 1 if no reduction.

#### *property* sample_id_range

The sample ID range.

* **Returns:**
  [start, stop] sample identifiers.

#### samples_get(start=None, stop=None, units=None, fields=None)

Get exact samples over a range.

* **Parameters:**
  * **start** – The starting time.
  * **stop** – The ending time.
  * **units** – The units for start and stop.
    ‘seconds’ or None is in floating point seconds relative to the view.
    ‘samples’ is in stream buffer sample indicies.
  * **fields** – The fields to get.

#### *property* sampling_frequency

The output sampling frequency.

#### statistics_get(start=None, stop=None, units=None)

Get the statistics for the collected sample data over a time range.

* **Parameters:**
  * **start** – The starting time relative to the first sample.
  * **stop** – The ending time.
  * **units** – The units for start and stop.
    ‘seconds’ is in floating point seconds relative to the view.
    ‘samples’ or None is in stream buffer sample indices.
* **Returns:**
  The statistics data structure.
  See the [statistics documentation](https://docs.joulescope.com/en/software/pyjoulescope/api/statistics.html)
  for details.

#### *property* voltage_range

The data file voltage range.

### *class* joulescope.data_recorder.DataRecorder(filehandle, calibration=None, user_data=None)

Record Joulescope data to a file.

* **Parameters:**
  * **filehandle** – The file-like object or file name.
  * **calibration** – The calibration bytes in datafile format.
    None (default) uses the unit gain calibration.
  * **user_data** – Arbitrary JSON-serializable user data that is
    added to the file.

#### close(footer_user_data=None)

Finalize and close the recording.

#### insert(data)

Insert sample data.

* **Parameters:**
  **data** – A dict in the `StreamBuffer.samples_get()` format.

#### stream_notify(stream_buffer)

Process data from a stream buffer.

* **Parameters:**
  **stream_buffer** – The stream_buffer instance which has:
  \* “output_sampling_frequency” member -> float
  \* “has_raw” member -> in [True, False]
  \* “sample_id_range” member => (start, stop)
  \* “voltage_range” member -> in [0, 1]
  \* samples_get(start_sample_id, stop_sample_id, dtype)
  \* data_get(start_sample_id, stop_sample_id, increment, out)
  \* \_\_len_\_ : maximum number of samples that stream_buffer holds