onecodex 0.19.0__py3-none-any.whl

docs/.gitignore

@@ -0,0 +1 @@
+_build/

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,47 @@
+import datetime
+import os
+import sys
+from onecodex.version import __version__
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "One Codex"
+copyright = f"{str(datetime.datetime.now().year)}, One Codex"
+author = "One Codex"
+
+version = __version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx.ext.autodoc", "nbsphinx", "myst_parser", "sphinxext_altair.altairplot"]
+
+nbsphinx_execute = "always"
+nbsphinx_allow_errors = True
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "venv"]
+
+html_logo = "_static/one_codex_logo.png"
+html_theme = "sphinx_rtd_theme"
+
+
+sys.path.insert(0, os.path.abspath("../"))
+
+html_theme_options = {"collapse_navigation": True, "navigation_depth": 2}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_static_path = ["_static"]
+
+# Set default options for autodoc directives
+autodoc_default_options = {
+    "inherited-members": True,  # Automatically document inherited members
+}

docs/index.rst

@@ -0,0 +1,90 @@
+*******************************
+One Codex Python Client Library
+*******************************
+
+Introduction
+============
+
+This package provides 3 major pieces of functionality: (1) a core Python client
+library; (2) a simple CLI for interacting with the `One Codex platform
+<https://onecodex.com>`_ that uses that core library; and (3) optional
+extensions to the client library, which offers many features aimed at advanced
+users and provides functionality for use in interactive notebook environments
+(e.g., Jupyter notebooks).
+
+For installation instructions and instructions on using the command-line
+client, see the :doc:`readme`. You can find the source code on `GitHub
+<https://github.com/onecodex/onecodex>`_.
+
+.. toctree::
+   :maxdepth: 5
+   :caption: Contents
+   :hidden:
+
+   sample_collection
+   Visualization <visualization>
+   Statistics <statistics>
+   Taxonomy <taxonomy>
+   Models <models>
+   notebooks
+
+   GitHub <https://github.com/onecodex/onecodex>
+
+
+Installation
+============
+
+.. code-block:: bash
+
+   # The CLI (and core Python library)
+   pip install onecodex
+
+   # Optional dependencies (visualization, analysis and reports)
+   pip install onecodex[all]
+
+
+Quickstart
+==========
+
+.. altair-plot::
+    :strict:
+
+    import onecodex
+
+    # Instantiate the API (run onecodex login first)
+    ocx = onecodex.Api()
+
+    # Fetch some samples
+    project = ocx.Projects.get("d53ad03b010542e3")
+    samples = ocx.Samples.where(project=project, public=True, limit=10)
+
+    # Generate a Pandas DataFrame from classification results
+    results = samples.to_df()
+
+    # Plot a bar graph
+    # note: return_chart is not needed if using a Jupyter notebook
+    samples.plot_bargraph(return_chart=True)
+
+
+Tutorials
+=========
+
+For documentation and examples of common uses of the client library including
+interactive data analysis and plotting within Jupyter notebooks see
+:doc:`notebooks`.
+
+CLI
+===
+
+The Python package also comes with a command-line tool which can be used to
+upload samples to One Codex as well as results from the API. See
+:doc:`readme` for more information.
+
+
+See Also
+========
+
+* `Source on GitHub <https://github.com/onecodex/onecodex>`_
+* `Package on PyPI <https://pypi.org/project/onecodex/>`_
+* `One Codex API Documentation <https://developer.onecodex.com>`_
+* `One Codex <https://onecodex.com>`_

docs/models.rst

