Adding Docs Workflow

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+# This pipeline builds the documentation.
+name: docs
+
+on:
+  push:
+    branches: [ main ]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+          cache: "pip"
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          version: "1.3.2"
+      - name: Cache dependencies
+        id: cache-deps
+        uses: actions/cache@v2
+        with:
+          path: .venv
+          key: pydeps-${{ hashFiles('**/poetry.lock') }}
+      - name: Install the dependencies
+        run: poetry install --no-interaction --no-root --with dev
+        if: steps.cache-deps.outputs.cache-hit != 'true'
+      - name: Install the module
+        run: poetry install --with dev --no-interaction
+      - name: Generate the documentation
+        run: poetry run mkdocs gh-deploy --force

docs/api/analyze.md

@@ -0,0 +1,8 @@
+# Analyze
+
+::: pyggdrasil.analyze.rhats
+::: pyggdrasil.analyze.ess
+::: pyggdrasil.analyze.Metrics
+::: pyggdrasil.analyze.to_pure_mcmc_data
+::: pyggdrasil.analyze.check_run_for_tree
+::: pyggdrasil.analyze.analyze_mcmc_run

docs/api/distances.md

@@ -0,0 +1,13 @@
+# Distances
+
+::: pyggdrasil.distances.TreeDistance
+::: pyggdrasil.distances.TreeSimilarity
+::: pyggdrasil.distances.TreeSimilarityMeasure
+::: pyggdrasil.distances.calculate_distance_matrix
+::: pyggdrasil.distances.AncestorDescendantSimilarity
+::: pyggdrasil.distances.MP3Similarity
+::: pyggdrasil.distances.AncestorDescendantSimilarityInclRoot
+::: pyggdrasil.distances.DifferentLineageSimilarity
+::: pyggdrasil.distances.MLTDSimilarity
+
+

docs/api/index.md

@@ -0,0 +1,15 @@
+# API
+
+- [Analyze](analyze.md) provides analysis tools of tree samples and inference runs.
+- [Distances](distances.md) provides tree-tree distance and similarity measures.
+- [Interface](interface.md) provides dataclasses for processing MCMC data.
+- [Serialize](serialize.md) contains utilities for serialization and  deserialization of trees, MCMC rus and analysis.
+- [Tree Inference](tree_inference.md) implements the mutation tree infernce; scDNA mutation profiles synthesis.
+- [Visualize](visualize.md) implements visualization of trees and MCMC runs and diagostics theirof.
+
+This package handels trees with _Anytree_, see our adaption in the class _TreeNode_ below.  For the inference we convert trees to binary adjacency matrices see [Tree Inference](tree_inference.md), for reasons of performance.
+
+::: pyggdrasil.TreeNode
+::: pyggdrasil.compare_trees
+
+

docs/api/interface.md

@@ -0,0 +1,7 @@
+# Interface
+
+::: pyggdrasil.interface.PureMcmcData
+
+
+
+

docs/api/serialize.md

@@ -0,0 +1,11 @@
+# Serialize
+
+::: pyggdrasil.serialize.serialize_tree_to_dict
+::: pyggdrasil.serialize.deserialize_tree_from_dict
+::: pyggdrasil.serialize.read_mcmc_samples
+::: pyggdrasil.serialize.save_mcmc_sample
+::: pyggdrasil.serialize.read_tree_node
+::: pyggdrasil.serialize.save_tree_node
+::: pyggdrasil.serialize.save_metric_result
+::: pyggdrasil.serialize.read_metric_result
+

docs/api/tree_inference.md

@@ -0,0 +1,28 @@
+# Tree Inference
+
+::: pyggdrasil.tree_inference.CellAttachmentStrategy
+::: pyggdrasil.tree_inference.CellSimulationData
+::: pyggdrasil.tree_inference.CellSimulationId
+::: pyggdrasil.tree_inference.CellSimulationModel
+::: pyggdrasil.tree_inference.ErrorCombinations
+::: pyggdrasil.tree_inference.ErrorRates
+::: pyggdrasil.tree_inference.evolve_tree_mcmc
+::: pyggdrasil.tree_inference.evolve_tree_mcmc_all
+::: pyggdrasil.tree_inference.gen_sim_data
+::: pyggdrasil.tree_inference.get_descendants
+::: pyggdrasil.tree_inference.get_simulation_data
+::: pyggdrasil.tree_inference.huntress_tree_inference
+::: pyggdrasil.tree_inference.make_tree
+::: pyggdrasil.tree_inference.McmcConfig
+::: pyggdrasil.tree_inference.McmcConfigOptions
+::: pyggdrasil.tree_inference.McmcRunId
+::: pyggdrasil.tree_inference.mcmc_sampler
+::: pyggdrasil.tree_inference.MoveProbabilities
+::: pyggdrasil.tree_inference.MoveProbConfig
+::: pyggdrasil.tree_inference.MoveProbConfigOptions
+::: pyggdrasil.tree_inference.MutationDataId
+::: pyggdrasil.tree_inference.MutationMatrix
+::: pyggdrasil.tree_inference.Tree
+::: pyggdrasil.tree_inference.TreeId
+::: pyggdrasil.tree_inference.TreeType
+

