Draft 0.1.0 - Samples and core

[rhfogh]

This discussion should cover the Sample shipping draft (Ed Daniel, 20240425) viewable here, and the general model draft (also relevant to samples) 0.1 (also relevant to samples, Rasmus Fogh, 20240505) presented here , and particularly how they can be merged.

It should be noted that it is generally not the idea to replace the Sample model schemas with the core v0.1 schemas – there should be no schemas corresponding to a bare LogisticalSample’. Rather we should aim to merge the two models by making some limited changes so that the detailed classes can be implemented as subtypes of the abstract core classes.

Below summary of the main differences between the two models:

Style

It would be good if we could agree on formatting. RF had used snake_case for properties (which I think was more or less agreed in one of the MXLIMS meetings), but the ED model uses camelCase. Also, the ED model has schema names with spaces, like ‘In-situ crystal’, whereas the RF model uses CapWords for schema names. Either will do, really, but we ought to harmonise.

Nested sample holders

The RF model has Shipment, Dewar, Pin, Plate Well, Well drop, Mounted crystal and In-situ Crystal all modelled as subtypes of the LogisticalSample in order to make the model easier to store in a simple database. This does not mean that all those classes have to be the same, or that any of their contents have to be removed. The links would also remain the same – a Plate can contain wells, not poins – but only the names of th links should be changed to contents, instead of dewars pins, pucks, wells, ... The other difference is that all these classes have the links that are available to the LogisticSample, even though it does not make sense to populate that link in all cases.

Linking to Samples

The ED Sample matches the RF model SamplePreparation (unless we can think of a better name – would just ‘Sample; do?). In the ED model Samples are linked only to Crystals (In-situ or mounted). In the RF model it must be possible to link them also to low-level sample holders like drops, CrystalDirect loops, SSX grids or liquid streams, or opaque multi-crystal cubic-lipid-phase samples. In all these cases it is possible that the actual crystals may only be identified after the experiment has started, e.g. via a mesh scan. It also seems wasteful to have to specify a separate Sample record for every hole in a SSX grid. That being so it becomes necessary to allow links to Sample from more than one level of the nested Sample holders – and in the interest of generality the RF model went for putting that link inside a single abstract superclass.

Precise v. general classes

The ED model has modelled every case very precisely. This is good for validation, but leads to a very large number of classes. There is the risk that this might make the model harder to use and maintain in the longer run; arguably this has been a problem with ISPyB. The RF model tries instead to combine many classes into a lowest-common-multiple class, where many or most fields may be optional. This reduces the number of classes. There are several examples:

Region specification

The ED classes ‘In-situ crystal’ and ‘Mounted crystal’ are combined into the RF ‘Crystal’ class, and the ED classes Image Region, Plate Region, Region, Point, Line, Circle, Rectangle, and Polygon, and Drop image are all handled by the RF classes Region and CrystalImage. There is no loss of information, all fields are preserved, though, again, there are some attributes that are only used in some cases (like ‘radius’) and the consistency between the region type and the number of points it needs may be harder to enforce.

Crystal form

The ED Crystal form record contains unit cell parameters and a space group name, with the explicit comment that these must all be mandatory. There are, however, use cases where the space group information can be partial or ambiguous. One is passing characterisation results to strategy generation or processing – the Bravais lattice does not allow you to discover the precise space group. Another is when prior information either includes multiple possible space groups, or if it is not possible to distinguish rotation axes form screw axes with certainty. It would be possible to use a single schema for all these cases if 1) the Unit Cell parameters and the apace group were both made optional, and 2) you added as an additional attribute a list of crystal class names to specify ambiguous situations. Which is what is in the RF proposal.

Diffraction plans etc.

This is an extension rather than a change from the current ED proposal, but the proposed way of handling diffraction plans deserves a mention. Essentially RF proposes to use the same schemas describing actual experiments and data sets also to describe diffraction plans and processing plans. A Logistical Sample have attached a number of Jobs. You would then create what amounts to a dummy Job for the experiment, containing the parameters (e.g. the strategy, target resolution etc. ) that you want to acquire, with attached template Datasets to describe the precise acquisition parameters. In each case you would only fill in the parameters you wanted to set explicitly, which might mean leaving most of the records empty for the beamline to fill in by default, and there would be no actual data associated with your template Dataset. You could have different templates for characterisation, and for acquisition, and even for mesh scans if you had a need for that. You would do the same thing with a processing job to make a processing plan, and attach this job to the LogisticalSample.