Create a Custom Index Adapter Kit

Run Planning provides a list of Illumina index adapter kits used for sequencing. If your index adapter kit is not available, please follow the following instructions to create a custom one.

Creating a custom index adapter kit can be done from within Run Planning (when creating a Configuration) or from the Resources page (select Index Adapter Kit tab).

A custom Index kit can be configured in yaml or tsv.

Configuring in yaml

The following are basic rules to follow when configuring in yaml

• 3 dashes indicates the start of the definition

• Begin a comment line with '#' character

• Each line is typically in the format of SettingName: SettingValue. Setting which value is a string has to be enclosed in double quotes. Other types like numeric or boolean do not require double quotes.

• When a setting contains more complex information, it is usually defined in multiple lines. Ensure the right indentation to maintain the structure. Use two space characters instead of a tab character.

Three yaml templates are provided.

1. Non-fixed Layout: for non-fixed layout kit where any index can be selected for any sample.

2. Fixed Layout - Single Plate: for fixed layout kit with single plate, where each well has a defined index combination.

3. Fixed Layout - Multi Plate: for fixed layout kit with multi-plate, where each well has a defined index combination.

Setting Details

Level-1 Setting	Level-2 Setting	Description
Name		Name of the kit. It is an internal name, which has to be unique within a domain.
DisplayName		Display name of the kit. It is used for the index kit display label in the Run Planning.
Organization		Organization name. It is informational and not used in planned run creation.
AllowedIndexStrategies		The index strategies supported by the kit. See AllowedIndexStrategies.
AdapterSequenceRead1		Adapter sequence for Read 1. Remove the line if it is not applicable.
AdapterSequenceRead2		Adapter sequence for Read 2. Remove the line if it is not applicable.
IndexSequences	i7Index1	A section of Index1 sequences. See IndexSequences.
IndexSequences	i7Index2	A section of Index2 sequences. See IndexSequences.
Settings	DefaultIndexStrategy	The default index strategy. It should be one of the strategy defined in the AllowedIndexStrategies.
Settings	FixedLayout	Indicates if the kit has a fixed-layout (true) or not (false). See example 3.
Settings	Multiplate	Indicates if a fixed-layout kit is single-plate (false) or multi-plate (true). See example 4, example 6.
Settings	FixedIndexPositions	A section containing mappings of well position to index names. It is only applicable for a fixed-layout kit. See Settings - FixedIndexPositions.
Settings	AllowVariableLengthIndexSequences	Indicates if the kit can have index sequences with different lengths. See Settings - AllowVariableLengthIndexSequences
Settings	EnableCustomIndexCycles	Indicates if the kit uses a custom Override Cycles. See OverrideCycles.
Settings	OverrideCycles	The custom pattern for the Override Cycles. See OverrideCycles.
Settings	NumCyclesIndex1Override	Used to override the default Index1 cycles. See OverrideCycles.
Settings	NumCyclesIndex2Override	Used to override the default Index2 cycles. See OverrideCycles.
Settings	CustomBclConvertSettings	A section of custom BCL Convert settings. See Settings - CustomBclConvertSettings.

AllowedIndexStrategies

The supported values are "Dual", "Single", and "NoIndex". Create a list below this setting. Each list item should be preceded with a dash (-) character and enclosed in double quotes. Use two spaces for indentation. See Example 1.

Example 1: Defining AllowedIndexStrategies for a kit that support single-index and dual-index, with dual-index as the default.

AllowedIndexStrategies:
  - "Dual"
  - "Single"
Settings:
  DefaultIndexStrategy: "Dual"

IndexSequences

• i7Index1 Create a list of Index1 sequences below this setting. Each index should be in the format of IndexName: "IndexSequence". See example 2.
• i5Index2 Create a list of Index2 sequences below this setting. Each index should be in the format of IndexName: "IndexSequence". See example 2.

Example 2: Defining Index1 and Index2 sequences.

IndexSequences: #Enter index sequences for both Index1 and Index2
  i7Index1: #Index1
    D701: "ATTACTCG" #<IndexName>: <IndexSequence>
    D702: "TCCGGAGA"
    D703: "CGCTCATT"
  i5Index2: #Index2
    D501: "TATAGCCT" #<IndexName>: <IndexSequence>
    D502: "ATAGAGGC"
    D503: "CCTATCCT"

Example 3: Settings for non-fixed-layout kit (FixedIndexPositions is not defined).

IndexSequences: #Enter index sequences for both Index1 and Index2
  i7Index1: #Index1
    D701: "ATTACTCG" #<IndexName>: <IndexSequence>
    D702: "TCCGGAGA"
    D703: "CGCTCATT"
  i5Index2: #Index2
    D501: "TATAGCCT" #<IndexName>: <IndexSequence>
    D502: "ATAGAGGC"
    D503: "CCTATCCT"
