[[PageOutline]]

= MeLuDI Software Information =

== 1 Introduction ==
=== 1.1 Description ===
MeLuDI is an ''extension package'' to BASE with registration wizards for melanoma-lung cancer projects, in analogy with the package "Reggie" for the SCAN-B breast cancer project. It is named "MeLuDI" after "melanoma/lung cancer diagnostics". This page gives some background information on the software, and is not intended as a user manual. Instead, some behind-the-scene information is given, e.g. what item properties are used to track what steps in the lab processing pipeline an item has passed, which can be useful, if you want to check items for a specific step directly in BASE, or re-do a step, if an error occurred.

=== 1.2 Links ===

 - BASE (!BioArray Software Environment) is a comprehensive free web-based database LIMS solution for tracking of information and data generated in sequencing and microarray experiments from sample to analysis. BASE is released under the ​[http://www.gnu.org/licenses/gpl.html GNU General Public License version 3]. It can be accessed at http://base.thep.lu.se/.
 - Reggie is an ''extension package'' to BASE that makes it easier to register biosources and samples. It can be accessed at http://baseplugins.thep.lu.se/wiki/net.sf.basedb.reggie.
 - MeLuDI can be accessed at http://baseplugins.thep.lu.se/wiki/net.sf.basedb.meludi. A user manual for MeLuDI 1.5.0 can be found at [http://baseplugins.thep.lu.se/wiki/doc/net.sf.basedb.meludi.usermanual_start MeLuDI 1.5.0 User Manual].

=== 1.3 MeLuDI: The project, and MeLuDI: The software ===

==== 1.3.1 The original MeLuDI project 2014 - 2016 ====
"MeLuDI" (short for "melanoma/lung cancer diagnostics") was the name of a project at the Department of Oncology, Clinical Sciences, Lund University. It was initiated in 2014, went into "production" phase in 2015-01-01, and ended 2016-06-23 after it had been announced 2016-01-21 that another laboratory should perform the analyses in question. The MeLuDI project produced clinical genomics data from samples from patients having specific types of cancer, but also aimed to support cancer research. Originally, the focus was on melanoma and lung cancer, but later on, more cancer types were supported.
As part of the LIMS procedure, it was decided to store sample data in a database managed by BASE, and which normally was accessed through a BASE extension, named "MeLuDI" after the project. The software did not cover all aspects of the project, it was named after. When the name "MeLuDI" is used in this document without further specification, the reference is to the software. The last software version used for the original MeLuDI project was MeLuDI v1.4.3.

==== 1.3.2 MeLuDI software 2016- ====
During fall 2016, a number of research projects at Lund University involved lab work using a workflow very close to the one used for the original MeLuDI project, so it was decided that a modified version of the MeLuDI software was to be used to track samples. MeLuDI was updated to support use in several BASE projects, allowing different items to have project-specific prefixes and number of digits in names, as well as project-specific default values for a number of items. Created documents like dilution protocols and statistics reports were updated to include the name of the active project. Together with other updates intended to support more flexibility in the workflow, the updated software was released as MeLuDI v1.5.0.

==== 1.3.3 MeLuDI software 2018-03- ====
In March 2018, it was decided to extend the MeLuDI software to support the SCAN-B-rec project, and in October 2019, the !NordicTrip project. In addition to extensions of MeLuDI, in order to allow data entries for the new projects, these required referrals in PDF format to be created by the software from PDF template forms, where some text and bar codes had been added by MeLuDI to make each referral unique. Also, the MeLuDI was updated to lessen the risk, that item keys were inadvertently revealed. The updated software was released as alpha- and beta-releases of MeLuDI v1.6.0. 2022-07-18 it was decided that also the LUCAS project should be supported for creating referrals, and MeLuDI v1.6.0 was finally released 2022-08-24.

=== 1.4 Note on BASE annotations ===
BASE was developed to be a web-based interface to a database with bio assay data. In order to simplify adapting the software/database to specific data storage needs, a system of annotation types was developed, making it easy to add storage of new variable data to an "annotatable" item. An annotation type is of a specific data type, e.g. integer, float, string; and is defined for a specific type of item, e.g. samples, extracts, bioplates, item lists, etc.

== 2 Pipeline management ==
=== 2.1 Description ===
MeLuDI, like Reggie, is intended to simplify keeping track on what items are of interest in each step of the processing pipeline, e.g. by only including those items in selection menus for a particular step. In some cases, this is simple, since child items are created at registration in several steps, and will then be input items in the next step. One case where you might be interested in the details of how MeLuDI keeps track of what steps an item has passed, is when you want to undo a step in the BASE GUI by deleting child items created in the last step. Sometimes this is not enough to allow you to redo the last step in MeLuDI, since the needed items do not appear in selection menus, if the software still considers them to have passed the step in question.

=== 2.2 How some wizards perform their magic ===
==== 2.2.1 Wizard "Lab tracking protocol for FFPE extraction": Extract source items added to start list ====
Extract source items (specimens or input extracts) added to a start list have their original quantity changed from `null` to 0.0. This will stop them from appearing in the extract source item selection menu, when the wizard is run again.
==== 2.2.2 Wizard "DNA/RNA registration/quantification": Processing a start list
A start list is regarded as processed, when quantification data for its extracts have been entered. This is indicated by setting value of Boolean item list annotation `Annotationtype.SAMPLE_PREP_LIST_IS_PROCESSED` to `true`.
==== 2.2.3 Wizard "Create new start DNA plate" Step 1: Processed start list to select DNA extracts from
For a processed start list to appear in the start list selection menu, it must contain at least one DNA extract that:
a. Does not have an FPA child extract on a library plate.
b. Is not selected for qPCR.
==== 2.2.4 Wizard "Create new start DNA plate" Step 2: DNA extracts on selected processed start lists
A DNA extract only appears in the DNA extract selection menu, if the extract:
a. Does not have an FPA child extract on a library plate.
b. Is not selected for qPCR.

=== 2.3 Some hints when correcting erroneous MeLuDI entries in BASE ===
==== 2.3.1 General ====
a. The information in this section covers the technical aspects of correcting erroneous MeLuDI entries in BASE. Please check the local lab procedure for the correct way to handle erroneous entries, which for example may require special documentation (on paper or digital) to accompany the action.
b. For details on how to perform specific actions in BASE, please see the BASE documentation.
c. It is always a good idea to get a printout of the current state of MeLuDI, e.g. a lab protocol, before starting to change anything in BASE.
d. It is often a good idea to completely remove an erroneous item, and then re-create it with correct data in MeLuDI. Trying to modify item properties in BASE, may have side effects in the way MeLuDI treats the item. An exception is modification of comment text for an item, that normally can be made without software consequences.
e. If an erroneous entry happens, when a series of entries should be made, it is often best to fix the erroneous entry, before commencing with the rest of the series. This is because of the side effects, an erroneous entry may have for following entries, e.g. recommended serial numbers or locations on storage plates. Fixing a problem later on is possible, but more steps may be necessary. 
==== 2.3.2 Wizard "Create new start DNA plate" Step 2 after registration: Remove an erroneously created start DNA plate
a. The following recommendation concerns removing the most recently registered start DNA plate.
b. Print a lab protocol (Plate layout) of the start DNA plate to be removed. This is preferred over a dilution protocol, since the former contains the name of the library preparation kit.
c. In BASE, delete the Bioplate and all *.fpa and *.fpb DNA extracts on the plate.
d. In MeLuDI wizard "Inspect/edit library preparation kit data", edit the entry for the library preparation kit used for the removed start DNA plate. At entry "Unused FPA plate locations", add the plate positions used for *.fpa DNA extracts on the removed plate to the list. Make sure that the plate positions are separated by a single comma. Save the changes.