Ticket #1442: bioplate-events-1.txt

BioPlate events
===============

The attached diagram shows new and modified things in the Biomaterial LIMS.
There are three new classes:

 * BioPlateTypeData
 * BioPlateEventData
 * BioPlateEventDefinitionData

In addition there is a new link from BioMaterialEventData to BioPlateEventData
and the BioPlateData class has several new properties and links.


BioPlateTypeData
----------------

This class is used to group bio plates into different types. A type can:

 * be locked to a specific biomaterial type which means that it is not 
   possible to mix, for example, samples and extracts on bioplates that
   uses the type.
 * lock the wells on the bioplates that uses the type. This means that once
   a biomaterial has been put in a well, it can't be moved to a different
   plate/well, nor can it be replaced with another biomaterial

The plate type is also used to "root" event definitions, which means that
an event is only possible for bioplates of a specific plate type.

The installation will (at least) create four generic plate types:

 * Generic storage plate: mixing is allowed, wells are not locked
 * Sample reaction plate: only samples, wells are locked
 * Extract reaction plate: only extracts, wells are locked
 * Labeled extract reaction plate: only labeled extracts, wells are locked

Already existing bioplates will be assigned to the "Generic storage plate"
type. Plate types are global resources, which means that they don't have an 
owner, and everyone has at least read permission to them. Create and edit
permissions are only granted to administrators (or power users?).

Q: I am thinking that it might be a good idea to define one plate type for
each step in the lab procedures. Or at least those steps that are important to
be registered in BASE. This way it will be easy to select the next event. For
example, when I have a plate of type X the next event must be Y or Z. However,
I assume that lab procedures vary a lot between labs and even between projects,
so this is probably something that has to be setup by an admin. Maybe we should
think of some kind of import/export functionality that can be used to setup
plate types and event definitions.


BioPlateEventDefinitionData
---------------------------

This class is used to define an event that is re-occurring in the lab. It is
linked to a specific source plate type and, if the event generate new plates,
also to a destination plate type. A default protocol, hardware (eg. some kind
of robot), label and mapping can be selected. It is possible to lock this or
allow it to be changed at the time of the event.

An event definition can define three types of event (the same type that are
currently possible for biomaterials):

 * Creation event: An event that creates a new bio plate
 * Hybridization event: An event that creates new hybridization(s)
 * Other: An event that doesn't create anything. It is merely registered as
   something that happened to some plate.

Event definitions are personal resources. Eg. there is an owner and they need
to be shared to the proper user/groups/projects before other user can use them.
This makes it possible to define different workflows in different projects.
Create permission is granted to power users (or users?).


BioPlateEventData
-----------------

This is the registration of an actual event that has happened to a plate. The
information is similar to what is registered in a BioMaterialEventData object 
(date/time, user, a comment, etc.) There is a link to the source plate. If the
event is a creation event the destination plates are also registered. The new
biomaterial that is created in the destination plates are linked back to the
biomaterial in the source plates using individual BioMaterialEvent objects.
The selected mapping is used to determine how the coordinates are related
between the source and destination plates. Here we need a way to allow users to
override the default mapping for a specific event. It is not yet fully
investigated how to do this.

The new biomaterial will have individual BioMaterialEvent:s attached to them
which is more or less copies of the plate event. This is needed to maintain 
backwards compatibility. Editing of the individual event is disabled, but they
are synchronized with the plate event and any changes made to the plate event
are also copied to the individual events.

Q: What about quantities? We never discussed it. Should this also be a property
of the plate event and the same amount is applied to all biomaterials on the
plate?

Q: Pooling events are not possible with the current design. The plate mapping is
re-used from the Array LIMS and a destination well can only have a single source
well linked to it. Is this too limiting?

Q: Permission-wise I am not sure how plate events should be handled. The 
permission system can either handle it is a standalone item, or as a child
item. The most natural would be to handle events as a child item to some plate.
The problem with this is that multiple plates may be created by the same event
and there is no natural parent item. The drawback with a standalone permission
system is that users must manage the permissions also for events and not just
for the plates. A similar problem arises if we start to delete plates. Do we
handle the events as child items and delete them also, or is the user required
to delete the events as well? What should happen to the biomaterials on a plate
that is deleted?