How to use custom library prep and index kits with Local Run Manager v3 and v4

Local Run Manager (LRM) is the integrated run planning and analysis software for most Windows-based Illumina benchtop sequencers. LRM version 3 is available for on-instrument analysis of run data from MiSeq systems running MiSeq Control Software version 4 and LRM version 4 is available for on-intrument analysis of run data from NextSeq 500/550 systems running NextSeq Control Software version 4.2. The iSeq 100 and MiniSeq systems currently run LRM v2 onboard. Note that sample sheets from Illumina Experiment Manager are not compatible with LRM v3 or v4. LRM v3 and v4 sample sheets can be exported from the LRM interface, or templates downloaded with the available module. You can use the LRM Module Selector Tool to ensure you are downloading the correct version of the module for your framework.

LRM v3 and v4 separate library prep kits and index kits into separate files, and files are compatible between LRM v3 and v4. Standard Illumina preps and indexes are included as built-in options in LRM modules; custom kit files from previous versions of LRM (v1 and v2) are not compatible with v3 and v4. LRM v3 and v4 also include a “Custom” option for manual entry of sample and index information during run setup. Custom and third-party library prep kits and index kits can be added to LRM and must be uploaded to the LRM interface before run set-up. The Local Run Manager Software Guide contains information on the content of the custom library prep and index files, and more details are provided below.

Important note: These directions are intended for versions 3 and 4 of LRM. For users with version 2 of LRM, refer to the bulletin Local Run Manager 2: How to use a custom library prep kit. For MiniSeq users using the on-instrument version 1 of LRM, refer to the bulletin Local Run Manager v1.3 for MiniSeq: How to use a custom library prep kit. Do not install LRM v3 or v4 on any instrument computer for which it was not designed.

To add a custom library prep and index kit to LRM v3 or v4, perform the following steps:

1. Connect to LRM via a web browser either via https://localhost/ if on-instrument, or using the instrument name or IP address if connecting over a network (network access currently only supported with LRM v4) and select the Tools dropdown menu then select Index & Library Prep Kits:

1. Select either the Library Prep Kit or Index Kit tab. Note that adding a new Library Prep Kit is not required in all cases, as custom index kits can be added to an existing Library Prep Kit if they are similar kit types. If you are adding a new index kit to an existing Library Prep Kit, skip to the section Adding a custom Index Kit.

Adding a custom Library Prep Kit

1. Select the Library Prep Kit tab and either select Download Template for the general template, or download an existing file to modify using the download button next to that kit.

2. Open the template file in either Excel or a plain text editor such as Notepad and edit the fields as follows:

   1. [LibraryPrepKit]: This section contains the default run parameters for the library prep kit types:

      1. The Checksum entry is not required for custom kits.

      2. The Name section must be unique for all kits.

      3. DisplayName: How the library prep will appear in LRM. Only alphanumeric, period, dash, and space characters are allowed.

      4. Description: A short description of the kit. Only alphanumeric, period, dash, and space characters are allowed.

      5. ReadType: Available options are Single, Paired, or All.

      6. The default number of cycles for Read 1 and Read 2 are specified in DefaultReadLength1 and DefaultReadLength2, respectively.

   2. [Resources]: Set custom parameters here. This section is optional. For more information on available parameters, see the Local Run Manager Software Guide. Note that adapter trimming is not entered here, but instead in the Index Kit.

   3. [SupportedModules]: Include the name of the analysis module or modules that can make use of this kit when creating a run. Multiple modules should be included on separate lines. The full module name must be used, with no spaces, such as GenerateFastQWorkflow. Refer to the Local Run Manager Software Guide for a full list of available modules.

3. Save the file, making sure to retain the format as TSV. Do not include spaces or special characters in the file name.

4. From the LRM dashboard, select the Tools dropdown menu, Index & Library Prep Kits, Library Prep Kit, then Add Library Prep Kit. The new library prep kit will then be available for selection during run creation.

Adding a custom Index Kit

1. Select the Index Kit tab and either select Download Template for the general template, or download an existing file to modify using the download button next to that kit. Index Kits can either have a fixed layout where each well has a defined index combination, or a non-fixed layout where any index can be selected for any sample.

