[[PageOutline]]

= MeLuDI 1.5.0 User Manual =

== 1 Introduction ==

Welcome to MeLuDI, a [http://base.thep.lu.se BASE] extension package with registration wizards for melanoma-lung cancer projects.

=== 1.1 What's in this manual ===

==== 1.1.1 Manual sections ====
This manual is intended to be helpful for the daily user of MeLuDI. Sections marked with an asterisk (`*`) are not absolutely essential to using the software, and can be skipped, if an answer to a specific question is desired. However, the reason for including these sections at all, is that they may add to the total understanding of the context in which MeLuDI works and was developed.

==== 1.1.2 Version disclaimer ====
This manual covers MeLuDI v.1.5.0. Even if a newer version is used, the main functionality should be similar, although some wizards may have additional input fields.

=== 1.2 *Background (for history buffs) ===

==== 1.2.1 BASE ====
[http://base.thep.lu.se BASE] was developed as a free web-based database LIMS solution for tracking of information and data generated in sequencing and microarray experiments from sample to analysis.

==== 1.2.2 Reggie ====
BASE extension package [http://baseplugins.thep.lu.se/wiki/net.sf.basedb.reggie Reggie] was developed as an interface to BASE, tailored to the laboratory workflow for the [http://scan.bmc.lu.se/index.php/Main_Page SCAN-B] breast cancer project (more accurately, to the part known as SCAN-B Primary). Reggie both simplifies entry of LIMS data into BASE, as well as inspection of the data and production of documents such as dilution protocols and results reports. At the time of writing, Reggie provides help with management of the complete pipeline from incoming samples, through extraction, library preparation, pooling for sequencing, secondary analysis of the NGS sequencing output, report generation and digital distribution.

==== 1.2.3 MeLuDI mid-2014 - mid-2016 ====
[http://baseplugins.thep.lu.se/wiki/net.sf.basedb.meludi MeLuDI] was later developed as another BASE extension, based on Reggie, but intended for melanoma-lung cancer projects.
It was named "MeLuDI" after the original project it was developed for, which got its name from "melanoma/lung cancer diagnostics". (When the name "MeLuDI" is used in this document without further specification, the reference is to the software.) MeLuDI was developed continuously until version 1.4.3, when the original MeLuDI project was terminated. The software then covered a workflow from sample registration to library preparation. 

==== 1.2.4 MeLuDI fall-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 *Motivation for use ===

==== 1.3.1 Why use a database to store LIMS info in? ====

The excellent search abilities of a database, especially a relational database, is normally enough to justify its use.

==== 1.3.2 Why use BASE? ====

If you work with a genomics project, BASE provides a convenient interface to the underlying database:

 a. Listings of items like samples, extracts, bioplates, etc. can be easily selected from menus, and filters and sorting rules can be entered in a simple way.
 b. BASE is built with a knowledge of the relationship between the different items, e.g. an extract item can be created from the page describing the parent sample/extract, and the created extract will automatically be linked to the parent item, and the new child item will appear on the page for the latter.
 c. BASE contains tools to simplify import/export of data in batch-mode, e.g. batch import can be made from definitions in a text file with tabular data in tab-separated columns.
 d. Project and user management. BASE allows data to be coupled to a project item, and the system normally only shows items for that project, but items can also be shared to several projects. User administration is also included, where a user can be given different sets of permissions in different projects.
 e. Support for two-factor authentication for increased security.
 f. Web-based interface. When BASE was first conceived, not all database management systems had web-based interfaces.

The decision whether to use BASE or not, often depends on the prevalent digital infra-structure for the laboratory. Much of the work in creating a new BASE installation is related to setting up the server and installing the database, that BASE will use. If a BASE installation already is present in the laboratory, much is simplified. However, the final decision may also depend on other conditions, e.g. requirements to use another LIMS system by regulations or policy decisions.

==== 1.3.3 Why use MeLuDI? ====

Although genomics data can be entered directly in BASE, if you are working in a project with a workflow similar to that covered by MeLuDI, its use will simplify several things:

 a. Creation of multiple extract items from the same parent sample/extract item in BASE requires performing the same operation repeated times. MeLuDI allows all necessary data to be entered in a wizard, after which it creates the new items with needed database links and attached information.
 b. MeLuDI provides support for naming conventions for different items in a project, something BASE is ignorant of. Specific prefixes and number of digits in serial numbers may be chosen for items such as samples, item lists, storage boxes, library plates, patient items, and library preparation kits. This is also supported by the system proposing serial numbers in names for new items, as well as storage box positions.
 c. MeLuDI uses a suffix system for names of child items inherited from Reggie, where specimens have a dot plus a number added to the case name, DNA extracts have ".d" added to the parent name, FPA aliquots have ".fpa" added to the parent DNA name, etc. This allows the parent heritage items to be identified for an extract directly from the name.
 d. Support exists for creating input configuration files with selected sample names for various instruments, as well as importing measurement values from text files generated by the instruments. Files can also be created for label printers.
 e. MeLuDI allows creation of dilution protocols, plate layouts, and statistical reports in formats, that are suited both for inspection on a screen and for print-outs.
 f. Information related to the same case can be conveniently displayed in a summary page, with links to the individual BASE items, for further inspection in BASE.

=== 1.4 Installing MeLuDI 1.5.0 ===
Please see [wiki:net.sf.basedb.meludi.notes1_5_0 Updating to MeLuDI 1.5.0] for information on how to update and configure MeLuDI.
 
=== 1.5 Miscellaneous ===
[[Image(snake-icon-64.png)]][[Image(spacer_1_0.png)]][[Image(dancing_reggie.gif)]]

Figure 1.1. Reggie the snake, mascot of both the Reggie and MeLuDI BASE extensions. A smaller version of the left image is used as menu icon for Reggie ([[Image(snake-icon.png)]]), while a musical note is used for MeLuDI ([[Image(musical_note.png)]]). 

''Note to non-Swedish readers'': As you might have suspected, various musical references in connection with MeLuDI is caused by it being very close to "''melodi''", the Swedish word for "melody".

== 2 General interface structure ==

MeLuDI inherited a general interface structure from Reggie. The interface was created with the intention of making access to central functionality as simple as possible.

=== 2.1 Start (index) page and some key components ===

 [[Image(MeLuDI_001_index_page_SMIL_01_with_key_elements_numbered_80_pct.png)]]

Figure 2.1. MeLuDI start (index page)

==== 2.1.1 MeLuDI start (index) page key elements ====

 1. BASE main menu bar (Note! Not to be confused with the web browser menu bar at the top).
 2. BASE project menu (the image shows project "SMIL" as active project).
 3. BASE Extensions menu. This is the menu where extension "MeLuDI" is selected.
 4. Name of active project, here: "SMIL". (MeLuDI only)
 5. BASE extension name; also works as quick link to the start (index) page, i.e. the page above.
 6. Link to a MeLuDI web page, e.g. a wizard.
 7. A counter, showing the number of items in queue (optionally) for a wizard.

==== 2.1.2 User permissions and shown sections on the start (index) page ====

The example start page above shows five sections:
 a. Sample processing wizards
 b. Library preparation wizards
 c. Server administrator wizards
 d. Personal information wizards
 e. Statistics and reporting wizards

The number of shown sections on the start page depends on the permissions of the logged-in user, as only sections the user is allowed to use are shown. The example above shows all sections, as the logged-in user is `root`, i.e. system administrator. The "Server administrator wizards" section is only visible for a system administrator, and the "Personal information wizards" section is only visible for a system administrator and users belonging to the `PatientCurator` group.

=== 2.2 Wizard pages and some key components ===

==== 2.2.1 Wizard page example and key elements ====

 [[Image(MeLuDI_002_specimen_tube_registration_page_SMIL_steps_01-02_01_80_pct.png)]]
Figure 2.2. Specimen tube registration wizard steps 1-2 

==== 2.2.2 Wizard steps ====

 1. Wizards are divided into steps, which are shown in sequence. The step number is shown to the left.
 2. When the wizard is entered, only step 1 is shown.
 3. A new step is only shown after the user clicks the "Next" button to continue to the next step.
 4. Only the last step is active. Previous steps are shown, but input fields are disabled.
 5. Previous steps might be collapsed to save space, only showing the step number bar.

 [[Image(MeLuDI_002a_step_numbers_01.png)]]
Figure 2.3. Steps number bar with step numbers.


===== 2.2.2.1 Active and inactive (disabled) steps =====
The active step is indicated by the step number bar being dark blue.
An inactive step is indicated by the step number bar being gray.

 [[Image(MeLuDI_002a_steps_01-02_step_01_disabled_01.png)]]
Figure 2.4. Steps 1 and 2 of the specimen registration wizard. Step 2 is active, while step 1 is disabled.

===== 2.2.2.2 Collapsed steps =====

 1. Only disabled steps can be collapsed, the active step is always expanded.
 2. A step is collapsed, if the wizard finds that there is not enough space to show details of the step.
 3. A step is collapsed, if the user clicks on the step number bar to the left of an expanded step.
 4. A step is expanded, if the user clicks on the step number bar to the left of a collapsed step.

 [[Image(MeLuDI_002a_steps_01-02_step_01_collapsed_01.png)]]
Figure 2.5. Step 1 is here collapsed.

==== 2.2.3 Step forms ====

Most step forms contain four columns:
 1. Input item title.
 2. Input field/menu/checkbox.
 3. Input status (icon: blank, OK, Error).
 4. Input item description/error message.

The status information normally covers errors that can be detected without referencing the database, e.g. if an item name has correct prefix + number of digits, a number is in allowed range, a date has correct format, a personal number is consistent with the control digit (last digit in number), etc.

 [[Image(MeLuDI_002a1_step_02_ok_status_and_message_01_80_pct.png)]]
Figure 2.6. Step form rows for PAD/CL and Number of tubes. Status OK for Number of tubes.

 [[Image(MeLuDI_002a2_step_02_error_status_and_message_01_80_pct.png)]]
Figure 2.7. Step form rows for PAD/CL and Number of tubes. Status error for Number of tubes (value = 0).

==== 2.2.4 Buttons and registration messages ====
===== 2.2.4.1 Cancel and Next buttons =====

Wizard steps except the last normally have a "Cancel" and "Next" button at the bottom.

 1. Clicking the "Cancel" button makes the wizard start with step 1 again.
 2. Clicking the "Next" button makes the wizard continue to the next step.

''Note'': If you want to leave the wizard, don't click the "Cancel" button; click the MeLuDI extension name at the upper left.

 [[Image(MeLuDI_002b_cancel_next_buttons_01.png)]]
Figure 2.8. "Cancel" and "Next" buttons.

===== 2.2.4.2 Cancel and Register buttons =====

The last wizard step has a "Register" button instead of a "Next" button.

 1. Clicking the "Register" button makes the wizard register the entered data in the BASE database.

 [[Image(MeLuDI_002c_cancel_register_buttons_01.png)]]
Figure 2.9. "Cancel" and "Register" buttons.

===== 2.2.4.3 Registration messages and Restart button =====

After registration, one or more messages may be shown at the bottom of the page, together with a "Restart" button.

 1. Clicking the "Restart" button makes the wizard start with step 1 again, ready for a new data entry.

 [[Image(MeLuDI_002e_registration_messages_and_restart_button_01.png)]]
Figure 2.10. Registration messages and "Restart" button.

''Note'': If you want to leave the wizard, don't click the "Restart" button; click the MeLuDI extension name at the upper left.

==== 2.2.5 Error messages ====

If an error occurs when the "Next" button is clicked, an error message is shown in a red text area at the bottom. This is typically errors that only are detected when addressing the database. Don't be intimidated by the sinister look of the message; normally the first part might be instructive. The rest is technical information, that may be useful, if an error in the server or program itself has been found.

 [[Image(MeLuDI_002g_specimen_tube_registration_page_SMIL_step_01_with_error_message_01_short_80_pct.png)]]
Figure 2.11. Step 1 of the specimen registration wizard after the "Next" button has been clicked and an error occurred, here the case number has already been registered for another item.

A very common error message is information that no appropriate items exist as input for a wizard:

 [[Image(MeLuDI_002g2_create_new_start_dna_plate_page_SMIL_step_01_with_error_message_01.png)]]
Figure 2.12. Step 1 of the create new start DNA plate wizard, when no suitable input items exist (here start lists).

=== 2.3 Wizard pages and some standard input elements ===

Wizards make use of most standard input elements in web pages, e.g. text input fields, menus, check boxes, etc. This section only contains comments on some of them.

==== 2.3.1 Required and optional text input fields ====

 1. Required text input fields have blue background. A required field is not allowed to be empty.
 2. Optional text input fields have white background.

 [[Image(MeLuDI_002j_pad_and_number_of_tubes_input_fields_01.png)]]
Figure 2.13. PAD/CL and Number of tubes input fields. The Number of tubes field is required, and has a default suggestion.

==== 2.3.2 Date input fields ====

 1. Date input fields are text input fields, but normally have a calendar icon to the right ([[Image(MeLuDI_002i_calendar_button_02.png)]]).
 2. Clicking on a calendar icon makes a BASE calendar dialog appear.

 [[Image(MeLuDI_002k_arrival_date_and_sampling_date_input_fields_01.png)]]
Figure 2.14. Arrival date and Sampling date input fields with calendar icons. The Arrival date field has today's date entered as default.

 [[Image(base_calendar_dialog_01_80_pct.png)]]
Figure 2.15. A BASE calendar dialog. Click on a date to select it. Use arrow at top to change month and year.

==== 2.3.3 User permissions and wizards and results pages ====

If a user has permission to use a wizard, normally all elements of it are accessible. However, there are some exceptions related to patient data:

 1. When registering a new case without (full) patient information, the PAD/CL input field is disabled, if the user does not belong to the `PatientCurator` group.
 2. On the Case Summary page, all personal patient information is hidden by default (patient item number, registration date, and gender are shown), and can only be displayed if the user clicks on check box "Show confidential information" and belongs to the `PatientCurator` group.

 [[Image(MeLuDI_002j_pad_and_number_of_tubes_input_fields_02_pad_field_disabled.png)]]
Figure 2.16. PAD/CL and Number of tubes input fields. The PAD/CL field is disabled, as the user does not have `PatientCurator` permission.

== Next: [wiki:net.sf.basedb.meludi.usermanual_03_case_registration 3 Case registration] ==