wiki:net.sf.basedb.meludi.notes1_6_0

Version 4 (modified by olle, 2 years ago) ( diff )

Updated section on MeLuDI configuration file

Updating to MeLuDI 1.6.0

MeLuDI 1.6.0 contains added functionality to simplify using it with multiple BASE projects. Updating to MeLuDI 1.6.0 therefore requires some extra steps, in addition to the standard update procedure.

Follow this procedure:

1. Preparations before update to MeLuDI v1.6.0

a. Update BASE to at least version 3.15.0, if needed

  1. MeLuDI v1.6.0 requires at least version 3.15.0 of BASE. If needed, update BASE before installing MeLuDI v1.6.0. If the current BASE version is 3.5.0 (minimum version for use with MeLuDI version 1.3.3), perform a two-step upgrade, first 3.5.0 -> 3.6.0, then 3.6.0 -> 3.7.0, followed by 3.7.0 -> 3.15.0.
  2. MeLuDI v1.6.0 should be used with Tomcat 9.

b. Create BASE projects to be used with MeLuDI

  1. Select BASE menu View -> Projects. Add all projects, that are intended to be used initially with MeLuDI. It is recommended to use complete and descriptive names, since the projects are to be selected from their names in BASE "Recently used projects" menu and the project names will be included in headers of generated protocols and reports (names may include spaces). Abbreviations that are commonly used, are of course eligible.
  2. Make sure that Protocol and other BASE items needed for the MeLuDI pipeline, are available for the BASE projects to be used with MeLuDI. If several projects should use the same item, there is no need to store multiple copies of the latter, but one item can be shared to all the projects.
  3. Make a note of the project names, since they are needed for the MeLuDI configuration file.

c. Information and recommendations regarding new MeLuDI configuration file meludi-config.xml

MeLuDI 1.6.0 relies on a data in configuration file meludi-config.xml to obtain project-specific settings.

  1. Backward compatibility with original MeLuDI project.
    If MeLuDI 1.6.0 is to be installed on a BASE server used to store data for the original MeLuDI project (named "MeLuDi" in BASE), settings for the latter must be added in the configuration file, to enable MeLuDI to be used as previously with this project (see next section for what settings to use). Even if no new samples will be registered in the original MeLuDI project, the configuration of prefixes is needed to ensure that "Case summary", "Sample source report", "Sample processing statistics", and other inspection wizards can be used to inspect the data.
  2. Recommendations for choice of project-specific prefixes for item names.
    For each item type, it is strongly recommended that unique prefixes are chosen for all projects to be used with MeLuDI.
  3. Use with non-configured projects.
    MeLuDI 1.6.0 allows a non-configured BASE project to be used as active project, but all item name prefixes will then be empty strings, and item names will consist of a pure serial number with optional suffix (e.g. for storage boxes). If more than one non-configured project is used, the same name might be used for items in different projects, which may cause confusion. This is therefore not recommended.

d. Create MeLuDI configuration file meludi-config.xml

  1. Create a MeLuDI configuration file meludi-config.xml with information on each project to be used with MeLuDI. The configuration file has the following structure, where new elements in MeLuDI 1.6.0 are marked with "NEW" (not part of the XML contents):
<?xml version="1.0" encoding="UTF-8"?>
<meludi>
	<projects>
		<project>
			<name>...</name>
NEW			<referral-prefix>...</referral-prefix>
NEW			<referral-num-digits>...</referral-num-digits>
			<sample-item-prefix>...</sample-item-prefix>
			<sample-item-num-digits>...</sample-item-num-digits>
NEW			<blood-item-prefix>...</blood-item-prefix>
NEW			<blood-item-num-digits>...</blood-item-num-digits>
NEW			<ffpe-block-item-prefix>...</ffpe-block-item-prefix>
NEW			<ffpe-block-item-num-digits>...</ffpe-item-num-digits>
			<storage-box-prefix>...</storage-box-prefix>
			<storage-box-num-digits>...</storage-box-num-digits>
			<start-list-item-prefix>...</start-list-item-prefix>
			<start-list-item-num-digits>...</start-list-item-num-digits>
			<start-plate-item-prefix>...</start-plate-item-prefix>
			<start-plate-item-num-digits>...</start-plate-item-num-digits>
			<patient-item-prefix>...</patient-item-prefix>
			<patient-item-num-digits>...</patient-item-num-digits>
			<libprep-kit-item-prefix>...</libprep-kit-item-prefix>
			<libprep-kit-item-num-digits>...</libprep-kit-item-num-digits>
