For an example, see the Michigan Genomics Initiative PheWeb. For a walk-through demo see here. If you have questions or comments, check out our Google Group.
If you use the PheWeb code base for your work, please cite our paper:
Gagliano Taliun, S.A., VandeHaar, P. et al. Exploring and visualizing large-scale genetic associations by using PheWeb. Nat Genet 52, 550โ552 (2020).
If any of these steps is incorrect, please open an issue on github and I'll see what I can do to improve things.
pip3 install pheweb
- If that doesn't work, follow the detailed install instructions.
-
mkdir ~/my-new-pheweb && cd ~/my-new-pheweb
- This directory will store all data for the pheweb your are building. All
pheweb ...
commands should be run in this directory. - You can put it wherever you want and name it whatever you want.
- This directory will store all data for the pheweb your are building. All
-
If you want to configure any options, make a file
config.py
in your data directory. Some options you can set are:-
hg_build_number
(int): either19
or38
. -
assoc_min_maf
(float): an association (between a phenotype and variant) will only be included if its MAF is greater than or equal to this value. (default:0
) -
cache
(string): a directory where files common to all datasets can be stored. (default:cache = "~/.pheweb/cache/"
) -
num_procs
(int or dict): the number of processes to use for parallel loading steps. You can also setnum_procs = {'qq':5, '*':30}
. (default: 2/3 of the number of cores on your machine)
-
You need one file for each phenotype, and there are some requirements:
- It needs a header row.
- Columns can be delimited by tabs, spaces, or commas.
- It needs a column for the reference allele (which must always match the reference genome that you specified with
hg_build_number
) and a column for the alternate allele. If you have aMARKER_ID
column like1:234_C/G
, that's okay too. If you have an allele1 and allele2, and sometimes one or the other is the reference, then you'll need to modify your files. - It can be gzipped if you want.
- Variants must be sorted by chromosome and position, with chromosomes in the order [1-22,X,Y,MT].
The file must have columns for:
column description | name | other allowed column names | allowed values |
---|---|---|---|
chromosome | chrom |
#chrom , chr |
1-22, X , Y , M , MT , chr1 , etc |
position | pos |
beg , begin , bp |
integer |
reference allele | ref |
reference |
must match reference genome |
alternate allele | alt |
alternate |
anything |
p-value | pval |
pvalue , p , p.value |
number in [0,1] |
You may also have columns for:
column description | name | other allowed column names | allowed values |
---|---|---|---|
minor allele frequency | maf |
number in (0,0.5] | |
allele frequency | af |
a1freq , frq |
number in (0,1) |
allele count | ac |
integer | |
effect size | beta |
number | |
standard error of effect size | sebeta |
se |
number |
odds ratio | or |
number | |
R2 | r2 |
number | |
number of samples | num_samples |
ns , n |
integer, must be the same for every variant in its phenotype |
number of controls | num_controls |
ns.ctrl , n_controls |
integer, must be the same for every variant in its phenotype |
number of cases | num_cases |
ns.case , n_cases |
integer, must be the same for every variant in its phenotype |
Column names are case-insensitive. If you used a different column name, set field_aliases = {"column_name": "field_name"}
in config.py
. For example, field_aliases = {'P_BOLT_LMM_INF': 'pval', 'NSAMPLES': 'num_samples'}
.
Any field can be null if it is one of ['', '.', 'NA', 'N/A', 'n/a', 'nan', '-nan', 'NaN', '-NaN', 'null', 'NULL']. If a required field is null, the variant gets dropped.
Inside of your data directory, you need a file named pheno-list.json
that looks like this:
[
{
"assoc_files": ["/home/peter/data/ear-length.gz"],
"phenocode": "ear-length"
},
{
"assoc_files": ["/home/peter/data/a1c.X.gz","/home/peter/a1c.autosomal.gz"],
"phenocode": "A1C"
}
]
phenocode
must only contain letters, numbers, or any of _-~
.
Each phenotype needs assoc_files
(a list of paths to association files) and phenocode
(a string representing your phenotype that is valid in a URL). If you want, you can also include:
phenostring
(string): a name for the phenotype. Shown in tables and tooltips and page headers.category
(string): groups together phenotypes in the PheWAS plot. Shown in tables and tooltips.num_cases
,num_controls
, and/ornum_samples
(number): if your input data only hasAC
orMAC
, this will be used to calculatedAF
orMAF
. Shown in tooltips. If your input data has correctly-named columns for these, the commandpheweb phenolist read-info-from-association-files
will add them into your existingpheno-list.json
.- anything else you want, but you'll have to modify templates to use it.
There are four ways to make a pheno-list.json
:
-
If you have a csv (or tsv, optionally gzipped) with a header that has exactly the right column names, just import it by running
pheweb phenolist import-phenolist "/path/to/my/pheno-list.csv"
.If you have multiple association files for each phenotype, you may put them all into a single column with
|
between them. For example, your filepheno-list.csv
might look like this:phenocode,assoc_files a1c,/home/peter/data/a1c.autosomal.gz|/home/peter/data/a1c.X.gz ear-length,/home/peter/data/ear-length.gz
-
If you have one association file per phenotype, you can use a shell-glob to get assoc-files. Suppose that your assocation files are at paths like:
/home/peter/data/a1c.autosomal.gz
/home/peter/data/ear-length.gz
Then you could run
pheweb phenolist glob-files "/home/peter/data/*.gz"
to getassoc-files
.To get
phenocodes
, you can use this command which will take the text after the last/
and before the next.
:pheweb phenolist extract-phenocode-from-filepath --simple
If that doesn't work, see
pheweb phenolist extract-phenocode-from-filepath -h
for how to use a regex capture group. -
If you have multiple association files for some phenotypes, you can follow the directions in 2 and then run
pheweb phenolist unique-phenocode
.For example, if your association files are at:
/home/peter/data/ear-length.gz
/home/peter/data/a1c.autosomal.gz
/home/peter/data/a1c.X.gz
then you can run:
pheweb phenolist glob-files "/home/peter/data/*.gz" pheweb phenolist extract-phenocode-from-filepath --simple pheweb phenolist unique-phenocode
-
If you want to do more advanced things, like merging in more information from another file, check out the tools in
pheweb phenolist --help
.
-
Run
pheweb process
.- To distribute jobs across a cluster, see instructions here.
-
If something breaks, read the error message.
- If you can understand the error message, modify your association or config files to avoid it, or drop the problematic phenotypes from
pheno-list.json
. Then re-runpheweb process
. - If the problem is something that PheWeb should support by default, open an issue on github or email me.
- If you can't understand the error message, open an issue on github or email me.
- If you can understand the error message, modify your association or config files to avoid it, or drop the problematic phenotypes from
Run pheweb serve --open
.
That command should either open a browser to your new PheWeb, or it should give you a URL that you can open in your browser to access your new PheWeb. If it doesn't, follow the directions for hosting a PheWeb and accessing it from your browser.
To run pheweb through systemd, see sample file here. To use Apache2 or Nginx, see instructions here. To require login via OAuth, see instructions here. To track page views with Google Analytics, see instructions here. To reduce storage use, see instructions here. To customize page contents, see instructions here.
PheWeb can display phenotype correlations generated by another tool.
To use this feature, set show_correlations = True
in config.py
and place the output of the rg pipeline as pheno-correlations.txt
in the same folder as pheno-list.json
.
To hide the button for downloading summary stats, add download_pheno_sumstats = "secret"
and SECRET_KEY = "random string here"
in config.py
. That will make a secret page (printed to the console when you start the server) to share summary stats.