# Settings for non-fixed-layout kit with dual-index
Settings:
  FixedLayout: false
  Multiplate: false

Settings - FixedIndexPositions

The mapping should be defined in the format of "WellPosition/Index1Name-Index2Name" or "Plate-WellPosition/Index1Name-Index2Name". The allowed well positions are A01 - H12. If the kit requires well positions defined in different format, define FixedLayoutPositionKeyByIndexId: true. See example 4, example 5, example 6.

Example 4: Settings for single-plate fixed-layout kit (Note that WellPositions are in the A01 - H12 range).

# Settings for fixed-layout kit with single plate
Settings:
  FixedLayout: true
  Multiplate: false
  FixedIndexPositions: #Format: '- "WellPosition/Index1Name-Index2Name"'
    - "A01/D701-D501"
    - "B01/D702-D502"
    - "H01/D703-D503"
    - "H12/D704-D504"

Example 5: Settings for single-plate fixed-layout kit (Note that FixedLayoutPositionKeyByIndexId is true because WellPositions do not follow A01 - H12 format).

# Settings for single-plate fixed-layout kit, where well positions do not follow A01 - H12 format.
Settings:
  FixedLayout: true
  Multiplate: false
  FixedLayoutPositionKeyByIndexId: true
  FixedIndexPositions: #Format: '- "WellPosition/Index1Name-Index2Name"'
    - "UDP0001/UDP0001-UDP0001"
    - "UDP0002/UDP0002-UDP0002"

Example 6: Settings for multi-plate fixed-layout kit.

# Settings for multi-plate fixed-layout kit 
Settings:
  FixedLayout: true
  Multiplate: true
  FixedIndexPositions: #Format: '- "Plate-WellPosition/Index1Name-Index2Name"'
    - "A-A01/D701-D501"
    - "C-B01/D703-D502"

Settings - AllowVariableLengthIndexSequences

The value is true or false. However, the usage is currently restricted to Instrument Platforms which allow multi-configuration. As each configuration only allows one Override Cycles, when setting up a run, samples with different index lengths should be separated into different configurations.

Override Cycles

• EnableCustomIndexCycles

  • The value is true or false. If the setting is set to false or if the setting is not defined, the Override Cycles used is Y;I;I;Y pattern.

• NumCyclesIndex1Override The value should be a numeric value. If this setting is not defined, the number of Index1 cycles follows the number of bases in the Index1 sequences.

• NumCyclesIndex2Override The value should be a numeric value. If this setting is not defined, the number of Index2 cycles follows the number of bases in the Index2 sequences. See example 7.
• OverrideCycles

  • The value should be defined in this format: "Y{{Read1Length}};I{{Index1Length}};I{{Index2Length}};Y{{Read2Length}}?", where:

    • {{Read1Length}} is the number of cycles for Read1,

    • {{Read2Length}} is the number of cycles for Read2,

    • {{Index1Length}} is the number of cycles for Index1, and

    • {{Index2Length}} is the number of cycles for Index2.

  • If UMI is used, update the pattern accordingly.

    • E.g. if Read1 and Read2 cycles include 7 UMI cycles and 1 skipped-cycle: U7N1Y{{Read1Length-8}};I{{Index1Length}};I{{Index2Length}};U7N1Y{{Read2Length-8}}?"

    • E.g. if the kit is a single index kit, with UMI cycles instead of Index2: "Y50N{{Read1Length-50}};I8N{{Index1Length-8}};N{{Index2Length-16}}U16;Y50N{{Read2Length-50}}?". See example 7.

Settings - CustomBclConvertSettings

This section contains custom BCL Convert settings. The settings will be included in the sample sheet generated by Run Planning.

• TrimUMI Indicates if the UMI should be excluded from fastq files. The value is "0" or "1". Set to "0" if BCL Convert should still output UMI cycles to fastq files. See example 8.
• CreateFastqForIndexReads Indicates if the UMI in Index cycles should be trimmed or not. The value is "0" or "1". Set to "1" if BCL Convert should still output UMI cycles in Index to fastq files. Note that TrimUMI should also be set to "0".

Example 7: Settings to override Index2 cycles and custom override cycles.

# Settings for non fixed-layout kit using single-index, with UMI in-place of Index2 :
# - NumCyclesIndex2Override is set to 16
# - Custom OverrideCycles is defined
# - CustomBclConvertSettings is defined so that fastq will be output for index reads.
IndexSequences:
  i7Index1:
    SI_NA_A1_1: "AAACGGCG"
    SI_NA_A1_2: "CCTACCAT"
    SI_NA_A1_3: "GGCGTTTC"
