# Custom Config Support

## Local App Setup

## Overview

This document describes how to use the **Custom Configuration Support** feature for the pipeline software. This feature allows users to customize a specific set of DRAGEN command-line options to override the default values pre-defined in the pipeline.

## Customization with `customConfig` and `customResourceDir`

Users can customize pipeline behavior and file inputs using:

* `--customConfig` : path to a **custom configuration file** listing customized parameter values.
* `--customResourceDir` : path to a **directory** containing custom resource files.

Both options should be used together if file-based overrides are required.

## Important note for using File Parameters

* For **file parameters** (parameters that require a file), users must specify **relative paths** in the `customConfig` file. The software will join `customResourceDir` and the relative path to form the full file path.
* Additionally, the value assigned to a **file parameter** must be enclosed in single quotes (`''`).

## Examples

### Command Line

```bash
run_Heme_WGS_TO_{version}.sh \
  --inputType bcl \
  --inputFolder /heme_input_bcl \
  --customConfig /path/heme_custom_param.config \
  --customResourceDir custom_resources_Heme_dir
```

### `heme_custom_param.config` Content

```bash
# custom parameters
vc_output_evidence_bam = false
qc_detect_contamination = true
aligner_clip_pe_overhang = 0

# custom reference files
vc_systematic_noise = '/snv/WGS_hg38_v1.0_systematic_noise.snv.bed.gz'
sv_systematic_noise = '/sv/WGS_FF_Heme_hg38_v1.0_systematic_noise.sv.bedpe.gz'
vc_somatic_hotspots = '/snv/somatic_hotspots_GRCh38.vcf.gz'
```

### `custom_resources_Heme_dir` Folder Structure

```
custom_resources_Heme/
├── snv
│   ├── WGS_hg38_v1.0_systematic_noise.snv.bed.gz
│   └── somatic_hotspots_GRCh38.vcf.gz
└── sv
    └── WGS_FF_Heme_hg38_v1.0_systematic_noise.sv.bedpe.gz
```

## `customConfig` Template (with default value)

```bash
#vc_systematic_noise = ''
#enable_map_align = true
#sv_systematic_noise = ''
#vc_output_evidence_bam = false
#qc_detect_contamination = true
#vc_somatic_hotspots = ''
#sv_somatic_ins_tandup_hotspot_regions_bed = ''
#cram_reference = ''
#aligner_clip_pe_overhang = 0
```

## Supported Parameters

| Display Name                           | Parameter Name                              | Component      | Allowed Values | Default Value | Optional |
| -------------------------------------- | ------------------------------------------- | -------------- | -------------- | ------------- | -------- |
| VC Systematic Noise File               | `vc_systematic_noise`                       | Variant Caller | file           | included      | Yes      |
| VC Somatic Hotspots File               | `vc_somatic_hotspots`                       | Variant Caller | file           | included      | Yes      |
| CRAM Input Reference Genome            | `cram_reference`                            | Mapper         | file           | included      | Yes      |
| Aligner Clip Paired End Reads Overhang | `aligner_clip_pe_overhang`                  | Mapper         | 0,1,2          | 0             | Yes      |
| Enable Map Align                       | `enable_map_align`                          | Mapper         | true / false   | true          | Yes      |
| SV Somatic Hotspot BED File            | `sv_somatic_ins_tandup_hotspot_regions_bed` | Structural VC  | file           | included      | Yes      |
| SV Systematic Noise File               | `sv_systematic_noise`                       | Structural VC  | file           | included      | Yes      |
| Output SNV Evidence BAM                | `vc_output_evidence_bam`                    | Debug          | true / false   | false         | Yes      |
| QC Detect Contamination                | `qc_detect_contamination`                   | QC             | true / false   | true          | Yes      |

***

> **ℹ️ Note:** For CRAM Input Reference Genome, a list of commonly-used human reference FASTA files can be downloaded from the Illumina support site: [Illumina DRAGEN Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html)