metaclonotypist 1.0.1

Output file: volcano_plot*.png

This PNG file displays a volcano plot summarizing the results of the cluster-HLA association analysis. Each point on the plot represents a specific cluster-HLA allele combination, with the x-axis showing the log-transformed odds ratio and the y-axis showing the negative log10 p-value for the association. Cluster-HLA pairs with strong associations appear further from the origin. Colour indicates associations judged to be statistically significant following false discovery rate control. Infinite odds ratios (arising from perfect separation) are plotted at a large fixed value to ensure they are visible on the plot.

As a control the second panel shows the same analysis on data where the donor metadata was shuffled.

Output file: cluster_associations.csv

This CSV file contains the results of the cluster-HLA association analysis. The columns are:

• cluster: Identifier for the TCR cluster (metaclone).
• hla: HLA allele tested for association.
• count_cluster: Number of individuals within the cluster that have the specified HLA allele.
• total_cluster: Total number of individuals in the cluster.
• count_other: Number of individuals not part of the cluster with the specified HLA allele.
• total_other: Total number of individuals not part of the cluster.
• pvalue: P-value from the statistical test assessing the association between the cluster and the HLA allele.
• odds_ratio: Odds ratio quantifying the strength of the association between the cluster and the HLA allele.

Output file: clustering*.csv

This CSV file contains the mapping of TCRs to identified metaclones (clusters). The columns are:

• index: Unique identifier for each TCR sequence in the input data.
• cluster: Identifier for the metaclone (cluster) to which the TCR has been assigned.

Each row represents a TCR and the cluster it belongs to, allowing users to trace which TCRs are grouped together as metaclones.

Output file: stats.csv

This CSV file provides summary statistics and parameter values used in the analysis. The columns are:

• parameter: Name of the parameter or statistic.
• value: The corresponding value for the parameter or statistic.

Each row reports a specific parameter setting or summary metric, allowing users to track the configuration and results of their analysis.

Input file: tcrdata.csv

This CSV file contains TCR sequence data for each sample. The columns are:

• TRBV: The TCR beta variable gene segment (e.g., TRBV20-1).
• TRBJ: The TCR beta joining gene segment (e.g., TRBJ2-7).
• CDR3B: The amino acid sequence of the TCR beta chain CDR3 region.
• Sample.ID: Identifier for the sample or donor from which the TCR was derived.
• clonal_count: The number of times this TCR sequence was observed in the sample (clone count).

Each row represents a unique TCR sequence observed in a particular sample, along with its gene usage and abundance.

For alpha chain analysis please supply the argument --chain alpha to metaclonotypist, and replace B with A in the above, e.g. TRBV -> TRAV.

Input file: metadata.csv

This CSV file contains metadata for each sample (typically HLA genotypes). The columns are:

• Sample.ID: Identifier for the sample or donor (must match the Sample.ID in the TCR data).
• HLA columns: Each subsequent column represents a specific HLA allele for a given gene and copy (e.g., DPA1.1, DPA1.2, B.1, B.2, DPB1.1, DPB1.2, A.1, A.2, C.1, C.2, DRB1.1, DRB1.2, DQAB1, DQAB2, DQAB3, DQAB4). These columns record the HLA alleles present in each individual for the corresponding gene and copy.

Each row corresponds to a single donor, listing their HLA alleles for each locus. The HLA columns may vary depending on the typing resolution and available data, but should be consistent across all samples. Where an individual is homozygous at a particular locus, the same allele name can be repeated twice or one of the alleles can be left blank.

Note: This metadata file could also contain other donor characteristics that might be differentially associated with metaclone presence in the repertoire. We have only used the pipeline so far to test for HLA association, but it is very much possible using this same setup to test for other associations (e.g., disease status).

usage: metaclonotypist [-h] --tcrpath TCRPATH --hlapath HLAPATH -o OUTPUT_DIR [--chain {alpha,beta}] [--tcrdistmethod {tcrdist,sceptr}] [--mincount MINCOUNT] [--maxtcrdist MAXTCRDIST]
                       [--clustering {leiden,multilevel}] [--hlatest {fisher,agresti-caffo}] [--mindonors MINDONORS] [--maxedits MAXEDITS] [--version]

options:
  -h, --help            show this help message and exit
  --tcrpath TCRPATH     Path to input TCR data (CSV file)
  --hlapath HLAPATH     Path to input HLA metadata (CSV file)
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        Path to the output directory
  --chain {alpha,beta}  chain to use (default: beta)
  --tcrdistmethod {tcrdist,sceptr}
                        TCR distance method (default: tcrdist)
  --mincount MINCOUNT   Minimum count for clones (default: None, no filtering)
  --maxtcrdist MAXTCRDIST
                        Maximum TCR distance (default: 15)
  --clustering {leiden,multilevel}
                        Clustering algorithm (default: leiden)
  --hlatest {fisher,agresti-caffo}
                        Statistical test method for HLA association (default: fisher)
  --mindonors MINDONORS
                        Minimum number of donors for HLA filtering (default: 4)
  --maxedits MAXEDITS   Maximum edits for TCR distance (default: 2)
  --version             Show the version of Metaclonotypist