Overhaul IndexSeries and add "order_of_images" to Images

[rly]

Fix #458

[bendichter]

Maybe add ImageStack ndtype, where the first dim is n_image, but has no timing info. This could be VectorData so that we could put it into a DynamicTable and add metadata

[rly]

I added an ImageStack type and changed IndexSeries to use it. Please review. @oruebel @bendichter @ajtritt

[rly]

TODO: Allow Images and ImageStack in the nwbfile/stimulus group

[rly]

TODO: consider how images are referenced in a table of image presentations (on time, off time, other metadata). Is it possible to reference an Image from a column in a TimeIntervals or other DynamicTable?

[rly]

After discussing this issue with @oruebel, we decided to postpone resolving this until NWB 2.5.0 while we consider the different options and talk with relevant parties.

Another idea is to create an ImageReferenceSeries that has a dataset of references to Image objects, rather than use indices into an ordered dataset. We would then deprecate IndexSeries. This may be simpler.

[bendichter]

@rly , @oruebel can we revisit this?

[oruebel]

@bendichter lets revisit this PR during our next sync

[rly]

Upon discussion with @oruebel and @bendichter, we decided to implement:

• Allowed NWBFile/stimulus/templates to contain Images objects. (Overhaul IndexSeries and add "order_of_images" to Images #459)
• Added new optional "ordered_images" dataset to Images that contains an ordered list of object references to
  Image objects stored in the same Images object. (Overhaul IndexSeries and add "order_of_images" to Images #459)
• Overhauled IndexSeries type (Overhaul IndexSeries and add "order_of_images" to Images #459):
  • Fixed dtype of data dataset of IndexSeries (int32 -> uint32).
  • Updated unit attribute of data to have fixed value "N/A".
  • Updated docstrings for the conversion and resolution attributes of data to indicate that
    these fields are not used.
  • Added link to an Images object, which contains an ordered collection of images.
    Discouraged use of the indexed_timeseries link to an ImageSeries.

We decided not to implement the ImageStack or ImageStacks neurodata types because those data can be represented using an Images type with the ordered_images dataset. If there is a use case where storing image stack data as an N-dimensional dataset is more preferred than storing M (N-1)-dimensional datasets in a group, then we can consider adding an ImageStack type.

We could also revamp IndexSeries in a different way by creating a new ImageReferenceSeries type that has a dataset of references to Image objects, rather than use indices into an ordered dataset of references to datasets in the Images group. Those images could reside within the ImageReferenceSeries type or in a separate Images group. Then we would deprecate IndexSeries. We would probably still want to keep the addition of "ordered_images" to the Images type. To me, this seems cleaner, though perhaps more disruptive.

i.e.

neurodata_type_def: ImageReferenceSeries
neurodata_type_inc: NWBContainer  
# NOTE this is not a TimeSeries because the dtype of data is not numeric and does not have attributes conversion, resolution, offset, unit
doc: A TimeSeries-like container that represents the times at which different images were displayed or acquired. 
datasets:
  - name: data
    dtype:
      target_type: Image
      reftype: object
    dims:
    - num_times
    shape:
    - null
    doc: References to images stored in this object.
  - neurodata_type_inc: Image
    doc: Images stored in this collection.
    quantity: '+'
  - ...  # description, timestamps, etc.

As designed in this PR, the API or user must do the following to get the images used in the IndexSeries in order:

images_container = nwbfile.stimulus_templates.get("Images")
images = [images_container.ordered_images[x] for x in index_series.data[:]]

Whereas with the ImageReferenceSeries above, the API or user must do the following:

images = image_reference_series.data[:]

@oruebel and @bendichter, what do you think? I am happy to go either way on new IndexSeries vs ImageReferenceSeries. Just wanted to present this alternative since we have not discussed it previously.

[bendichter]

looks great!

[oruebel]

Looks good to me