Package: ontoloviz
OntoloViz is a user-friendly interface that enables the creation of interactive sunburst plots for 
    biomedical ontologies. It allows you to conveniently visualize your data for reports or share the 
    generated plots with collaborators. Check out theexamples sectionto download interactive .html examples and to gain a better understanding of the package's capabilities.QuickstartThe GUI can be run by downloading the latestreleaseor by installing the package via PyPi (OS independent, requiresPython 3.8+):pip install ontolovizAfter the installation you can run the GUI from the command line with the following command:ontolovizUsageThe application allows importing.tsvand.xlsxfiles, but the use of.tsvandtabas a
separator is recommended. The GUI can create two types of sunburst diagrams to represent either phenotype or drug
ontologies, which is determined by the structure of the loaded files. Any numbers entered in the input file will be converted
to integers and decimal points will be rounded.GUI OptionsLoad File: load an.tsvor.xlsxfile containing ontology data based below defined file formatsLoad from Web: load an.oboontology from a pre-defined list, or define a URL to any ontologyGeneral optionsSet Color Scale: define a custom color scale for the sunburst color scaling when color propagation is activeSet Border: configures the border properties drawn around sunburst wedgesDrop empty nodes(phenotype sunburst only): drops nodes who have no further children and 0 countsWedge Width(drug sunburst only): switch from full outer circle (total) to count-based wedge widths (remainder)Display Labels: controls display of labels inside sunburst wedges, available options:allpropagationdrugs(drug sunburst only)noneLegend: displays a weighted color bar (disabled for summary plots with specific color propagation enabled)Propagation optionsEnable: enables count- and color propagation from child to parent nodesColor: controls color propagation by the options:off: color scale is based on 'Color' column from imported filespecific: color scale is based on the maximum values of the corresponding subtreeglobal: color scale is based on the maximum values of the entire tree ontologyphenotype(phenotype sunburst only): Only the most outer phenotype in a branch is coloredCounts: controls count propagation by the options:off: no counts are propagated, counts equal imported valueslevel: counts are propagated up to defined level, values above threshold remain unchangedall: counts are propagated up to central node, imported values are corrected and overwrittenLevel: controls color- and count-propagation from outer to inner levels up to defined levelaffects color propagation whenColoris set tospecificorglobalaffects count propagation whenCountsis set toleveldrug sunburst: 1 corresponds to the central node, 5 to the outermost node (=drug)phenotype sunburst: 0 corresponds to the central node, 13 to the outermost nodeSummary optionsEnable: displays all available subtrees in a single view
(resource intensive, set Labels tononefor faster loading)Columns: defines the amount of columns when summary plot is enabledSave and Plot optionsSave: when enabled, an interactive.htmlfile containing the plot as well as a.tsvfile containing the ontology data based on the current settings is generated for later usePlot: Process and generate plot, opens in a Browser windowMeSH OntologyThis separator-based ontology follows the principles of theMeSH tree.A Tree ID is defined by acombination of three numbers or letters, for exampleC01.Levels are separated by adot., for exampleC01.001.Ontologiesup to thirteen hierarchical levelsare supported.A single phenotype end-node can be assigned to multiple parent-nodes by specifying the parents tree ids as
a pipe separated string in the columnTree ID, for exampleC01.001.001|C02.001.001.If a child element is defined without a valid parent node existing, the GUI generates all parent elements with the default color and value 0. For example, the node123.001is automatically generated if only the child node123.001.001was defined. This works only if at least the most central node123was defined manually.Counts entered in the file will be converted to integers. If a node should be displayed without counts, use0.The loaded file must contain7 columnsand follow the below structure to be correctly recognized:Column IndexHeader TextDescription0MeSH IDRequired primary identifier of a node in formatC01.0011Tree IDRequired|pipe delimited list of Tree IDs of a node (allows 1:N mappings)2NameOptional label to be displayed inside the sunburst wedges3DescriptionOptional description displayed in the sunburst wedge tooltip4CommentOptional comment displayed in the sunburst wedge tooltip5Counts [Name]Required count for wedge weights,Namewill be used as figure title6ColorOptional color for the sunburst wedges, must be hex-string in format#FFFFFFATC OntologyThis kind of sunbursts have a fixed hierarchy of 5 levels and are based on theATC tree.ATC codes are divided into five levels, which must follow the following naming conventions:1st level: letter2nd level: two numbers3rd level: letter4th level: letter5th level: two numbersExample ATC code:A10BA02The hierarchy does only allow 1:1 child-parent relationships, contrary to the other ontologies.
For example, if the drugdeltatoninshould be assigned to the
parent nodesA01AAandB01BB, it must be defined twice with the idsA01AA01andB01BB01.The loaded file must contain6 columnsand follow the below structure to be correctly
recognized as a ATC ontology:Column IndexHeader TextDescription0ATC codeRequired primary identifier of a node in formatA10BA021LevelOptional level as number, not used for building tree2LabelOptional label to be displayed inside the sunburst wedges3CommentOptional comment displayed in the sunburst wedge tooltip4Counts [Name]Required count for wedge weights,Namewill be used as figure title5ColorOptional color for the sunburst wedges, must be hex-string in format#FFFFFFCustom Separator-based OntologiesOntoloViz supports loading of custom ontologies - if no known format is detected, a prompt will ask
whether the loaded file is a separator-based ontology or if it does contain identifiers with child-
and parent-ids. For separator-based ontologies, the following separators are supported:.(dot),,(colon),_(underscore),/(slash).
To generate such an ontology, the following 5-column layout is required:Column IndexHeader TextDescription0IDRequired node identifier of a node in formatA.1- multiple IDs can be separated with|(pipe)1LabelOptional label to be displayed inside the sunburst wedges2CommentOptional comment displayed in the sunburst wedge tooltip3CountOptional count for wedge weights4ColorOptional color for the sunburst wedges, must be hex-string in format#FFFFFFCustom Parent-based OntologiesFor loading any ontology with arbitrary IDs that do not follow a structured schema, the definition of a child-parent relationship using a 6-column layout is required:Column IndexHeader TextDescription0IDRequired node identifier in any format - multiple IDs can be separated with|(pipe)1ParentRequired parent identifier in any format - if parent ID does not exist, node will be removed2LabelOptional label to be displayed inside the sunburst wedges3CommentOptional comment displayed in the sunburst wedge tooltip4CountOptional count for wedge weights5ColorOptional color for the sunburst wedges, must be hex-string in format#FFFFFFTemplates and ExamplesFilenameDescriptionatc_example_covid_drugs_experimental.tsvATC-based example with data from theDrugBankindicating experimental drugs related to COVID-19.atc_example_covid_drugs_trial_summary.tsvATC-based example with data frompublicly available clinical trial dataindicating drugs tested in clinical studies, one count represents usage in one study.atc_template.tsvATC-based empty template of theATCtree based on the manually curated chemical database of bioactive moleculesChEMBL v29.custom_template_parent_based.tsvTemplate for creating your own ontology based on any child and parent terms.custom_template_separator_based.tsvTemplate to create your own ontology based on a separator-based tree structure - for this template the underscore character_has been used.mesh_example_pubmed_mapped.tsvMeSH-based example with data from the publicly availablePubMeddatabase of publications (title + abstract), where disease-related MeSH terms were extracted and mapped to the MeSH-tree.mesh_template.tsvMeSH-based empty template of theMeSHtreeCandF03. Terms are unique and mapped to all related parent nodes.atc_example.htmlATC-based sample plot generated with the providedcovid_drugs_trial_summary.tsvfile.mesh_example.htmlMeSH-based sample plot generated with the providedcovid_drugs_trial_summary.tsvfile.Screenshots and DemosDemo 1:Minimal example for creating a phenotype based ontologyDemo 2:Showcase of some of the features available in OntoloViz (used template:test_tree.zip)Screenshot 1:Drug sunburst plot with enabled labels, counts propagated up to level 3Screenshot 2:Summary phenotype sunburst plot with tooltip, counts propagated up to the central node, color codedScreenshot 3 & 4:Left: define automatic color scales based on defined counts with thresholds and hex color codes, Right: define border properties (width, opacity, colors) or disable them entirelySpecial Thanks toPaul Perco, who had the initial idea for this package and provided support throughout the entire processAndreas Heinzel, for inspiration regarding architectural- and software-related topicsThe Delta4 GmbH team for providing helpful inputsReferenceMatthias Ley, Andreas Heinzel, Lucas Fillinger, Klaus Kratochwill, Paul Perco, OntoloViz: a GUI for interactive visualization of ranked disease or drug lists using the MeSH and ATC ontologies, Bioinformatics Advances, 2023; vbad113,https://doi.org/10.1093/bioadv/vbad113