@@ -0,0 +1,87 @@
+******
+Models
+******
+
+``Analyses``
+============
+
+.. autoclass:: onecodex.models.analysis.Analyses
+   :members:
+   :show-inheritance:
+
+``Alignments``
+==============
+
+.. autoclass:: onecodex.models.analysis.Alignments
+   :members:
+   :show-inheritance:
+
+``Classifications``
+===================
+
+.. autoclass:: onecodex.models.analysis.Classifications
+   :members:
+   :show-inheritance:
+
+``FunctionalProfiles``
+======================
+
+.. autoclass:: onecodex.models.misc.FunctionalProfiles
+   :members:
+   :show-inheritance:
+
+``Panels``
+==========
+
+.. autoclass:: onecodex.models.analysis.Panels
+   :members:
+   :show-inheritance:
+
+``Assets``
+==========
+
+.. autoclass:: onecodex.models.misc.Assets
+   :members:
+   :show-inheritance:
+
+``Documents``
+=============
+
+.. autoclass:: onecodex.models.misc.Documents
+   :members:
+   :show-inheritance:
+
+``Jobs``
+========
+
+.. autoclass:: onecodex.models.misc.Jobs
+   :members:
+   :show-inheritance:
+
+``Projects``
+============
+
+.. autoclass:: onecodex.models.misc.Projects
+   :members:
+   :show-inheritance:
+
+``Samples``
+===========
+
+.. autoclass:: onecodex.models.sample.Samples
+   :members:
+   :show-inheritance:
+
+``Tags``
+========
+
+.. autoclass:: onecodex.models.misc.Tags
+   :members:
+   :show-inheritance:
+
+``Users``
+=========
+
+.. autoclass:: onecodex.models.misc.Users
+   :members:
+   :show-inheritance:

docs/notebook_examples/notebooks_demo.ipynb

