Add multi-stimulus file API to StimulusTimestamps

[danielsf]

PR #2354 implements a helper function to register the timestamps in a sync file with multiple stimulus block presentations. We need to be able to use this code to create a StimulusTimestamps object.

Need to be able to return a StimulusTimestamps object that correctly registers multiple stimulus files to one sync file but only returns the timestamps corresponding to the stimulus file of interest. This should be a new class method in StimulusTimestamps that looks something like this

from_multi_stim(
     sync_path: path/to/sync/file,
     list_of_stim: list_of_stimulus_files,
     stim_of_interest: index or list of indices in list_of_stim whose timestamps you actually want)

Tasks

• Implement from_multi_stim in StimulusTimestamps
• Remove StimulusTimestamps.from_json and to_json as it is no longer straightforward to know which timestamps you want if there are more than one pickle files referred to in the dict representation

Validation

• All existing unit tests pass
• There are unit tests round tripping the data through from_multi_stim and to_nwb

[danielsf]

I have most of an (untested) implementation here

https://github.com/AllenInstitute/AllenSDK/tree/ticket/2357/multi/stim/timestamps

To understand what is going on, it may be useful to look at the prototype running speed code Corbett provided, which is cut-and-pasted here

#2331

Basically

1. you use the vsync_stim line to get the timestamps for all frames in the stim file
2. use breaks in the stim_running line to divide the frame timestamps into blocks that correspond to the various stimulus presentation blocks
3. either select the block of timestamps you want, or concatenate them into a single set of timestamps, depending on your use case

This commit

e6d364d

should get us as far as steps (1) and (2).

This commit

cd4f5a4

should achieve step (3). What I do not know is how to represent the fact that a StimulusTimestamps object came from multiple stimulus files in the to_json method of any DataObjects that are constructed from the StimulusTimestamps. Probably, StimulusTimestamps._stimulus_file should have the option to be a ListOfStimFiles object that knows how to write the appropriate data to_json. Any dependent object could, for instance

class RunningSpeed():

    def to_json():
        ...
        if self._stimulus_timestamps._stimulus_file is not None:
            output.update(self._stimulus_timestamps._stimulus_file.to_json())

but I haven't thought that all the way through. Sorry to leave things in such an incomplete state.