Skip to content

usage_cladebreaker_off.md

Latest commit

 

History

History
176 lines (141 loc) · 9.62 KB

usage_cladebreaker_off.md

File metadata and controls

176 lines (141 loc) · 9.62 KB
Raw

THRESHER - Cladebreaker Off: Re-identify Strain Composition without Cladebreaker Corrections

thresher cladebreaker-off -h

options:
  -h, --help            show this help message and exit
  --thresher_output THRESHER_OUTPUT
                        Path to the existing THRESHER directory.
                                The existing analysis directory should contain the previous analysis results.
  --output OUTPUT       Path to output directory.
                                If not provided, defaults to thresher_cladebreaker_off_<YYYY_MM_DD_HHMMSS> under the current working directory.
  --threshold_floor THRESHOLD_FLOOR
                        The floor of the range of SNP distances to search for the optimal phylothreshold.
                        Default is 5.
  --threshold_ceiling THRESHOLD_CEILING
                        The ceiling of the range of SNP distances to search for the optimal phylothreshold.
                        Default is 500.
  --singleton_threshold SINGLETON_THRESHOLD
                        The SNP distance threshold above which every genome in the group is considered a singleton.
                        Default is 100.
  --plateau_length PLATEAU_LENGTH
                        The plateau length for the plateau endpoint method. Default is 15.
  --correction_bootstrap CORRECTION_BOOTSTRAP
                        Minimum bootstrap support threshold for applying phylogenetic corrections to strain composition (default: 0).
  -t THREADS, --threads THREADS
                        Thread number. Default is 1.
  --prefix PREFIX       Prefix for config files. If not provided, defaults to timestamp: YYYY_MM_DD_HHMMSS
  --conda_prefix CONDA_PREFIX
                        Directory for conda environments needed for this analysis. If not provided, defaults to OUTPUT/conda_envs_<YYYY_MM_DD_HHMMSS>

Required Input

  1. Existing THRESHER Output Directory(--thresher_output):

    Path to the existing THRESHER directory containing previous analysis results.

Optional Input

  1. Threshold Floor(--threshold_floor):

    The floor of the range of SNP distances to search for the optimal phylothreshold. Default is 5.

  2. Threshold Ceiling(--threshold_ceiling):

    The ceiling of the range of SNP distances to search for the optimal phylothreshold. Default is 500.

  3. Singleton Threshold(--singleton_threshold):

    The SNP distance threshold above which every genome in the group is considered a singleton. Default is 100.

  4. Plateau Length(--plateau_length):

    The plateau length for the plateau endpoint method. Default is 15.

  5. Output Directory(--output):

    Path to the output directory. If not provided, defaults to thresher_cladebreaker_off_<YYYY_MM_DD_HHMMSS> under the current working directory.

  6. Prefix(--prefix):

    Prefix for config files. If not provided, defaults to timestamp: YYYY_MM_DD_HHMMSS.

  7. Conda Environment Directory(--conda_prefix):

    Directory for conda environments needed for this analysis. If not provided, defaults to OUTPUT/conda_envs. You can reuse the conda environments from previous THRESHER runs to save time and disk space.

