ndi.fun.probe.geometry.fromKilosortMap

  NDI.FUN.PROBE.GEOMETRY.FROMKILOSORTMAP - create NDI geometry documents from a Kilosort-style channel map

  [PG_DOC, S2C_DOC] = NDI.FUN.PROBE.GEOMETRY.FROMKILOSORTMAP(S, PROBE, SOURCE, ...)

  Reads a Kilosort/KIASORT-style channel map and creates the NDI documents that
  describe the electrode geometry of PROBE in the ndi.session S:

    pg_doc  - a 'probe_geometry' document (per-site coordinates), and
    s2c_doc - a 'site2channelmap' document (which recording channel each site is).

  This is the inverse of NDI.FUN.PROBE.GEOMETRY.TOKILOSORTMAP: after running it,
  that function (and ndi.fun.probe.import.kiasort.run) will build a channel map for
  KIASORT from the probe's stored geometry instead of a linear placeholder.

  SOURCE is either:
    - a path to a .mat file containing the channel-map variables, or
    - a struct with those variables as fields.
  The recognized fields (Kilosort convention) are:
    xcoords    (required) - N x 1 horizontal position (microns) of each channel
    ycoords    (required) - N x 1 vertical/depth position (microns) of each channel
    kcoords    (optional) - N x 1 shank id per channel (default all ones)
    connected  (optional) - N x 1 logical, which channels are live (default all true)
    chanMap    (optional) - N x 1 channel indices; validated for length only (the
                             coordinates are taken as already in recording-channel
                             order, which is how Kilosort stores xcoords/ycoords)
    name       (optional) - probe model string (e.g. 'NP2')

  Coordinate/axis mapping into probe_geometry:
    xcoords -> site_locations_leftright
    ycoords -> site_locations_depth
    kcoords -> shank_id
    site_locations_frontback is set to zeros (a planar/2-D probe).

  site2channelmap.map is built as site i -> channel i for connected channels and
  NaN for unconnected channels, so a subsequent NDI.FUN.PROBE.GEOMETRY.TOKILOSORTMAP
  reproduces the same connected mask.

  Name/value pairs:
  ---------------------------------------------------------------------------------
  | Parameter (default) | Description                                              |
  |---------------------|----------------------------------------------------------|
  | probe_model ('')    | Overrides the model string (else uses SOURCE.name).      |
  | manufacturer ('')   | Manufacturer string for the probe_geometry document.     |
  | unit ('um')         | Spatial unit stored in the probe_geometry document.      |
  | add (true)          | Add the created documents to S's database. If false, the |
  |                     |   documents are returned but not committed.              |
  | verbose (1)         | 0/1 Should we be verbose?                               |
  ---------------------------------------------------------------------------------

  Example (an NP2 channel map):
     p = S.getprobes('type','n-trode');
     ndi.fun.probe.geometry.fromKilosortMap(S, p{1}, '/path/to/NP2_channel_map.mat');
     % verify:
     G = ndi.fun.probe.geometry.get(S, p{1});
     ndi.fun.probe.plotProbeGeometry(G.pg_doc);

  See also: NDI.FUN.PROBE.GEOMETRY.TOKILOSORTMAP, NDI.FUN.PROBE.GEOMETRY.GET,
    NDI.FUN.PROBE.PLOTPROBEGEOMETRY