Settings:
  FixedLayout: false
  Multiplate: false
  EnableCustomIndexCycles: true
  NumCyclesIndex2Override: "16"
  OverrideCycles: "Y50N{{Read1Length-50}};I8N{{Index1Length-8}};N{{Index2Length-16}}U16;Y50N{{Read2Length-50}}?"
  CustomBclConvertSettings:
    TrimUMI: "0"
    CreateFastqForIndexReads: "1"

Example 8: Settings to disable TrimUMI, i.e. BCL Convert should output fastq files for UMI cycles.

# Settings for single-plate fixed-layout kit using dual-index, with UMI in Read1 :
# - Custom OverrideCycles is defined
# - CustomBclConvertSettings is defined so that fastq will be output for reads.
IndexSequences:
  i7Index1:
    SI_NT_A1: "ATTTACCGCA"
    SI_NT_A2: "TTGTCGTAGA"
    SI_NT_A3: "AGTCCTGCGG"
  i5Index2:
    SI_NT_A1: "GACAATAAAG"
    SI_NT_A2: "CAATGTAGCA"
    SI_NT_A3: "TGACACAAGT"
Settings:
  FixedLayout: true
  Multiplate: false
  FixedIndexPositions:
    - "A01/SI_NT_A1-SI_NT_A1"
    - "A02/SI_NT_A2-SI_NT_A2"
    - "A03/SI_NT_A3-SI_NT_A3"
  OverrideCycles: "U28N{{Read1Length-28}};I10N{{Index1Length-10}};N{{Index2Length-10}}I10;Y90N{{Read2Length-90}}?"
  CustomBclConvertSettings:
    TrimUMI: "0"

Configuring in tsv

Similar to yaml, three tsv templates are provided. Please note that currently .tsv file supports fewer custom kit settings (as compared to .yaml file).

1. Non-fixed Layout: for non-fixed layout kit where any index can be selected for any sample.

2. Fixed Layout - Single Plate: for fixed layout kit with single plate, where each well has a defined index combination.

3. Fixed Layout - Multi Plate: for fixed layout kit with multi-plate, where each well has a defined index combination.

A tsv file contains of three sections, namely [IndexKit], [Resources], [Indices], where each section contains rows of tab-separated values.

IndexKit Section

No	Field Name	Field Value
1	Name	Name of the kit. It is an internal name, which has to be unique within a domain.
2	DisplayName	Display name of the kit. It is used for the index kit display label in the Run Planning.
3	Description	Description of the kit. It is displayed below the index kit field when the kit is selected in the Run Planning.
4	IndexStrategy	The index strategies supported by the kit. See 4.1 - 4.7 for the supported values.
4.1		NoIndex: only allow No Index
4.2		SingleOnly: only allow Single Index
4.3		DualOnly: only allow Dual Indexes
4.4		NoAndSingle: allow No Index and Single Index; defaut is No Index
4.5		NoAndDual: allow No Index and Dual Indexes; default is No Index
4.6		SingleAndDual: allow Single Index and Dual Indexes; default is Single Index
4.7		All: allow No Index, Single Index and Dual Indexes; default is No Index

Resources Section

Each row in the Resources section consists of four columns: Name, Type, Format, and Value. It is used to define Adapter Read settings and the type of index kit (whether a fixed layout with single- or multi- plate or non fixed layout). In addition, the mappings of well positions and index names (only for a fixed layout kit) should be included in this section (see No 5 in the table below).

No	Name	Type	Format	Value
1	Adapter	Adapter	string	The Adapter sequence for Read 1.
2	AdapterRead2	AdapterRead2	string	The Adapter sequence for Read 2. Include this line only when applicable.
3	FixedLayout	FixedLayout	bool	Indicates if it is a fixed layout kit. Value is true or false.
4	Multiplate	Multiplate	bool	Indicates if it is a fixed layout kit with multi- or single- plate. Value is true or false.
5	{Well position name}	FixedIndexPosition	string	Index1 and Index2 names separated by a dash, e.g. D701-D501.

[Resources]
Name	Type	Format	Value
Adapter	Adapter	string	ACCTCCCCGTGA
AdapterRead2	AdapterRead2	string	ACCTCCCCGTGA
FixedLayout	FixedLayout	bool	true
Multiplate	Multiplate	bool	false
A01 FixedIndexPosition  string  D701-D501
B01 FixedIndexPosition  string  D702-D502

Indices Section

Index1 and Index2 sequences should be defined in this section. Each row consists of three columns: Name, Sequence, IndexReadNumber.

Name	Sequence	IndexReadNumber
{Index name}	{Index sequence}	Value is 1 (for Index1) or 2 (for Index2)

[Indices]
Name	Sequence	IndexReadNumber
D701	ATTACTCG	1
D702	TCCGGAGA	1

D501	TATAGCCT	2
D502	ATAGAGGC	2