SCOARY(1)

🌸 NAME 🌸

okay bestie, welcome to the scoary manual page — this is section 1 of User Commands, and it's pangenome-wide association studies 💖 periodt.

🦋 SYNOPSIS 🦋

scoary [-h] [-t TRAITS] [-g GENES] [-n NEWICKTREE] [-s START_COL]
[--delimiter DELIMITER] [-r RESTRICT_TO] [-o OUTDIR] [-u] [-p
P_VALUE_CUTOFF [P_VALUE_CUTOFF ...]]  [-c [{I,B,BH,PW,EPW,P}
[{I,B,BH,PW,EPW,P} ...]]] [-m MAX_HITS] [--include_input_columns
GRABCOLS] [-w] [--no-time] [-e PERMUTE] [--no_pairwise] [--collapse]
[--threads THREADS] [--test] [--citation] [--version]

✨ OPTIONS ✨

🎀 optional arguments:

• -h, --help — pops up this help message and then dips. that's it, that's the whole thing 💅

🧬 Input options:

• -t TRAITS, --traits TRAITS — your input trait table, in comma-separated-values format. trait presence is marked with 1, trait absence with 0. it assumes strain names live in the first column and trait names live in the first row, bestie, no negotiation 🌸
• -g GENES, --genes GENES — the input gene presence/absence table (comma-separated values), coming straight from ROARY. the strain names must match the ones in the trait table, fr fr 👑
• -n NEWICKTREE, --newicktree NEWICKTREE — hand it a custom tree (Newick format) for the phylogenetic analyses instead of letting it calculate one internally. yes, you get to be the main character here 🦋
• -s START_COL, --start_col START_COL — tells it which column in the gene presence/absence file is where the individual strain info actually starts. Default = 15. (and it's 1-based indexing, iykyk) 🔢
• --delimiter DELIMITER — the delimiter between cells in the gene presence/absence file, the trait file, and the output file. one delimiter to rule them all ✨
• -r RESTRICT_TO, --restrict_to RESTRICT_TO — use this when you only wanna analyze a subset of your strains. Scoary reads the comma-separated table of strains you give it and restricts all the analyses to just those. choose your fighters 🫶

💾 Output options:

• -o OUTDIR, --outdir OUTDIR — the directory where output files get dropped. Default = . 📁
• -u, --upgma_tree — this flag makes Scoary write the calculated UPGMA tree out to a newick file. tree reveal moment 🌳
• -p P_VALUE_CUTOFF [P_VALUE_CUTOFF ...], --p_value_cutoff P_VALUE_CUTOFF [P_VALUE_CUTOFF ...] — the p-value cut-off, aka the alpha level. for the Fishers, Bonferronis and Benjamini-Hochbergs tests, SCOARY simply won't report genes with p-values higher than this. for empirical p-values tho, it gets treated as an alpha level instead — so 0.02 will filter out all genes except the lower and upper percentile from that test. run it with "-p 1.0" to report all the genes. it accepts standard form (e.g. 1E-8). you can provide a single value (applied to everything) or exactly as many values as correction criteria, in corresponding order. (peep the example under correction 👀) Default = 0.05
• -c [{I,B,BH,PW,EPW,P} [{I,B,BH,PW,EPW,P} ...]], --correction [{I,B,BH,PW,EPW,P} [{I,B,BH,PW,EPW,P} ...]] — applies the indicated filtration measure. allowed values are I, B, BH, PW, EPW, P, and here's the tea on each one:
  • I = Individual (naive) p-value
  • B = Bonferroni adjusted p-value
  • BH = BenjaminiHochberg adjusted p
  • PW = Best (lowest) pairwise comparison
  • EPW = Entire range of pairwise comparison p-values
  • P = Empirical p-value from permutations

you can enter as many correction criteria as you want, and they get associated with the p_value_cutoffs you enter. like, "-c I EPW -p 0.1 0.05" applies these cutoffs: the naive p-value has to be lower than 0.1 AND the entire range of pairwise comparison values must be below 0.05 for that gene. ngl, note that empirical p-values should be interpreted at both tails — so running "-c P -p 0.05" applies an alpha of 0.05 to the empirical (permuted) p-values, i.e. it filters everything except the upper and lower 2.5 percent of the distribution. Default = Individual p-value. (I) 💀

• -m MAX_HITS, --max_hits MAX_HITS — maximum number of hits to report. SCOARY will only report the top max_hits results per trait. keeping it cute and concise 🎀
• --include_input_columns GRABCOLS — grabs columns from the input Roary file and puts them in the output. handles commas and ranges, e.g. --include_input_columns 4,6,8,16-23. the special keyword ALL will include all relevant input columns in the output. shopping spree 🛍️
• -w, --write_reduced — use this with -r if you want Scoary to create a brand new gene presence absence file from your reduced set of isolates. > heads up bestie: columns 1-14 (No. sequences, Avg group size nuc etc) in this file do not reflect the reduced dataset — those get taken from the full dataset. not me warning you twice 🙈
• --no-time — outputs the file as TRAIT.results.csv instead of TRAIT_TIMESTAMP.csv. and when you use it with the -w argument, it outputs a reduced gene matrix as gene_presence_absence_reduced.csv rather than gene_presence_absence_reduced_TIMESTAMP.csv. no timestamps, no stress ⭐

🔬 Analysis options:

• -e PERMUTE, --permute PERMUTE — performs N number of permutations of the significant results post-analysis. each permutation does a label switching of the phenotype and a new p-value gets calculated according to this new dataset. after all N permutations are done, the results are ordered in ascending order, and the percentile of the original result in the permuted p-value distribution is reported. literally a whole glow-up arc for your p-values 🔥
• --no_pairwise — do not perform pairwise comparisons. in this mode, Scoary performs population structure-naive calculations only (Fishers test, ORs etc). useful for summary operations and exploring sets (genes unique in groups, intersections etc) but not for causal analyses, okay? 👀
• --collapse — add this to collapse correlated genes (genes that have identical distribution patterns in the sample) into merged units. twinning fr fr 👯

🌈 Misc options:

• --threads THREADS — number of threads to use. Default = 1 🧵
• --test — runs Scoary on the test set in exampledata, overriding all other parameters. it does not care what else you typed, bestie 💅
• --citation — shows citation information, and exits. give credit where it's due 🫶
• --version — displays the Scoary version, and exits. ✨

by Ola Brynildsrud (olbb@fhi.no) 💜

👑 AUTHOR 👑

this manpage was written by Andreas Tille for the Debian distribution, and it can be used for any other usage of the program. iconic behavior, we love a flexible license 🎀

and that's the whole vibe check, bestie — this was scoary version 1.6.16, dated January 2019, signing off from the SCOARY(1) manual. slay, go run some associations, and remember: the facts stay, the energy stays higher 💖✨🦋