feat: add support for calibration objects

[dbirman]

This PR adds a CalibrationObject that can be used as a Subject.subject_details option.

[dyf]

If my phantom is a bunch of beads embedded in a gel, how would I represent that as a device?

[dbirman]

If my phantom is a bunch of beads embedded in a gel, how would I represent that as a device?

notes: "Beads in a gel"?

I guess I was assuming phantoms here were objects purchased from somewhere whereas people here are making their own phantoms? Maybe we need to get some information about what requirements phantoms needs to have, or keep it generic and just make a class with a description: str field and let people write something down.

[dyf]

Okay I like that. My suggestion is

class PhantomDetails(DataModel):
   description: str
   devices: list[Device]

[saskiad]

I'm really not keen on having a subject when there literally is no subject

[saskiad]

I'm confused why we decided not to use the solution we decided on back in the day?

[dbirman]

I'm confused why we decided not to use the solution we decided on back in the day?

Because we didn't used to have a concept of "subject details" the subject class was a hodgepodge of fields related to the subject. Now that there's a clean differentiation between mouse/human (and other things) it's more obvious that a phantom is just an alternate set of details in the Union. See also David's original post.

I think this solution is cleaner than adding a new data level concept in my opinion, at the end of the day the data is no different than data acquired with a mouse (or human) in an instrument it's the subject of the acquisition that has changed.

[saskiad]

I still disagree.
First, The subject class is information about the animal that data is collected from. With this change, this isn't true. It's information about the object(?) data is collected from. But now, if I'm imaging a brain slice, why do I need the subject and procedures, why can't I just have "SliceDetails" for my subject? I think we're opening a slippery slope by broadening the concept in this way.
Second, I still strongly think we need a data level for calibration data.
Last, I think the term Phantom is confusing.

[saskiad]

Additional points:
A lot of calibration data has no subject and no device. Eg flat field correction. This doesn't address that need.
The example given (beads in a gel) is a poor motivation for me. In my experience, imaging beads is done to align the laser adjust the light path, and calibrate PSF. I didn't save any data or do anything with it outside beyond the acquisition rig. If you have a specific use case, I'd love to hear it. But I don't really think imaging beads is it.

[dbirman]

Additional points: A lot of calibration data has no subject and no device. Eg flat field correction. This doesn't address that need. The example given (beads in a gel) is a poor motivation for me. In my experience, imaging beads is done to align the laser adjust the light path, and calibrate PSF. I didn't save any data or do anything with it outside beyond the acquisition rig.

If this is what we're discussing then we're going in circles, if there's no data asset there's no metadata...

I'm pretty sure David's intention in opening this issue was for the situation where a real data asset gets generated and sent downstream. I'm thinking about this coming from MRI where phantoms are a common thing, and they have two requirements that affect us: (1) the data asset generated with a phantom is indistinguishable from an asset from a human/animal, (2) processing pipelines can be run on these assets for testing.

The consequence of (1) is that the metadata is the only thing that tells us a phantom (or calibration object) was used. It feels very natural to put that data into the Subject.subject_details field. I hear your argument that you don't want to dilute subject as being about the original data source and I disagree that a calibration object is not an original data source in the same way that a human or animal is. I'm find finding a different place in the metadata to store this if you have an idea in mind, but I don't see another place.

The second issue is what convinces me that we shouldn't add a data level. What's different about these assets would not be the asset structure, which is really what DataLevel tells you.

[dbirman]

I moved this issue to point at 2.x, it's not blocking for 2.0

[dbirman]

• CalibrationObject instead of PhantomSubject
• CalibrationObject.empty: boolean <- no actual object was used in the calibration
• CalibrationObject.object: Union[str, Device] <- clear description
• Metadata-level validator that checks that the tag "calibration" shows up in data_description when a CalibrationObject is used