@@ -0,0 +1,261 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Introduction\n",
+    "\n",
+    "This notebook contains all of the code from the corresponding post on the [One Codex Blog](https://www.onecodex.com/blog/2019/05/01/onecodex-library-for-data-viz/). These snippets are exactly what are in the blog post, and let you perfectly reproduce those figures.\n",
+    "\n",
+    "This is meant to be a starting off point for you to get started analyzing your own samples. You can copy this notebook straight into your account using the button in the header. To \"run\" or execute a cell, just hit `Shift + Enter`. A few other resources you may find useful include: notes on getting started with [our One Codex library](https://github.com/onecodex/onecodex); the [full documentation on our API](https://docs.onecodex.com) (more technical); a cheat sheet on [getting started with Pandas](http://nbviewer.jupyter.org/github/pybokeh/ipython_notebooks/blob/master/pandas/PandasCheatSheet.ipynb), a Python library for data manipulation; and [reading a few of our blog posts](https://www.onecodex.com/blog/) (where we plan to have nice demos with these notebooks). As always, also feel free to send us questions or suggestions by clicking the chat icon in the bottom right!\n",
+    "\n",
+    "Now we're going to dive right in and start crunching some numbers!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Fetching data\n",
+    "\n",
+    "To get started, we create an instance of our API, grab the DIABIMMUNE project, and download 500 samples from the cohort."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from onecodex import Api\n",
+    "\n",
+    "ocx = Api()\n",
+    "\n",
+    "project = ocx.Projects.get(\"d53ad03b010542e3\")  # get DIABIMMUNE project by ID\n",
+    "samples = ocx.Samples.where(project=project.id, public=True, limit=50)\n",
+    "\n",
+    "samples.metadata[[\n",
+    "    \"gender\",\n",
+    "    \"host_age\",\n",
+    "    \"geo_loc_name\",\n",
+    "    \"totalige\",\n",
+    "    \"eggs\",\n",
+    "    \"vegetables\",\n",
+    "    \"milk\",\n",
+    "    \"wheat\",\n",
+    "    \"rice\",\n",
+    "]]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Question #1: How does alpha diversity vary by sample group?\n",
+    "\n",
+    "Here, we display observed taxa, Simpson’s Index, and Shannon diversity side-by-side, grouped by the region of birth. Each group includes samples taken across the entire three-year longitudinal study.\n",
+    "\n",
+    "**Note:** Shannon diversity is calculated using log base ``e`` (natural log)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "observed_taxa = samples.plot_metadata(vaxis=\"observed_taxa\", haxis=\"geo_loc_name\", return_chart=True)\n",
+    "simpson = samples.plot_metadata(vaxis=\"simpson\", haxis=\"geo_loc_name\", return_chart=True)\n",
+    "shannon = samples.plot_metadata(vaxis=\"shannon\", haxis=\"geo_loc_name\", return_chart=True)\n",
+    "\n",
+    "observed_taxa | simpson | shannon"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from onecodex.notebooks.report import *\n",
+    "\n",
+    "ref_text = 'Roo, et al. \"How to Python.\" Nature, 2019.'\n",
+    "legend(f\"Alpha diversity by location of birth{reference(text=ref_text, label='roo1')}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Question #2: How does the microbiome change over time?\n",
+    "\n",
+    "The `plot_metadata` function can\n",
+    "search through all taxa in your samples and pull out read counts or relative abundances."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "samples.plot_metadata(haxis=\"host_age\", vaxis=\"Bacteroides\", plot_type=\"scatter\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Question #3: How does an individual subject's gut change over time?\n",
+    "\n",
+    "Here, we're going to drop into a dataframe, slice it to fetch all the data points from a single subject of the study, and generate a stacked bar plot. It's nice to see the expected high abundance of Bifidobacterium early in life, giving way to Bacteroides near age three!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# generate a dataframe containing relative abundances\n",
+    "df_rel = samples.to_df(rank=\"genus\")\n",
+    "\n",
+    "# fetch all samples for subject P014839\n",
+    "subject_metadata = samples.metadata.loc[samples.metadata[\"host_subject_id\"] == \"P014839\"]\n",
+    "subject_df = df_rel.loc[subject_metadata.index]\n",
+    "\n",
+    "# put them in order of sample date\n",
+    "subject_df = subject_df.loc[subject_metadata[\"host_age\"].sort_values().index]\n",
+    "\n",
+    "# you can access our library using the ocx accessor on pandas dataframes!\n",
+    "subject_df.ocx.plot_bargraph(\n",
+    "    rank=\"genus\",\n",
+    "    label=lambda metadata: str(metadata[\"host_age\"]),\n",
+    "    title=\"Subject P014839 Over Time\",\n",
+    "    xlabel=\"Host Age at Sampling Time (days)\",\n",
+    "    ylabel=\"Relative Abundance\",\n",
+    "    legend=\"Genus\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Question #4: Heatmaps?!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df_rel[:30].ocx.plot_heatmap(legend=\"Relative Abundance\", tooltip=\"geo_loc_name\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Question #5: How do samples cluster?\n",
+    "\n",
+    "First up, we'll plot a heatmap of weighted UniFrac distance between the first 30 samples in the dataset. This requires unnormalized read counts, so we'll generate a new, unnormalized dataframe."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# generate a dataframe containing read counts\n",
+    "df_abs = samples.to_df()\n",
+    "\n",
+    "df_abs[:30].ocx.plot_distance(metric=\"weighted_unifrac\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Question #6: Can I do PCA?"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "samples.plot_pca(color=\"geo_loc_name\", size=\"Bifidobacterium\", title=\"My PCoA Plot\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Question #6: Can I do something _better_ than PCA?"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "samples.plot_mds(\n",
+    "    metric=\"weighted_unifrac\", method=\"pcoa\", color=\"geo_loc_name\", title=\"My PCoA Plot\"\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "page_break()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bibliography()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.4"
+  },
+  "onecodex_notebook": true
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}

docs/notebooks.rst

@@ -0,0 +1,10 @@
+Notebooks
+---------
+
+Examples of interactive data analysis using the One Codex Python library with
+Jupyter Notebook.
+
+Example Notebooks
+^^^^^^^^^^^^^^^^^
+
+1. :doc:`Notebooks Demo <notebook_examples/notebooks_demo>`

docs/readme.md