2. For non-fixed layout index kits, open the template file in either Excel or a plain text editor, such as Notepad and edit the fields as follows:

   1. [IndexKit]: This section contains the default parameters for the index kit.

      1. The Checksum entry is not required for custom kits.

      2. The Name section must be unique for all kits.

      3. DisplayName: How the library prep will appear in LRM. Only alphanumeric, period, dash, and space characters are allowed.

      4. Alias can be optionally used to overwrite existing kit values with the values in this kit; this parameter can be omitted if not used.

      5. Description: A short description of the kit. Only alphanumeric, period, dash, and space characters are allowed

      6. Available options for IndexStrategy are NoIndex, SingleOnly, DualOnly, SingleAndDual, NoAndSingle, NoAndDual, or All.

   2. [Resources]: Set custom parameters here. This section is optional and is where adapter trimming information is entered. For more information on available parameters, see the Local Run Manager Software Guide.

      1. Adapter trimming (optional): Adapter sequences can be included in the Resources section of the kit definition to enable adapter trimming of FASTQs. Adapter trimming can also be toggled off during run setup in the Module-Specific Settings. For paired end kits with the same adapter on both reads (such as Nextera-based kits), only a single Adapter entry is needed. For kits where the Read 1 and Read 2 adapter sequences differ (such as TruSeq-based kits), a separate AdapterRead2 entry is needed. An example of how to enter these values is shown for a TruSeq kit below, where the arrows indicate tab entries in the TSV file. Note that the LibraryPrepKits column can be left blank if these values apply to all supported library prep kits:
   3. [Indices]: Specify which index sequences will be used with this kit. Include the Name along with the Sequence and IndexReadNumber (1 or 2). After loading the custom kit into Local Run Manager, sequences are selected using the Name value. Important Notes:

      1. Never reverse complement the second index sequence, only use the forward orientation. LRM will do so automatically during demultiplexing as necessary based on the instrument type.

      2. Mixing indexing lengths and types (eg, dual and single) within a kit and run is not supported. Index lengths must be consistent and only A, G, C, and T bases are valid. N cannot be entered and used as a wildcard in a library prep kit. N can be manually entered when using the “Custom” option.

      3. Index names are limited to 50 characters. Attempting to upload a kit template with index names longer than 50 characters will result in an error on import.

   4. [SupportedLibraryPrepKits]: Include the name of the Library Prep kit or kits that can make use of this index kit when creating a run. Multiple Library Prep kits should be included on separate lines. The full module name must be used, matching the Name value from the Library Prep Kit file. This section can include existing Illumina Library Prep kits or custom Library Prep kits created as described in the previous section.

3. For fixed-layout kits open the template in a plain text editor such as Notepad. Excel is not recommended for editing this template type. It will automatically convert the required Boolean values to uppercase and disrupt usage of the fixed-layout information. Fixed-layout kits are most commonly used for unique dual index (UDI) sets.

   1. [IndexKit] contains the same values as described above in the non-fixed layout section.

   2. [Resources]: Entries in this section are required in order to designate the index kit as fixed layout. Adapter trimming is optional and is entered in the same way as described in the non-fixed layout section above.

      1. To set up the fixed layout, include the following tab-separated string:

   Important Note: The Boolean “true” value must remain lowercase for LRM to recognize this kit as fixed layout. Using Excel will automatically convert “true” to “TRUE”, and LRM will no longer recognize this kit as fixed layout. 2. Enter the value of the well designated for the particular index pair along with the FixedIndexPosition flag, designate the values as a string, and enter in the associated two indexes separated by a dash. All values must be tab-separated. The index names and values will be defined in the next section. Examples of entries for these are shown below:

   1. [Indices]: Specify which index sequences will be used with this kit. Include the Name along with the Sequence and IndexReadNumber (1 or 2). After loading the custom kit into Local Run Manager, sequences are selected using the Name value. The index Name values must match the values used in the FixedLayout section. Important Notes:

      1. Never reverse complement the second index sequence, only use the forward orientation. Local Run Manager will do so automatically during demultiplexing as necessary based on the instrument type.

      2. Mixing indexing lengths and types (eg, dual and single) within a kit and run is not supported. Index lengths must be consistent and only A, G, C, and T bases are valid. N cannot be entered and used as a wildcard in a library prep kit. N can be manually entered when using the “Custom” option.

      3. Index names are limited to 50 characters. Attempting to upload a kit template with index names longer than 50 characters will result in an error on import.

   2. [SupportedLibraryPrepKits]: Include the name of the Library Prep kit or kits that can make use of this index kit when creating a run. Multiple Library Prep kits should be included on separate lines. The full module name must be used, matching the Name value from the Library Prep Kit file. This section can include existing Illumina Library Prep kits or custom Library Prep kits created as described in the previous section.

4. Save the file, making sure to retain the format as TSV. Do not include spaces or special characters in the file name.

5. From the LRM dashboard, select the Tools dropdown menu, Index & Library Prep Kits, Index Kit, then Add Index Kit. The new library prep kit will then be available for selection during run creation.

For any feedback or questions regarding this article (Illumina Knowledge Article #5897), contact Illumina Technical Support [e-mail].