Package: phenopy
phenopyphenopywas developed using Python 3.9 and functions to perform phenotype similarity scoring by semantic similarity.phenopyis a
lightweight but highly optimized command line tool and library to efficiently perform semantic similarity scoring on
generic entities with phenotype annotations from theHuman Phenotype Ontology (HPO).InstallationInstall using pip:pipinstallphenopyInstall from GitHub:gitclonehttps://github.com/GeneDx/phenopy.gitcdphenopy
pipxinstallpoetry
poetryinstallCommand Line Usagescorephenopyis primarily used as a command line tool. An entity, as described here, is presented as a sample, gene, or
disease, but could be any concept that warrants annotation of phenotype terms.Usephenopy scoreto perform semantic similarity scoring in various formats. Write the results of any command to file
using--output-file=/path/to/output_file.txtScore similarity of entities defined by the HPO terms from an input file against all the OMIM diseases in.phenopy/data/phenotype.hpoa. We provide a test input file in the repo. The default summarization method is to
use--summarization-method=BMWAwhich weighs each diseases' phenotypes by the frequency of a phenotype seen in
each particular disease.phenopyscoretests/data/test.score.txtOutput:#query	entity_id	score
118200  210100  0.0
118200  615779  0.0
118200  613266  0.0052
...Score similarity of entities defined by the HPO terms from an input file against all the OMIM diseases in.phenopy/data/phenotype.hpoa, to use the non-weighted summarization method use--summarization-method=BMAwhich
uses a traditionalbest-match averagesummarization of semantic similarity scores when comparing terms from recordawith terms from recordb.phenopyscoretests/data/test.score.txt--summarization-method=BMWAOutput:#query	entity_id	score
118200  210100  0.0
118200  615779  0.0
118200  613266  0.0052
...Score similarity of an entities defined by the HPO terms from an input file against a custom list of entities with HPO annotations, referred to as the--records-file. Both files are in the same format.phenopyscoretests/data/test.score-short.txt--records-filetests/data/test.score-long.txtOutput:#query  entity_id       score
118200  118200  0.0169
118200  300905  0.0156
118200  601098  0.0171
...Score pairwise similarity of entities defined by the HPO terms from an input file using--self.phenopyscoretests/data/test.score-long.txt--threads4--selfOutput:#query  entity_id       score
118200  118200  0.2284
118200  118210  0.1302
118200  118211  0.1302
118210  118210  0.2048
118210  118211  0.2048
118211  118211  0.2048Score age-adjusted pairwise similarity of entities defined in the input file,
using phenotype mean age and standard deviation defined in the--ages_distribution_file,
select best-match weighted average as the scoring summarization method--summarization-method BMWA.phenopyscoretests/data/test.score-short.txt--ages_distribution_filetests/data/phenotype_age.tsv--summarization-methodBMWA--threads4--selfOutput:#query  entity_id       score
118200  210100  0.0
118200  177650  0.0127
118200  241520  0.0
...The phenotype age file contains hpo-id, mean, sd as tab separated text as followsHP:00012516.03.0HP:00012631.01.0HP:00012901.01.0HP:000432210.03.0HP:00012496.03.0If no phenotype ages file is provided--summarization-method=BMWAcan be selected to use default, open access literature-derived phenotype ages (~ 1,400 age weighted phenotypes).phenopyscoretests/data/test.score-short.txt--summarization-methodBMWA--threads4ParametersFor a full list of command arguments usephenopy [subcommand] --help:phenopyscore--helpOutput:--output_file=OUTPUT_FILE
        File path where to store the results. [default: - (stdout)]
    --records_file=RECORDS_FILE
        An entity-to-phenotype annotation file in the same format as "input_file". This file, if provided, is used to score entries in the "input_file" against entries here. [default: None]
    --annotations_file=ANNOTATIONS_FILE
        An entity-to-phenotype annotation file in the same format as "input_file". This file, if provided, is used to add information content to the network. [default: None]
    --ages_distribution_file=AGES_DISTRIBUTION_FILE
        Phenotypes age summary stats file containing phenotype HPO id, mean_age, and std. [default: None]
    --self=SELF
        Score entries in the "input_file" against itself.
    --summarization_method=SUMMARIZATION_METHOD
        The method used to summarize the HRSS matrix. Supported Values are best match average (BMA), best match weighted average (BMWA), and maximum (maximum). [default: BMWA]
    --threads=THREADS
        Number of parallel processes to use. [default: 1]Library UsageThephenopylibrary can be used as aPythonmodule, allowing more control for advanced users.scoreGenerate the hpo network and supporting objects:importosfromphenopy.build_hpoimportgenerate_annotated_hpo_networkfromphenopy.scoreimportScorer# data directoryphenopy_data_directory=os.path.join(os.getenv('HOME'),'.phenopy/data')# files used in building the annotated HPO networkobo_file=os.path.join(phenopy_data_directory,'hp.obo')disease_to_phenotype_file=os.path.join(phenopy_data_directory,'phenotype.hpoa')# if you have a custom ages_distribution_file, you can set it here.ages_distribution_file=os.path.join(phenopy_data_directory,'xa_age_stats_oct052019.tsv')hpo_network,alt2prim,disease_records=\generate_annotated_hpo_network(obo_file,disease_to_phenotype_file,ages_distribution_file=ages_distribution_file)Then, instantiate theScorerclass and score hpo term lists.scorer=Scorer(hpo_network)terms_a=['HP:0001263','HP:0011839']terms_b=['HP:0001263','HP:0000252']print(scorer.score_term_sets_basic(terms_a,terms_b))Output:0.11213185474495047miscellaneousThe library can be used to prune parent phenotypes from thephenotype.hpoaand store pruned annotations as a filefromphenopy.utilimportexport_phenotype_hpoa_with_no_parents# saves a new file of phenotype disease annotations with parent HPO terms removed from phenotype lists.disease_to_phenotype_no_parents_file=os.path.join(phenopy_data_directory,'phenotype.noparents.hpoa')export_phenotype_hpoa_with_no_parents(disease_to_phenotype_file,disease_to_phenotype_no_parents_file,hpo_network)Initial setupphenopy is designed to run with minimal setup from the user, to run phenopy with default parameters (recommended), skip ahead