NEW			<uses-site-prefix>...</uses-site-prefix>
NEW			<site-prefix-hash-list>...</site-prefix-hash-list>
NEW			<uses-referral-creation>...</uses-referral-creation>
NEW			<uses-site-specific-referral-templates>...</uses-site-specific-referral-templates>
			<project-focus-default>...</project-focus-default>
			<specimen-type-default>...</specimen-type-default>
			<specimen-input-type-default>...</specimen-input-type-default>
			<extracts-from-first-specimen-only-default>...</extracts-from-first-specimen-only-default>
			<deparaffinization-rna-volume-microliters-default>...</deparaffinization-rna-volume-microliters-default>
			<deparaffinization-dna-volume-microliters-default>...</deparaffinization-dna-volume-microliters-default>
		</project>
		...
	</projects>
</meludi>

Add a <project></project> XML block for each project. Configuration values for each project:

XML tag name Description Value for original MeLuDI project
name Name of the project item in BASE MeLuDi
sample-item-prefix Prefix for sample item names in project ML
sample-item-num-digits # Digits in sample item names in project 5
storage-box-prefix Prefix for storage box names in project ML_
storage-box-num-digits # Digits in storage box names in project 4
start-list-item-prefix Prefix for start list item names in project SL
start-list-item-num-digits # Digits in start list item names in project 5
start-plate-item-prefix Prefix for start plate item names in project LP
start-plate-item-num-digits # Digits in start plate item names in project 5
patient-item-prefix Prefix for patient item names in project MLP
patient-item-num-digits # Digits in patient item names in project 6
libprep-kit-item-prefix Prefix for library preparation kit item names in project LP_kit_
libprep-kit-item-num-digits # Digits in library preparation kit item names in project 3
project-focus-default Cancer type studied in the project <empty string> (unknown)
specimen-type-default Primary tumor or metastasis <empty string> (unknown)
specimen-input-type-default The form in which a specimen is delivered <empty string> (unknown)
extracts-from-first-specimen-only-default Flag indicating whether extract items should be created for first specimen only false
deparaffinization-rna-volume-microliters-default RNA elution volume (µl) 25
deparaffinization-dna-volume-microliters-default DNA elution volume (µl) 25

Notes:
1. The "name" tag value is used by MeLuDI to identify the project item in BASE, so it is essential that it corresponds exactly to the project item name in BASE.
2. It is allowed to configure MeLuDI for projects, before the latter are created in BASE. A project configuration will only be used, when a BASE project is selected as active.

The menu option values for project focus, specimen type, and specimen input type to use for default choices are:

Project focus
Menu option value Menu option text
unknown
melanoma Melanoma
lungcancer Lung cancer
coloncancer Colon cancer
GIST GIST (Gastrointestinal stromal tumour)
breastcancer Breast cancer


Specimen type
Menu option value Menu option text
unknown
Primary Primary tumour
MetastasisDistant Metastasis


Specimen input type
Menu option value Menu option text
unknown
fresh_frozen Fresh frozen
ffpe_section FFPE section
ffpe_punch FFPE punch
ffpe_slide FFPE slide
cell_line Cell line

e. Install MeLuDI configuration file meludi-config.xml

  1. Place configuration file meludi-config.xml on the BASE server in same directory as base.config.

f. Update MeLuDI case label info file Case_Label_Info.csv, if existing

  1. Check on the BASE server if a MeLuDI case label info file Case_Label_Info.csv exists in BASE user files directory. If it does, MeLuDI versions prior to 1.6.0 stored information in a single line about the highest case number, for which a label file had been created. The line consisted of the string "Highest case number;" followed by the case number. MeLuDI 1.6.0 will store information in one line per project, for which a label file has been created, where each line consists of the project name, followed by a tab character and the case number. In order to make sure that information for the original MeLuDI project is retained, replace the string "Highest case number;" with "MeLuDi" followed by a tab character (Note that for historical reasons, the original MeLuDI project was named "MeLuDi" with a lowercase i at the end). As an example, if the original contents of file Case_Label_Info.csv was "Highest case number;1272", it should be changed to "MeLuDi 1272", with a tab character separating the project name and the highest label case number.
  2. If no case label info file Case_Label_Info.csv exists, no action is needed, since MeLuDI 1.6.0 will create it automatically.

2. Update to MeLuDI v1.6.0

  1. After installation of MeLuDI v1.6.0, run the installation wizard, for each of the configured projects as active project. This assumes that a BASE project exists for all the projects configured in meludi-config.xml. However, it is allowed to configure projects in advance, and then create BASE projects when needed. In that case, run the installation wizard after a configured project has been created in BASE.

3. Check/modify roles of users

  1. MeLuDI v1.6.0 allows a PAD/CL number (Patho-Anatomical Diagnosis/cytology number) to be registered with a case, even if no other patient data is known (e.g. personal number). However, the PAD/CL input field will be disabled if the logged-in user does not have PatientCurator or Administrator roles. If registration of a PAD/CL number is essential, make sure that all users, that should perform the registration, have PatientCurator or Administrator roles.
Note: See TracWiki for help on using the wiki.