# freyja-plot
Plotting lineage abundance for individual samples from aggregated freyja demix results
## Installation:
```console
pip install freyja-plot
```
## Inputs:
`freyja-plot` enables the production of plots from aggregated freyja data. This can be acquired after two Freyja steps. See the [Freyja docs](https://github.com/andersen-lab/Freyja) for more details.
1. `freyja demix [variants-file] [depth-file] --output [output-file]`
2. `freyja aggregate [directory-of-output-files] --output [aggregated-filename.tsv]`
`freyja-plot` just needs the output file from `freyja aggregate`: [aggregated-filename.tsv].
## Usage:
### Create a freyja plotter with one or more files
```python
from freyja_plot import FreyjaPlotter
# single batch plotter from one file
plotter = FreyjaPlotter("examples/wastewater-freyja-aggregated.tsv")
# single batch plotter with multiple input files
# note: default behavior assumes multiple files should be compared, so set compare=False to avoid this
multi_file_plotter = FreyjaPlotter(
["examples/wastewater-freyja-aggregated.tsv","examples/wastewater-freyja-compare1.tsv"],
compare=False
)
```
### Create a freyja plotter for comparing samples across batches
Note: this requires a different file for each batch.
```python
from freyja_plot import FreyjaPlotter
# comparison plotter, derived names
comp_plotter_derived_names = FreyjaPlotter([
"example/wastewater-freyja-compare1.tsv",
"example/wastewater-freyja-compare2.tsv",
])
# comparison plotter, customized batch names (this uses a dict as input)
# note: the value associated with each filename key will be appended to each sample name when plotted
comp_plotter_explicit_names = FreyjaPlotter({
"example/wastewater-freyja-compare1.tsv":"plate1",
"example/wastewater-freyja-compare2.tsv":"plate2",
})
```
### Plotting
Plotting works the same whether comparing multiple batches or viewing a single set of samples, so we'll simplify our several plotter examples from above into one `plotter`. The method `FreyjaPlotter.plotLineages()` returns a plotly figure that can be used for further analysis. If a filename is given, the fig will be saved there. `freyja-plot` currently supports html and png files. Writing .png files may not work... see [this link](https://github.com/plotly/Kaleido/issues/134) for more details.
```python
# simple plot of lineage abundances for all samples in file
plotter.plotLineages(fn="lineage_abundance_example.html")
```
With more samples or more varied samples, the above non-summarized plot may take a while to produce. Sometimes, it may be more useful to get a summarized view of the lineages and their abundance in each sample.
```python
plotter.plotLineages(summarized=True,fn="summarized_lineage_abundance_example.html")
```
To view higher level lineage assignments with the non-summarized freyja output, the `superlineage` flag can be used. The base `superlineage` is demarked level 0. Each next sublineage (to the next ".") can be attained by adding 1 for each sublineage desired. 'BA.5.1' with a requested sublineage of 0 would return 'BA.*', as would a sample with the lineage 'BA'. For less specific lineages, if the `superlineage` level gets to high, the most specific lineage possible will be returned. 'BA.5.1' with a requested sublineage of 5 would still only return 'BA.5.1'.
```python
# plotting superlineage, level 0: e.g. BA.* ()
fig1 = plotter.plotLineages(superlineage=0,fn="superlineage_abundance_example.html")
# plotting superlineage, level 2: e.g. BA.5.1.* ()
fig2 = plotter.plotLineages(superlineage=2,fn="superlineage_abundance_example.html")
```
To stack multiple lineage plots
```python
plotter.plotLineages([fig1,fig2],["Fig 1 Title","Fig 2 Title"],fn="combined_plots_example.html")
```
#### Example plots
Here's an example plot from a single batch.
Here's an example plot from a batch comparison with summarized=True.
Did you notice how some samples are missing labels in the example plots when presented as .png files? If you zoom in or expand the html version of the plot enough (or you have fewer samples per plot), missing names should appear.
## Testing
If you run the script [create_test_plots.py](example\create_test_plots.py), some test png/html files will be produced in a new directory `./example/test_images`. They should look like the images above in this tutorial.
## Additional functionality
To see what else you can do, use python's `help()` function. Here's a useful excerpt from the portion that's most useful.
```python
>>> import freyja_plot
>>> help(freyja_plot.FreyjaPlotter)
...
plotLineages(self,
summarized=False, superlineage=None, minimum=0.05,
fn=None, title='Freyja lineage prevalence', samples='all',
include_pattern=None, exclude_pattern=None)
Returns plot of stacked bars showing lineage abundances for each sample
Args:
`summarized` (bool): whether to use summarized lineages or all, defaults to False
`superlineage` (int|None): number of superlineages to consider, ignored if not provided, 0 is the base lineage, defaults to None
`minimum` (float): minimum abundance value to include in plot - anything less is categorized in "Other", defualts to 0.05
`fn` (str|Path): where to write fig, if provided, defaults to None
`title` (str): plot title, defualts to "Freyja lineage prevalence"
`samples` (list|"all"): only the listed samples will be plotted
`include_pattern` (str): samples to include like "sample1|sample2"
`exclude_pattern` (str): samples to exclude like "sample1|sample2"
...
```
Raw data
{
"_id": null,
"home_page": "https://github.com/enviro-lab/freyja-plot.git",
"name": "freyja-plot",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "freyja, plot, lineage, abundance, covid",
"author": "Sam Kunkleman",
"author_email": "skunklem@uncc.edu",
"download_url": "https://files.pythonhosted.org/packages/33/70/f73a05b8738fad7b830d455147f13e215ce6ae4923ae8ea013982bfdeab1/freyja_plot-0.8.3.tar.gz",
"platform": null,
"description": "# freyja-plot\nPlotting lineage abundance for individual samples from aggregated freyja demix results\n\n![Example Lineage Abundance Plot](example/example_images/batch_comparison_selection_example.png \"These samples had some issues on plate1 or else the 'plate1' and 'plate2' versions of each sample would look more similar.\")\n\n## Installation:\n```console\npip install freyja-plot\n```\n\n## Inputs:\n`freyja-plot` enables the production of plots from aggregated freyja data. This can be acquired after two Freyja steps. See the [Freyja docs](https://github.com/andersen-lab/Freyja) for more details.\n1. `freyja demix [variants-file] [depth-file] --output [output-file]`\n2. `freyja aggregate [directory-of-output-files] --output [aggregated-filename.tsv]`\n\n`freyja-plot` just needs the output file from `freyja aggregate`: [aggregated-filename.tsv].\n\n## Usage:\n### Create a freyja plotter with one or more files\n```python\nfrom freyja_plot import FreyjaPlotter\n\n# single batch plotter from one file\nplotter = FreyjaPlotter(\"examples/wastewater-freyja-aggregated.tsv\")\n\n# single batch plotter with multiple input files\n# note: default behavior assumes multiple files should be compared, so set compare=False to avoid this\nmulti_file_plotter = FreyjaPlotter(\n [\"examples/wastewater-freyja-aggregated.tsv\",\"examples/wastewater-freyja-compare1.tsv\"],\n compare=False\n)\n```\n\n### Create a freyja plotter for comparing samples across batches\nNote: this requires a different file for each batch.\n```python\nfrom freyja_plot import FreyjaPlotter\n\n# comparison plotter, derived names\ncomp_plotter_derived_names = FreyjaPlotter([\n \"example/wastewater-freyja-compare1.tsv\",\n \"example/wastewater-freyja-compare2.tsv\",\n])\n\n# comparison plotter, customized batch names (this uses a dict as input)\n# note: the value associated with each filename key will be appended to each sample name when plotted\ncomp_plotter_explicit_names = FreyjaPlotter({\n \"example/wastewater-freyja-compare1.tsv\":\"plate1\",\n \"example/wastewater-freyja-compare2.tsv\":\"plate2\",\n})\n```\n\n### Plotting\nPlotting works the same whether comparing multiple batches or viewing a single set of samples, so we'll simplify our several plotter examples from above into one `plotter`. The method `FreyjaPlotter.plotLineages()` returns a plotly figure that can be used for further analysis. If a filename is given, the fig will be saved there. `freyja-plot` currently supports html and png files. Writing .png files may not work... see [this link](https://github.com/plotly/Kaleido/issues/134) for more details.\n```python\n# simple plot of lineage abundances for all samples in file\nplotter.plotLineages(fn=\"lineage_abundance_example.html\")\n```\n\nWith more samples or more varied samples, the above non-summarized plot may take a while to produce. Sometimes, it may be more useful to get a summarized view of the lineages and their abundance in each sample.\n```python\nplotter.plotLineages(summarized=True,fn=\"summarized_lineage_abundance_example.html\")\n```\n\nTo view higher level lineage assignments with the non-summarized freyja output, the `superlineage` flag can be used. The base `superlineage` is demarked level 0. Each next sublineage (to the next \".\") can be attained by adding 1 for each sublineage desired. 'BA.5.1' with a requested sublineage of 0 would return 'BA.*', as would a sample with the lineage 'BA'. For less specific lineages, if the `superlineage` level gets to high, the most specific lineage possible will be returned. 'BA.5.1' with a requested sublineage of 5 would still only return 'BA.5.1'.\n```python\n# plotting superlineage, level 0: e.g. BA.* ()\nfig1 = plotter.plotLineages(superlineage=0,fn=\"superlineage_abundance_example.html\")\n# plotting superlineage, level 2: e.g. BA.5.1.* ()\nfig2 = plotter.plotLineages(superlineage=2,fn=\"superlineage_abundance_example.html\")\n```\n\nTo stack multiple lineage plots\n```python\nplotter.plotLineages([fig1,fig2],[\"Fig 1 Title\",\"Fig 2 Title\"],fn=\"combined_plots_example.html\")\n```\n\n#### Example plots\nHere's an example plot from a single batch.\n\n![superlineage_example.png](example/example_images/superlineage_example.png?raw=true \"Lineage abundance plot with superlineage=2 - png\")\n\nHere's an example plot from a batch comparison with summarized=True.\n\n![batch_comparison_example.png](example/example_images/batch_comparison_example.png?raw=true \"Batch comparison of samples using summarized lineage abundances - png\")\n\nDid you notice how some samples are missing labels in the example plots when presented as .png files? If you zoom in or expand the html version of the plot enough (or you have fewer samples per plot), missing names should appear.\n\n## Testing\nIf you run the script [create_test_plots.py](example\\create_test_plots.py), some test png/html files will be produced in a new directory `./example/test_images`. They should look like the images above in this tutorial.\n\n## Additional functionality\nTo see what else you can do, use python's `help()` function. Here's a useful excerpt from the portion that's most useful.\n```python\n>>> import freyja_plot\n>>> help(freyja_plot.FreyjaPlotter)\n...\nplotLineages(self, \n summarized=False, superlineage=None, minimum=0.05, \n fn=None, title='Freyja lineage prevalence', samples='all', \n include_pattern=None, exclude_pattern=None)\nReturns plot of stacked bars showing lineage abundances for each sample\n\nArgs:\n `summarized` (bool): whether to use summarized lineages or all, defaults to False\n `superlineage` (int|None): number of superlineages to consider, ignored if not provided, 0 is the base lineage, defaults to None\n `minimum` (float): minimum abundance value to include in plot - anything less is categorized in \"Other\", defualts to 0.05\n `fn` (str|Path): where to write fig, if provided, defaults to None\n `title` (str): plot title, defualts to \"Freyja lineage prevalence\"\n `samples` (list|\"all\"): only the listed samples will be plotted\n `include_pattern` (str): samples to include like \"sample1|sample2\"\n `exclude_pattern` (str): samples to exclude like \"sample1|sample2\"\n...\n```",
"bugtrack_url": null,
"license": "MIT",
"summary": "Plotting lineage abundance for individual samples from aggregated freyja demix results",
"version": "0.8.3",
"project_urls": {
"Homepage": "https://github.com/enviro-lab/freyja-plot.git",
"Repository": "https://github.com/enviro-lab/freyja-plot.git"
},
"split_keywords": [
"freyja",
" plot",
" lineage",
" abundance",
" covid"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "07615dcf3c61c18e776a78cc15727e1ff4c453b862711fa619bac66b38b8879a",
"md5": "6da9e1a342de972ee74fb5f6032f4c23",
"sha256": "7b60d82493c83c6f0ba55d2cc3daf27b12e7e558f48a6a1a82396588b7c174c7"
},
"downloads": -1,
"filename": "freyja_plot-0.8.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6da9e1a342de972ee74fb5f6032f4c23",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 3412231,
"upload_time": "2024-07-31T13:24:59",
"upload_time_iso_8601": "2024-07-31T13:24:59.409377Z",
"url": "https://files.pythonhosted.org/packages/07/61/5dcf3c61c18e776a78cc15727e1ff4c453b862711fa619bac66b38b8879a/freyja_plot-0.8.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3370f73a05b8738fad7b830d455147f13e215ce6ae4923ae8ea013982bfdeab1",
"md5": "34ab501db99353e86dfb574876c00000",
"sha256": "4da6d06a51e8b494801cc8b5a743827b80ff5ed5c0d1af6474f3eebf913b0f77"
},
"downloads": -1,
"filename": "freyja_plot-0.8.3.tar.gz",
"has_sig": false,
"md5_digest": "34ab501db99353e86dfb574876c00000",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 3403209,
"upload_time": "2024-07-31T13:25:01",
"upload_time_iso_8601": "2024-07-31T13:25:01.781430Z",
"url": "https://files.pythonhosted.org/packages/33/70/f73a05b8738fad7b830d455147f13e215ce6ae4923ae8ea013982bfdeab1/freyja_plot-0.8.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-31 13:25:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "enviro-lab",
"github_project": "freyja-plot",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "freyja-plot"
}
JSON