docs/api/visualize.md

@@ -0,0 +1,11 @@
+# Visualize
+
+::: pyggdrasil.visualize.plot_tree
+::: pyggdrasil.visualize.save_metric_iteration
+::: pyggdrasil.visualize.save_log_p_iteration
+::: pyggdrasil.visualize.plot_tree_mcmc_sample
+::: pyggdrasil.visualize.plot_tree_no_print
+::: pyggdrasil.visualize.save_top_trees_plots
+::: pyggdrasil.visualize.save_rhat_iteration
+::: pyggdrasil.visualize.save_rhat_iteration_AD_DL
+::: pyggdrasil.visualize.save_ess_iteration_AD_DL

docs/contributing.md

@@ -0,0 +1,93 @@
+# Contributing
+
+Thank you for your time to contribute to this project!
+Below we present some guidelines.
+
+## Reporting a bug
+
+If you find a bug, please [submit a new issue](https://github.com/cbg-ethz/PYggdrasil/issues).
+
+To be able to reproduce a bug, we will usually need the following information:
+
+  - Versions of Python packages used (in particular version of this library).
+  - A minimal code snippet allowing us to reproduce the bug.
+  - What is the desired behaviour in the reported case?
+  - What is the actual behaviour?
+
+
+## Submitting a pull request
+
+**Do:**
+
+  - Do use [Google Style Guide](https://google.github.io/styleguide/pyguide.html). We use [black](https://github.com/psf/black) for code formatting.
+  - Do write unit tests. We use [pytest](https://docs.pytest.org/).
+  - Do write docstrings. We use [Material for Mkdocs](https://squidfunk.github.io/mkdocs-material/) to generate the documentation.
+  - Do write high-level documentation as examples and tutorials, illustrating introduced features.
+  - Do consider submitting a *draft* pull request with a description of proposed changes.
+  - Do check the [Development section](#development).
+
+**Don't:**
+
+  - Don't include license information. This project is MIT licensed and by submitting your pull request you implicitly and irrevocably agree to use this.
+  - Don't implement too many ideas in a single pull request. Multiple features should be implemented in separate pull requests.
+
+
+## Development
+
+### Workflow
+
+We use [Feature Branch Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow),
+in which modifications of the code should happen via small pull requests.
+
+We recommend submitting small pull requests and starting with drafts outlining proposed changes.
+
+### Installation & dependencies
+To install the repository together with the dependencies run:
+```
+$ git clone [email protected]:cbg-ethz/PYggdrasil.git  # Clone the repository
+$ poetry install --with dev                         # Install the dependencies
+$ poetry run pre-commit install                     # Install pre-commit hooks
+$ poetry run pytest                                 # Check if unit tests are passing
+```
+
+
+### Testing & Checking
+
+Then, you will be able to run tests:
+```bash
+$ poetry run pytest
+```
+... or check the types:
+```bash
+$ poetry run pyright
+```
+
+### Existing code quality checks
+The code quality checks run during on GitHub can be seen in ``.github/workflows/test.yml``.
+
+We are using:
+  - [Ruff](https://github.com/charliermarsh/ruff) to lint the code.
+  - [Black](https://github.com/psf/black) to format the code.
+  - [Pyright](https://github.com/microsoft/pyright) to check the types.
+  - [Pytest](https://docs.pytest.org/) to run the unit tests.
+  - [Interrogate](https://interrogate.readthedocs.io/) to check the documentation.
+
+Alternatively, you may prefer to work with the right Python environment using:
+```bash
+$ poetry shell
+$ pytest
+```
+
+### Building documentation locally
+You can build the documentation on your machine using:
+```
+$ poetry run mkdocs serve
+```
+and opening the generated link using web browser.
+
+### Code organisation
+
+- The package code is in ``src/pyggdrasil/`` and is partitioned into subpackages.
+- The unit tests are in ``tests/`` and the structure of this directory should reflect the one of the package.
+- Experimental workflows are in ``workflows/``, with a description of how to set up the environment in ``workflows/README.md``
+

docs/index.md

@@ -0,0 +1 @@
+../README.md

docs/tutorial/index.md

@@ -0,0 +1,9 @@
+# Tutorials
+
+We'd love to see you built upon PYggdrasil. Below we provide some tutorials to help you get started.
+
+## Functional Usage
+
+- [Single MCMC Run](singleMCMC.md) demonstrated how to run a single MCMC chain.
+
+## Experimental Workflows