@@ -0,0 +1,2 @@
+```{include} ../README.md
+```

docs/requirements.txt

@@ -0,0 +1,6 @@
+sphinx
+nbsphinx
+sphinx-rtd-theme
+myst-parser
+sphinxext-altair
+-e .[all,reports]

docs/sample_collection.rst

@@ -0,0 +1,73 @@
+****************
+SampleCollection
+****************
+
+Data export, analysis and visualization functions are all contained within the
+``SampleCollection`` class.
+
+A ``SampleCollection`` is returned whenever multiple Samples are returned via
+the One Codex API using a model.
+
+Usage
+=====
+
+``SampleCollection`` contains useful tools for data export, analysis,
+visualization and statistics. See the following sections for more information:
+
+- :doc:`Visualization <visualization>`
+- :doc:`Statistics <statistics>`
+- :doc:`Taxonomy <taxonomy>`
+
+.. code-block:: python
+
+   import onecodex
+
+   ocx = onecodex.Api()
+
+   project = ocx.Project.get("d53ad03b010542e3")
+   samples = ocx.Samples.where(project=project)
+
+   type(samples) # SampleCollection
+
+
+A ``SampleCollection`` can also be created manually from a list of samples:
+
+.. code-block:: python
+
+   import onecodex.models.collection.SampleCollection
+
+   sample_list = [
+       ocx.Samples.get("cee3b512605a43c6"),
+       ocx.Samples.get("01f703ac505e4a30")
+   ]
+
+   samples = SampleCollection(sample_list)
+
+   # convert classification results to a Pandas DataFrame
+   samples.to_df()
+
+
+``filter``
+==========
+
+.. automethod:: onecodex.models.collection.SampleCollection.filter
+
+``to_otu``
+==========
+
+.. automethod:: onecodex.models.collection.SampleCollection.to_otu
+
+``to_df``
+=========
+
+.. automethod:: onecodex.models.collection.SampleCollection.to_df
+
+``to_classification_df``
+=========================
+
+.. automethod:: onecodex.models.collection.SampleCollection.to_classification_df
+
+``to_functional_df``
+=====================
+
+.. automethod:: onecodex.models.collection.SampleCollection.to_functional_df

docs/statistics.rst

@@ -0,0 +1,39 @@
+**********
+Statistics
+**********
+
+.. admonition:: See Also
+   :class: note
+
+   Statistics functions are implemented as part of ``SampleCollection``. For
+   more information, see :doc:`sample_collection`.
+
+``aitchison_distance``
+======================
+
+.. automethod:: onecodex.models.collection.SampleCollection.aitchison_distance
+
+``alpha_diversity``
+===================
+
+.. automethod:: onecodex.models.collection.SampleCollection.alpha_diversity
+
+``alpha_diversity_stats``
+=========================
+
+.. automethod:: onecodex.models.collection.SampleCollection.alpha_diversity_stats
+
+``beta_diversity``
+==================
+
+.. automethod:: onecodex.models.collection.SampleCollection.beta_diversity
+
+``beta_diversity_stats``
+========================
+
+.. automethod:: onecodex.models.collection.SampleCollection.beta_diversity_stats
+
+``unifrac``
+===========
+
+.. automethod:: onecodex.models.collection.SampleCollection.unifrac

docs/taxonomy.rst

@@ -0,0 +1,24 @@
+********
+Taxonomy
+********
+
+.. admonition:: See Also
+   :class: note
+
+   Taxonomy functions are implemented as part of ``SampleCollection``. For more
+   information, see :doc:`sample_collection`.
+
+``tree_build``
+==============
+
+.. automethod:: onecodex.models.collection.SampleCollection.tree_build
+
+``tree_prune_rank``
+===================
+
+.. automethod:: onecodex.models.collection.SampleCollection.tree_prune_rank
+
+``tree_prune_tax_ids``
+======================
+
+.. automethod:: onecodex.models.collection.SampleCollection.tree_prune_tax_ids