ndi.fun.ensemble.create

  ndi.fun.ensemble.create - build an ensemble element's epoch and store it

  [ENSEMBLEELEMENT, EXISTING] = ndi.fun.ensemble.CREATE(S, ELEMENT, EPOCHID, ...)

  Builds (or extends) the ndi.element.ensemble for ELEMENT (usually a probe) by
  adding the epoch EPOCHID. The ensemble activity is looked up by this function
  (with ndi.fun.ensemble.load): it reads the spike times of every neuron
  recorded on ELEMENT during EPOCHID, and stores them in the ensemble element as
  a marked point process (a standard element_epoch/vhsb binary) plus a per-epoch
  'ensemble' map document recording the neuron ids and names for that epoch's
  columns.

  The ensemble element is found-or-created for ELEMENT (one ensemble element per
  probe, named [ELEMENT.name '_ensemble']); constructing it adds its element
  document to the database. This call then adds the EPOCHID data.

  Before adding, CREATE checks whether the ensemble element already has an
  ensemble for EPOCHID and, if so, raises an error, unless CheckExisting is
  false.

  =========================================================================
  INPUTS
  =========================================================================
    S        - an ndi.session or ndi.dataset object.
    ELEMENT  - the element (usually a probe) whose neurons form the ensemble and
               that provides the time reference. An ndi.element/ndi.probe object
               or an element document id string.
    EPOCHID  - the epoch id (of ELEMENT) to build the ensemble for.

  =========================================================================
  OPTIONS (name/value pairs)
  =========================================================================
    neurons ({})                 - restrict to these neuron elements; default is
                                   every 'spikes' element built on ELEMENT that
                                   is recorded in EPOCHID.
    clocktype ('')               - clock to express spike times in; default is
                                   ELEMENT's clock for EPOCHID.
    ensemble_name ('')           - a human-readable label stored in the map doc.
    value_type ('spiketimes')    - short code for what the stored values mean.
    value_description ('')       - free text describing the values.
    CheckExisting (true)         - if true, error when the ensemble element
                                   already has an ensemble for EPOCHID.
    SkipIfEmpty (false)          - if true and no neurons are recorded in
                                   EPOCHID, add nothing and return the ensemble
                                   element as-is.
    add_to_database (true)       - if true, add the epoch and map documents to
                                   the database.
    Verbose (false)              - print progress messages.

  =========================================================================
  OUTPUT
  =========================================================================
    ENSEMBLEELEMENT - the ndi.element.ensemble (with the EPOCHID epoch added).
    EXISTING        - a cell array of any pre-existing 'ensemble' map documents
                      found for this ensemble element and epoch (empty if none).
                      When CheckExisting is true and this is non-empty, an error
                      is raised instead of returning.

  =========================================================================
  EXAMPLE
  =========================================================================
    ens = ndi.fun.ensemble.create(S, probe, 'epoch_1', 'ensemble_name', 'V1');
    [neuronIndex, spikeTime] = ens.readtimeseries('epoch_1', -Inf, Inf);

  See also: ndi.element.ensemble, ndi.fun.ensemble.load,
    ndi.fun.ensemble.read, ndi.fun.ensemble.findExisting