<a id="api-stream-buffer"></a>

# Stream Buffer API

### *class* joulescope.v1.stream_buffer.StreamBuffer(duration, frequency, device, output_frequency=None)

Efficient real-time Joulescope data buffering.

* **Parameters:**
  **duration** – The total length of the buffering in seconds.

#### data_get(start, stop, increment=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.
  * **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.

This method provides fast access to statistics data, primarily for
graphical display.  Applications should prefer using
[`samples_get()`](#joulescope.v1.stream_buffer.StreamBuffer.samples_get) which provides metadata along with the samples.

#### *property* extra_signals

The list of enabled extended signal names.

The extended signals are in EXTENDED_SIGNALS.  Assigning this
property reallocates the buffers, which discards all buffered data.

#### *property* sample_id_range

Get the range of sample ids currently available in the buffer.

* **Returns:**
  Tuple of sample_id start, sample_id end.
  Start and stop follow normal python indexing:
  start is inclusive, end is exclusive

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

Get exact sample data without any skips or reductions.

* **Parameters:**
  * **start** – The starting sample id (inclusive).
  * **stop** – The ending sample id (exclusive).
  * **fields** – 

    The single field or list of field names to return.
    None (default) is equivalent to
    [‘current’, ‘voltage’, ‘power’, ‘current_range’, ‘current_lsb’, ‘voltage_lsb’].
    The available fields are:
    * current: The calibrated float32 current data array in amperes.
    * voltage: The calibrated float32 voltage data array in volts.
    * power: The calibrated float32 power data array in watts.
    * current_range: The current range. 0 = 10A, 6 = 18 uA, 7=off.
    * current_lsb: The general purpose input 0 (alias for gpi0).
    * voltage_lsb: The general purpose input 1 (alias for gpi1).
    * gpi0, gpi1, gpi2, gpi3: The general purpose inputs.
    * trigger_in: The trigger input.

    Short aliases are also supported: i, v, p, r, 0, 1, 2, 3, T.
    The gpi2, gpi3, and trigger_in signals require JS220 or JS320
    hardware with the signal selected (see the device ‘signals’
    parameter).
* **Returns:**
  The dict containing top-level ‘time’ and ‘signals’ keys.
  The ‘time’ value is a dict contain the timing metadata for
  these samples.  The ‘signals’ value is a dict with one
  key for each field in fields.  Each field value is also
  a dict with entries ‘value’ and ‘units’.
  However, if single field string is provided to fields, then just
  return that field’s value.

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

Get exact statistics over the specified range.

* **Parameters:**
  * **start** – The starting sample_id (inclusive).
  * **stop** – The ending sample_id (exclusive).
  * **out** – The optional output np.ndarray(STATS_FIELD_COUNT, dtype=DTYPE).
    None (default) creates and outputs a new record.
* **Returns:**
  The tuple of (np.ndarray(STATS_FIELD_COUNT, dtype=DTYPE), [start, stop]).
  The values of start and stop will be constrained to the
  available range.

#### *property* utc_anchor

The most recent mapping from sample id to UTC time.

* **Returns:**
  The tuple (sample_id, utc) where sample_id is in this
  buffer’s output sample id space and utc is the
  `joulescope.time` timestamp for that sample, or None
  before the first sample.