# 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](#details_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](#details_indexsequences).                                                                                                    |
| IndexSequences         | i7Index2                          | A section of Index2 sequences. See [IndexSequences](#details_indexsequences).                                                                                                    |
| Settings               | DefaultIndexStrategy              | The default index strategy. It should be one of the strategy defined in the [AllowedIndexStrategies](#details_allowedindexstrategies).                                           |
| Settings               | FixedLayout                       | Indicates if the kit has a fixed-layout (`true`) or not (`false`). See [example 3](#ex_nonfixedlayout).                                                                          |
| Settings               | Multiplate                        | Indicates if a fixed-layout kit is single-plate (`false`) or multi-plate (`true`). See [example 4](#ex_singleplate_wellposition), [example 6](#ex_multiplate_wellposition).      |
| Settings               | FixedIndexPositions               | A section containing mappings of well position to index names. It is only applicable for a fixed-layout kit. See [Settings - FixedIndexPositions](#details_fixedindexpositions). |
| Settings               | AllowVariableLengthIndexSequences | Indicates if the kit can have index sequences with different lengths. See [Settings - AllowVariableLengthIndexSequences](#details_allowvariableindexlength)                      |
| Settings               | EnableCustomIndexCycles           | Indicates if the kit uses a custom Override Cycles. See [OverrideCycles](#details_overridecycles).                                                                               |
| Settings               | OverrideCycles                    | The custom pattern for the Override Cycles. See [OverrideCycles](#details_overridecycles).                                                                                       |
| Settings               | NumCyclesIndex1Override           | Used to override the default Index1 cycles. See [OverrideCycles](#details_overridecycles).                                                                                       |
| Settings               | NumCyclesIndex2Override           | Used to override the default Index2 cycles. See [OverrideCycles](#details_overridecycles).                                                                                       |
| Settings               | CustomBclConvertSettings          | A section of custom BCL Convert settings. See [Settings - CustomBclConvertSettings](#details_custombclconvertsettings).                                                          |

#### AllowedIndexStrategies <a href="#details_allowedindexstrategies" id="details_allowedindexstrategies"></a>

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](#ex_allowedindexstrategies).

#### Example 1: Defining AllowedIndexStrategies for a kit that support single-index and dual-index, with dual-index as the default. <a href="#ex_allowedindexstrategies" id="ex_allowedindexstrategies"></a>

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

#### IndexSequences <a href="#details_indexsequences" id="details_indexsequences"></a>

* `i7Index1` Create a list of Index1 sequences below this setting. Each index should be in the format of `IndexName: "IndexSequence"`. See [example 2](#ex_indexsequences).
* `i5Index2` Create a list of Index2 sequences below this setting. Each index should be in the format of `IndexName: "IndexSequence"`. See [example 2](#ex_indexsequences).

#### Example 2: Defining Index1 and Index2 sequences. <a href="#ex_indexsequences" id="ex_indexsequences"></a>

```
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). <a href="#ex_nonfixedlayout" id="ex_nonfixedlayout"></a>

```
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 <a href="#details_fixedindexpositions" id="details_fixedindexpositions"></a>

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](#ex_singleplate_wellposition), [example 5](#ex_singleplate_indexname), [example 6](#ex_multiplate_wellposition).

#### Example 4: Settings for single-plate fixed-layout kit (Note that WellPositions are in the A01 - H12 range). <a href="#ex_singleplate_wellposition" id="ex_singleplate_wellposition"></a>

```
# 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). <a href="#ex_singleplate_indexname" id="ex_singleplate_indexname"></a>

```
# 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. <a href="#ex_multiplate_wellposition" id="ex_multiplate_wellposition"></a>

```
# 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 <a href="#details_allowvariableindexlength" id="details_allowvariableindexlength"></a>

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 <a href="#details_overridecycles" id="details_overridecycles"></a>

* `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](#ex_customcycles_index2withumi).
* `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](#ex_customcycles_index2withumi).

#### Settings - CustomBclConvertSettings <a href="#details_custombclconvertsettings" id="details_custombclconvertsettings"></a>

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](#ex_trimumi).
* `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. <a href="#ex_customcycles_index2withumi" id="ex_customcycles_index2withumi"></a>

```
# 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. <a href="#ex_trimumi" id="ex_trimumi"></a>

```
# 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
```