to theCommands overview.This section provides details about where phenopy stores data resources and config files. The following occurs when
you run phenopy for the first time.phenopy creates a.phenopy/directory in your home folder and downloads external resources from HPO into the$HOME/.phenopy/data/directory.phenopy creates a$HOME/.phenopy/phenopy.iniconfig file where users can set variables for phenopy to use
at runtime.ConfigWhile we recommend using the default settings for most users, the config filecan bemodified:$HOME/.phenopy/phenopy.ini.To run phenopy with a different version ofhp.obo, set the path ofobo_filein$HOME/.phenopy/phenopy.ini.ContributingWe welcome contributions from the community. Please follow these steps to setup a local development environment.pipenvinstall--devTo run tests locally:pipenvshell
coveragerun--source=.-munittestdiscover--start-directorytests/
coveragereport-mReferencesThe underlying algorithm which determines the semantic similarity for any two HPO terms is based on an implementation of HRSS,published here.Citing PhenopyPlease use the following Bibtex to cite this software.@software{arvai_phenopy_2019,
    title = {Phenopy},
    rights = {Attribution-NonCommercial-ShareAlike 4.0 International},
    url = {https://github.com/GeneDx/phenopy},
    abstract = {Phenopy is a Python package to perform phenotype similarity scoring by semantic similarity.
        Phenopy is a lightweight but highly optimized command line tool and library to efficiently perform semantic
        similarity scoring on generic entities with phenotype annotations from the Human Phenotype Ontology (HPO).},
    version = {0.3.0},
    author = {Arvai, Kevin and Borroto, Carlos and Gainullin, Vladimir and Retterer, Kyle},
    date = {2019-11-05},
    year = {2019},
    doi = {10.5281/zenodo.3529569}
}