Output

  1. New Strain Compositions: The new strain composition files generated by all 4 endpoint methods contain the following columns:

    1. strain_id : Strain ID assigned by Thresher using the specified endpoint method.
    2. genome : Genome name.
    • Plateau strains:
      • thresher/output/plateau_strains.RDS
      • thresher/output/plateau_strains.csv
    • Peak strains:
      • thresher/output/peak_strains.RDS
      • thresher/output/peak_strains.csv
    • Discrepancy strains:
      • thresher/output/discrepancy_strains.RDS
      • thresher/output/discrepancy_strains.csv
    • Public strains:
      • thresher/output/public_strains.RDS
      • thresher/output/public_strains.csv
    • Group-specific thresholds:
      • Plateau thresholds: thresher/output/group_plateau.csv
        • Columns included in the group-specific thresholds csv files:
        • group: Hierarchical clustering group ID
        • plateau: Phylothreshold determined for the group using the plateau endpoint method.
        • plateau_length: Plateau length used for determining the phylothreshold.
      • Peak thresholds: thresher/output/group_peak.csv
        • Columns included in the group-specific thresholds csv files:
        • group: Hierarchical clustering group ID
        • peak: Phylothreshold determined for the group using the peak endpoint method.
      • Discrepancy thresholds: thresher/output/group_discrepancy.csv
        • Columns included in the group-specific thresholds csv files:
        • group: Hierarchical clustering group ID
        • discrepancy: Phylothreshold determined for the group using the discrepancy endpoint method.
      • Public thresholds: thresher/output/group_public.csv
        • Columns included in the group-specific thresholds csv files:
        • group: Hierarchical clustering group ID
        • public: Phylothreshold determined for the group using the public endpoint method.

  2. Sanity Check Plots:

  • Plateau: thresher/output/QC/plateau_qc_plot.pdf
  • Peak: thresher/output/QC/peak_qc_plot.pdf
  • Public: thresher/output/QC/public_qc_plot.pdf
  • Discrepancy: thresher/output/QC/discrepancy_qc_plot.pdf
  • Figure descriptions:

    • X-axis: Phylogenetic Average Distance

      The average phylogenetic distance between two strains, calculated by averaging the pairwise branch-length distances between all genomes in strain A and all genomes in strain B on the core genome phylogeny.

    • Y-axis: gSNP Average Distance

      The average SNP distance between two strains, calculated by averaging the pairwise SNP distances between all genomes in strain A and all genomes in strain B. Pairwise SNP distances are computed using MUMmer4.

    • Colored dots: Each dot represents a comparison between two strains. Blue dots indicate strain pairs within the same hierarchical clustering group. Red dots indicate strain pairs from different hierarchical clustering groups.

    • Doted line: A vertical dotted line at gSNP distance of 100.

  1. Sanity Check Tables:

    All csv files contain the following columns:

    1. subject: subject strain ID
    2. query: query strain ID
    3. snp_average_distance: average SNP distance between the subject and query strains
    4. phylogeny_average_distance: average phylogenetic distance between the subject and query strains
    5. same_group: whether the subject and query strains belong to the same hierarchical clustering group
    • Plateau: thresher/output/QC/plateau_qc_table.csv
    • Peak: thresher/output/QC/peak_qc_table.csv
    • Public: thresher/output/QC/public_qc_table.csv
    • Discrepancy: thresher/output/QC/discrepancy_qc_table.csv

  2. Multi-SNP-Threshold Plot:

  • thresher/output/MSTP/{Group_ID}_MSTP.pdf
  • Figure descriptions:

    • Shared X-axis: SNP Threshold tested

      The SNP thresholds tested to define strains.

    • Upper panel: The median and mean bootstrap values of the clades containing the strains defined at the SNP threshold.

    • Lower panel:

      • Lines: The number of singletons, clones, and the discrepant genomes when the strain compositions determined by pairwise SNP distances mapped to the corresponding reference-based phylogenetic tree of the group.
      • Annotations: The final phylothresholds determined by each endpoint method (plateau, peak, discrepancy, public) are indicated on the plot.

  1. Strain Composition Visualizations:

    Strain compositions visualized with ML Phylogeny and SNP distance Heatmap of each hirarchical group for four endpoint methods:

    • RDS files:
      • Plateau: plots/strain_compositions/plateau/plateau_strain_tree_snp.RDS
      • Peak: plots/strain_compositions/peak/peak_strain_tree_snp.RDS
      • Discrepancy: plots/strain_compositions/discrepancy/discrepancy_strain_tree_snp.RDS
      • Public: plots/strain_compositions/public/public_strain_tree_snp.RDS
    • PDF files:
      • Plateau: plots/strain_compositions/plateau/Group{Group_ID}_plateau_strain_composition.pdf
      • Peak: plots/strain_compositions/peak/Group{Group_ID}_peak_strain_composition.pdf
      • Discrepancy: plots/strain_compositions/discrepancy/Group{Group_ID}_discrepancy_strain_composition.pdf
      • Public: plots/strain_compositions/public/Group{Group_ID}_public_strain_composition.pdf
    • Figure descriptions:
      • ML Phylogeny (left panel)
        • Midpoint-rooted ML tree of the group
        • Tip points: Blue circles = study genomes, Brown circles = public genomes (CladeBreaker)
        • Highlighted clades: Genomes assigned to the same clone (strain with ≥2 genomes) are highlighted with a green rectangle and labeled with their strain ID (e.g., 1_1)
        • Scale bar: Branch length in substitutions per site
        • Optimal Phylothreshold: The optimal phylothreshold determined by the selected endpoint method displayed at the top
      • SNP Distance Heatmap (right panel)
        • Rows aligned to phylogeny tip labels; columns show study genomes only
        • White to blue gradient: Pairwise SNP distances between study genomes
        • Grey cells: Comparisons of study genomes to corresponding top public genomes. The color of these cells are greyed out. The cells with no values indicate this study genome is not compared to the public genome(s) as the public genome(s) is/are not the top hit for this study genome in WhatsGNU analysis.
        • Text color indicates SNP quality:
          • Green = good quality (alignments meet coverage threshold)
          • Red = poor quality (low-coverage alignments, interpret with caution)