Rename multiplier to frames_per_event and move to first dim of shape

[thomashopkins32]

This PR does the following:

• Renames multiplier -> frames_per_event
• Add the frames_per_event as the first dimension of DataKey.shape
• Ensure that the index provided by DetectorWriter.get_indices_written() and DetectorWriter.observe_indices_written() is divided by frames_per_event so that it actually captures the correct amount of exposures in each index (except for PandA which explicitly says it only has 1 "frame" per event)
• Add unit tests showing that describe() works as intended
• Add unit tests showing that stream resources are actually batches of exposures
• Re-order self._writer.open() and self._writer.get_indices_written(). The writer needs to be opened in order to get the indices written. Otherwise, it has no idea what frames_per_event to use when returning the index last written.

I could not actually add tests using bluesky plans and inspecting the data afterword because TriggerInfo is hardcoded in StandardDetector. I think it is a separate issue that should be raised since it would enhance the scope of this PR. I will open an issue for this soon and mention it below.

Otherwise, I have a few open questions regarding my understanding of ophyd-async as well as the implementation which I will also leave as review comments. Please see below.

Closes #576

[thomashopkins32]

Question about shapes when frames_per_event is 1: do we want to always "squeeze" the shape?
I.e. there are a couple of options:

• For 2d arrays:
  • [1, h, w] -> [h, w] when frames_per_event = 1
  • [frames_per_event, h, w] when frames_per_event > 1
• For scalar values:
  • [1,] -> [] when frames_per_event = 1
  • [frames_per_event,] when frames_per_event > 1

Currently, it is set up such that if the result would be a single scalar value, the shape would be replaced with []. Otherwise, the shape always contains the extra dim.

[jwlodek]

I think this is close, just a few minor notes. We should try setting this up in the lab and running a test w/ collecting data from different devices w/ different frames_per_event to make sure it behaves as expected (and also to maybe work out the needed changes to the consolidators).

[jwlodek]

Do we need the # type: ignore here?

[thomashopkins32]

I get the following mypy issue. It looks like event-model does not have a py.typed marker.

[coretl]

Does pyright also complain? If it needs a py.typed then please could you make an event-model PR to add it?

[thomashopkins32]

pyright does not seem to complain, event-model is missing a py.typed marker so I can add it

[thomashopkins32]

PR here: bluesky/event-model#346

[jwlodek]

Question about shapes when frames_per_event is 1: do we want to always "squeeze" the shape? I.e. there are a couple of options:

* For 2d arrays:
  
  * `[1, h, w]` -> `[h, w]` when `frames_per_event = 1`
  * `[frames_per_event, h, w]` when `frames_per_event > 1`

* For scalar values:
  
  * `[1,]` -> `[]` when `frames_per_event = 1`
  * `[frames_per_event,]` when `frames_per_event > 1`

Currently, it is set up such that if the result would be a single scalar value, the shape would be replaced with []. Otherwise, the shape always contains the extra dim.

I think I'd be in favor of avoiding such squeezing, because then we'd need a separate parameter to let us know if it had been squeezed or not. Say we have a frames_per_event of 1 w/ a dataset that's 10 x 10. If we squeeze we get [10, 10] as the shape, but there's no way of telling if this is actually a 1D dataset of size 10 w/ 10 frames per event.

[thomashopkins32]

@jwlodek so the current squeezing behavior for the shape is

• For 2d arrays:
  • [frames_per_event, h, w] (even if frames_per_event is 1)
• For scalar values:
  • [1,] -> [] when frames_per_event = 1
  • [frames_per_event,] when frames_per_event > 1

The final change I would make based on your comment would be to remove the squeezing on scalar values from [1,] -> [].

[thomashopkins32]

Should be ready to review once more. The new shape behavior is such that the frames_per_event is always the first dimension of shape. If the len(shape) > 1, then the dtype is an array, otherwise, its a number.