{"id":24527238,"url":"https://github.com/biobakery/graphlan","last_synced_at":"2025-04-10T02:21:40.849Z","repository":{"id":47369360,"uuid":"234528108","full_name":"biobakery/graphlan","owner":"biobakery","description":"High-quality circular representations of taxonomic and phylogenetic trees","archived":false,"fork":false,"pushed_at":"2024-08-07T16:09:38.000Z","size":2812,"stargazers_count":95,"open_issues_count":3,"forks_count":28,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-03T00:05:43.100Z","etag":null,"topics":["biobakery","circular-visualization","phylogenetic-trees","python","taxonomic-trees","tools"],"latest_commit_sha":null,"homepage":"https://segatalab.github.io/tools/graphlan","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/biobakery.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-17T10:41:36.000Z","updated_at":"2025-03-13T15:15:22.000Z","dependencies_parsed_at":"2024-08-07T19:26:36.419Z","dependency_job_id":null,"html_url":"https://github.com/biobakery/graphlan","commit_stats":{"total_commits":130,"total_committers":6,"mean_commits":"21.666666666666668","dds":0.5384615384615384,"last_synced_commit":"7a6df5169584c899183e3a15aeef090e039240d5"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biobakery%2Fgraphlan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biobakery%2Fgraphlan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biobakery%2Fgraphlan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biobakery%2Fgraphlan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/biobakery","download_url":"https://codeload.github.com/biobakery/graphlan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248143124,"owners_count":21054709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["biobakery","circular-visualization","phylogenetic-trees","python","taxonomic-trees","tools"],"created_at":"2025-01-22T06:17:42.624Z","updated_at":"2025-04-10T02:21:40.819Z","avatar_url":"https://github.com/biobakery.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"GraPhlAn is a software tool for producing high-quality circular \nrepresentations of taxonomic and phylogenetic trees. GraPhlAn focuses on \nconcise, integrative, informative, and publication-ready representations of \nphylogenetically- and taxonomically-driven investigation.\n\nYou can find below the instruction for installing and using the software.\nIf you have any questions or comment please refer to the project home page at\nhttps://github.com/biobakery/graphlan\nor to thebioBakery help forum:\nhttps://forum.biobakery.org/\n\n## Installation\n\nGraPhlAn is available in Bioconda and via pip, you can install it by running:\n\n- Bioconda: `conda install -c bioconda graphlan`\n- Pip : `pip install graphlan`\n\nOtherwise, you can fetch it from GitHub (https://github.com/biobakery/graphlan)\nIn a Unix environment, this means you have to type:\n```bash\n$ git clone https://github.com/biobakery/graphlan.git\n```\nand install it using\n```bash\npip install .\n```\n\nThis will install GraPhlAn in your default Python distribution, it is advised to use virtual environment such as Anaconda.\n\nFor Windows or MacOS systems a similar procedure should be followed. Is is also\npossible to obtain the software using the releases page at\nhttps://github.com/biobakery/graphlan/releases.\n\n\n## Prerequisites\nRequired Python packages are automatically installed when GraPhlAn is installed via Conda or pip.\n\nIf you want to install it from the repository, you need to have the following programs and libraries installed:\n- python 2.7 or higher ( http://www.python.org/ )\n- the biopython python library 1.76 ( http://biopython.org )\n- the matplotlib python library 1.1 or higher \n  ( http://matplotlib.sourceforge.net )\n\n## Usage\n\nThe GraPhlAn package consists in two main scripts:\n1- `graphlan.py`\n2- `graphlan_annotate.py`\n\nThe first produces graphical output of an input tree in any of the three most\npopular format: Newick, PhyloXML, or text format. The second modifies any \ninput tree (in any of the three standard format) adding additional \ninformation regarding structural or graphical aspects of the tree (like colors \nand style of the taxa, labels, shadows, heatmaps, ...); \n`graphlan_annotate.py` generates PhyloXML files that can be converted into images by `graphlan.py`.\n\n\nMore specifically, here are all the options one can set for `graphlan.py`:\n\n```\nusage: graphlan.py [-h] [--format ['output_image_format']]\n                   [--warnings WARNINGS] [--positions POSITIONS]\n                   [--dpi image_dpi] [--size image_size] [--pad pad_in]\n                   [--external_legends] [--avoid_reordering] [-v]\n                   input_tree output_image\n\nGraPhlAn 1.1.3 (5 June 2018) AUTHORS: Nicola Segata (nsegata@hsph.harvard.edu)\n\npositional arguments:\n  input_tree            the input tree in PhyloXML format\n  output_image          the output image, the format is guessed from the\n                        extension unless --format is given. Available file\n                        formats are: png, pdf, ps, eps, svg\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --format ['output_image_format']\n                        set the format of the output image (default none\n                        meaning that the format is guessed from the output\n                        file extension)\n  --warnings WARNINGS   set whether warning messages should be reported or not\n                        (default 1)\n  --positions POSITIONS\n                        set whether the absolute position of the points should\n                        be reported on the standard output. The two\n                        cohordinates are r and theta\n  --dpi image_dpi       the dpi of the output image for non vectorial formats\n  --size image_size     the size of the output image (in inches, default 7.0)\n  --pad pad_in          the distance between the most external graphical\n                        element and the border of the image\n  --external_legends    specify whether the two external legends should be put\n                        in separate file or keep them along with the image\n                        (default behavior)\n  --avoid_reordering    specify whether the tree will be reorder or not\n                        (default the tree will be reordered)\n  -v, --version         Prints the current GraPhlAn version and exit\n```\n\n\n\nInput tree files for `graphlan.py` can be generated, personalized, and annotated\nusing the graphlan_annotate.py module. In addition to the tree topology and\n(possibly) branch lengths, graphlan_annotate.py reads an \"annotation file\" \n(`--annot` option) which specifies the graphical options for the tree. The\nsyntax of the annotation file is described comprehensively below. Here is the\ncommand line invocation syntax.\n\n\n```\nusage: graphlan_annotate.py [-h] [--annot annotation_file] [-v]\n                            input_tree [output_tree]\n\nGraPhlAn annotate module 1.1.3 (5 June 2018) AUTHORS: Nicola Segata\n(nsegata@hsph.harvard.edu)\n\npositional arguments:\n  input_tree            the input tree in Newick, Nexus, PhyloXML or plain\n                        text format\n  output_tree           the output tree in PhyloXML format containing the\n                        newly added annotations. If not specified, the input\n                        tree file will be overwritten\n\noptional arguments:\n  -h, --help            show this help message and exit\n  --annot annotation_file\n                        specify the annotation file\n  -v, --version         Prints the current GraPhlAn version and exit\n```\n\n## Command and syntsx of the annotation file\n\nThe annotation file is a tab-delimited file listing the graphical options for\nclades. Usually each line has three fields: the name of the clade, the name of\nthe option, and the value to assign to the option. Lines can however have two\nfields (typically for \"global\" option not referred to a specific clade) or \nfour fields when the external rings (a sort of circular heatmap) is specified.\n\nBelow we report and describe all available options and their syntax subdivided\nby option types.\n\n### GLOBAL TREE OPTIONS:\n\nGlobal structural and visual characteristics affecting the entire tree are\nspecified in the annotation file with a two-column tab separated syntax with the\nfollowing pattern:\n\n```\nglobal_tree_option\tglobal_tree_option_value\n```\nwhere `global_tree_option` can be any of the following: \n\n`ignore_branch_len [def. 0 = False]` : specify whether to display the tree with\n    fixed branch length (i.e. 0) or with the values specified in the input \n    tree. If the input tree is not containing branch length information, branch \n    lengths will not be showed regardless of this option \n\n`total_plotted_degrees [def. 360]` : the total circular portion used in plotting \n    the tree. 360 means that the tree uses the full rotational space. Small \n    trees are usually best displayed with a limited total_plotted_degrees value.\n\n`start_rotation [def 0]` : the default starting rotational position for the first \n    leaf of the tree \n\n`clade_separation [def 0.0]` : specify a fractional separation between clades \n    which is proportional to the branch distance between subtrees. It option can\n    be used to visually separate more clades that are reciprocally deep \n    branching.  \n\n`branch_bracket_depth [def 0.25]` : the relative position of the branch bracket \n    which is the radial segment from which the child taxa branches originate.  \n\n`branch_bracket_width [def 1.0]` : the width of the branch bracket relative to \n    the position of the most separated child roots\n\n`branch_thickness [def 0.75]` : the global thickness of the lines connecting taxa\n\n`branch_color [def black]` : the color of the lines connecting taxa\n\n`branch_color_from_ancestor [def 1]` : whether to use the color of the closest\n    ancestor colored taxa for the downstream branches\n\n\n### GLOBAL GRAPHICAL OPTIONS:\n\nGlobal options affecting the graphical appearance of annotations, legends, and\nmarkers specified in the annotation file with a two-column tab separated syntax\nwith the following pattern:\n\n```\nglobal_graphical_option  global_graphical_option_value\n```\n\nwhere `global_graphical_option` can be any of the following:\n\n`title` : set the title of the output image\n\n`title_font_size [def. 15]` : set the font size used to display the title\n\n`annotation_background_width [def. 0.1]` : set the width of the annotation, you\n    can think of it as inserting a space before and after the label of the\n    annotation\n\n`annotation_background_alpha [def. 0.2]` : set the transparency level of the\n    background. Keep in mind that some annotations can overlap\n\n`annotation_background_separation [def. 0.02]` : set how much space keep between\n    leafs and the last labels\n\n`annotation_background_offset [def. 0.02]` : set the end of the circle that\n    contains the tree, where the exteran optional barplots start\n\n`annotation_legend_font_size [def. 7]` : set the font size used in the annotation\n    legend\n\n`class_legend_font_size [def. 7]` : set the font size used in the class legend\n\n`class_legend_marker_size [def. 1.0]` : the size of the markers in the legend\n\n`internal_labels_rotation [def. None]` : set the internal labels orientation. It \n    does not work well, already put in the known issues list\n\n### GRAPHICAL TREE OPTIONS:\n\nThe graphical tree options are the most common way of personalizing the trees.\nThey can be referred to specific clade, to set of clades, or to all clade. The\nsyntax is the following:\n\n```\n[clade_name{+|*|^}]\tgraphical_tree_option\tgraphical_tree_option_value\n```\n\nIf the `clade name` is omitted the option is applied to ALL clades. The clade\ncan be specified with the full label comprising all names from the root of the\ntree or with the last level only (if last level names are not unique, multiple\nmatching clades will be affected by the command). Optionally, at the end of the\nclade name, one of the following character can be added (see below for the\nmeaning of these symbols): `+, *, ^`\n\nThe `graphical_tree_option` can be:\n\n`clade_marker_size [def. 20.0]` : the size of the marker representing the root \n    of the clade inside the tree\n\n`clade_marker_color [def. #FFFFFF, i.e. white]` : the fill color of the marker \n    representing the root of the clade inside the tree\n\n`clade_marker_shape [def. 'o', i.e. circle]` : the shape of the clade marker. \n    See the Marker Shapes table below for the allowed options\n\n`clade_marker_edge_width [def. 0.5]` : the thickness of the border for clade \n    markers\n\n`clade_marker_edge_color [def. #000000, i.e. black]` : the color of the markers' \n    border\n\n`clade_marker_label` : specify a label to insert in the specified clade\n\n`clade_marker_font_size [def. 7]` : the size of the font color for the clade\n    marker label specified\n\n`clade_marker_font_color [def 'k', i.e. black]` : the font color of the clade\n    marker label specified\n\nWhen added after the name of a valid clade, the following three characters can\nbe used to apply the same property to multiple parts of the clade' subtree\n\n`*` : the specified clade and all its descendants are affected by the property\n`+` : the specified clade and all its terminal nodes are affected \n`^` : all (and only) the terminal nodes of the specified clade are affected\n\n\n### ANNOTATION OPTIONS\n\n```\n[clade_name]\tannotation_option\tgraphical_tree_option_value\n```\n\nWe call annotations the shadings highlighting clades and the corresponding\nsubtree. Annotations can be colored, their alpha-channel can be globally\nregulated, and have a label associated with them. Specifically, the options\navailable for annotations are:\n\n`annotation [def. no annotation]` : the label the be associated and displayed for\n    the annotation. This can assume several formats:\n      1. `str` (a string not containing ':'): the string to be displayed entirely \n         (an only) on the shading\n      2. `key:str` : the (supposedly short) key will be displayed on the \n         annotation shading, whereas the full `key:string` label will be reported \n         as external legend\n      3. `*:str` : a key will be generated and used as the 2. `key:str` case\n      4. `*` : the name of the clade (specifically the last taxonomic level only) \n         will be used as the `str` in the 1. case above\n      5. `*:*` : the combination of the 3. and 4. cases above\n\n`annotation_font_size [def. 7]` : the font size of the annotation label\n\n`annotation_font_stretch [def. 0]` : horizontal font compactness (0 is minimal)\n\n`annotation_rotation [def. 0]` : the rotation of the label. As default the rotation\n    is perpendicular to the radial position of the label. It can be changed to \n    90 so that the labels are less likely to overlap\n\n`annotation_background_color [def. grey]` : the color of the annotation background\n\n`annotation_background_edge_color [def annotation_background_color]` : the color \n    of the edge for the annotation background. NOT IMPLEMENTED YET\n\n\n### INTERNAL ANNOTATION OPTIONS\n\n```\nannotation_option\tannotation_r\tannotation_value\n```\n\nInternal annotations are used to label the levels in a tree (e.g. specify the\nlevel of bacterial species in a taxonomic tree). `annotation_r` specifies the\nradial distance from the center (i.e. the number of levels). Currently,\nannotation_option can be:\n\n`internal_label` : the label to be displayed\n\n`internal_label_font_size [def. 8]` : the font\n\nThe rotational position of the labels can be specified with the \n`internal_labels_rotation` parameter (see GLOBAL GRAPHICAL OPTIONS) \n\n\n### RING OPTIONS\n\nWe call rings the graphical elements external to the tree itself that can be\nseen as \"circular heatmaps\", \"circular barplots\", and actually more (like\nindicator elements). These \"rings\" are linked directly to the internal tree as\neach segment of the rings correspond to a tree leaf (and potentially to internal\nnodes as well). Multiple rings can be specified for the same image and each must\nhave a progressive associated number (level \"1\" being the most internal ring).\n\nThe general syntax for rings is:\n```\n[clade_name]\tring_option\tring_level\tring_option_value\n```\n\nIf `clade_name` is not present or if it is `\"*\"` the ring option is applied to all\nthe ring sectors in the `ring_level`. The `ring_level` is a integer number that\nmust always be specified.\n\nHere are the possible ring options:\n\n`ring_color [def. black]` : the color of the ring segment \n\n`ring_width [def. 1.0]` : the width of the ring segment a fraction of the total \n    circular width available for the specific clade\n\n`ring_height [def. highest height for the rings in the same level, or 0.1 if no\n    heights are specific]` : the height of the circular segment. If not specific \n    the same default height (0.1*size of the tree) is applied for all ring \n    segment in the level, otherwise the height is equal to the biggest height \n    value in the level.\n\n`ring_alpha [def. 1.0]`: the transparency value. 0.0 means completely transparent\n    (thus invisible), 1.0 means completely opaque (no transparencies) \n\n`ring_shape [def. R]`: the shape of the ring. Default is 'R' for rectangular which\n    means that the whole available area is used. The alternatives are currently \n    'v' or '^' which mean triangular shape (with opposite directions) that can \n    be used as pointing arrow for highlighting specific clades. \n\n`ring_edge_width [def 0.1]`: the width of the border of the ring segment\n\n`ring_edge_color [def None, which means 'ring_color']`: the color of the border \n    of the ring segment\n\nSome additional ring options refer to non clade-specific aspects like the label\nof the ring itself or the graphical separation between rings. These options are\nspecified without a clade name in the following tree-column format:\n\n```\nglobal_ring_option     ring_level      global_ring_option_value\n```\n\nSpecifically, the ring options can be:\n\n`ring_label [def. None]`: the label to be displayed at \"stat_rotation\" position \n    for the rings. total_plotted_degrees should be less than 360 to make space \n    for these labels\n\n`ring_label_color [def. black]`: the color of the ring label\n\n`ring_label_font_size [def. 11]`: the font size of the ring labels\n\n`ring_internal_separator_thickness [def.  0.0 which means absent]`: the thickness \n    of the circular line separating different ring levels. This is referred \n    to the most internal of the two sides of each ring.\n\n`ring_external_separator_thickness [def.  0.0 which means absent]`: the thickness\n    of the circular line separating different ring levels. This is referred to \n    the most external of the two sides of each ring.\n\n`ring_separator_color [def. 'k' for black]`: the color of the circular line \n    separating different ring levels.\n\n\n### COLORS\n\nColors are strings that can be:\n- one of the following 'default' colors: `blue, green, red, cyan, magenta, \n    yellow, black, white`\n- a one-letter shortcut for the above colors: `'b' (blue), 'g' (green), \n    'r' (red), 'c' (cyan), 'm' (magenta), 'y' (yellow), 'k' (black), \n    'w' (white) `\n\n- a RGB color code in the hexadecimal format: `#rrggbb`, for example `#FF0000`\n    corresponds to (full) red\n\n\n### MARKER SHAPES:\n\nAs of August 2012 we support the marker types available in matplotlib version\n1.1.1. Specifically here are the codes for the markers. Note that some of them\nare shapes with internal color-filled space, other are edge- or point-only\nmarkers.\n\n- `.` : point marker\n- `,` : pixel marker\n- `o` : circle marker\n- `v` : triangle_down marker\n- `^` : triangle_up marker\n- `\u003c` : triangle_left marker\n- `\u003e` : triangle_right marker\n- `1` : tri_down marker\n- `2` : tri_up marker\n- `3` : tri_left marker\n- `4` : tri_right marker\n- `s` : square marker\n- `p` : pentagon marker\n- `*` : star marker\n- `h` : hexagon1 marker\n- `H` : hexagon2 marker\n- `+` : plus marker\n- `x` : x marker\n- `D` : diamond marker\n- `d` : thin_diamond marker\n- `|` : vline marker\n- `_` : hline marker\n\n## Contributions\nThanks go to these wonderful people:","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiobakery%2Fgraphlan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbiobakery%2Fgraphlan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiobakery%2Fgraphlan/lists"}