From e4281bd13f2876c07977c72012b4d4c259286466 Mon Sep 17 00:00:00 2001 From: Johannes Soltwedel <38459088+jo-mueller@users.noreply.github.com> Date: Wed, 24 Jul 2024 16:17:52 +0200 Subject: [PATCH 1/2] Turn resources into Jupyter book --- root/docs/_config.yml | 2 ++ root/docs/_toc.yml | 6 ++++++ .../docs/instructions}/Transfer_dataset.md | 0 {notebooks => root/docs/notebooks}/synchronize_tags.ipynb | 0 {notebooks => root/docs/notebooks}/tag_collection.yaml | 0 5 files changed, 8 insertions(+) create mode 100644 root/docs/_config.yml create mode 100644 root/docs/_toc.yml rename {instructions => root/docs/instructions}/Transfer_dataset.md (100%) rename {notebooks => root/docs/notebooks}/synchronize_tags.ipynb (100%) rename {notebooks => root/docs/notebooks}/tag_collection.yaml (100%) diff --git a/root/docs/_config.yml b/root/docs/_config.yml new file mode 100644 index 0000000..6e68493 --- /dev/null +++ b/root/docs/_config.yml @@ -0,0 +1,2 @@ +title: "OMERO Tools" +author: "BiAPoL" diff --git a/root/docs/_toc.yml b/root/docs/_toc.yml new file mode 100644 index 0000000..214824f --- /dev/null +++ b/root/docs/_toc.yml @@ -0,0 +1,6 @@ +format: jb-book +root: index + +chapters: + - file: instructions/Transfer_dataset.md + - file: notebooks/synchronize_tags.ipynb diff --git a/instructions/Transfer_dataset.md b/root/docs/instructions/Transfer_dataset.md similarity index 100% rename from instructions/Transfer_dataset.md rename to root/docs/instructions/Transfer_dataset.md diff --git a/notebooks/synchronize_tags.ipynb b/root/docs/notebooks/synchronize_tags.ipynb similarity index 100% rename from notebooks/synchronize_tags.ipynb rename to root/docs/notebooks/synchronize_tags.ipynb diff --git a/notebooks/tag_collection.yaml b/root/docs/notebooks/tag_collection.yaml similarity index 100% rename from notebooks/tag_collection.yaml rename to root/docs/notebooks/tag_collection.yaml From 7fbdffdba3fd93f435206082e4ce20ee23099084 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20M=C3=BCller?= <38459088+jo-mueller@users.noreply.github.com> Date: Wed, 24 Jul 2024 16:40:18 +0200 Subject: [PATCH 2/2] convert to Jupyter-book --- .github/workflows/build_book.yml | 36 ++++++++++++++ .gitignore | 3 ++ docs/_config.yml | 12 +++++ docs/_toc.yml | 6 +++ docs/index.md | 12 +++++ .../instructions/transfer_dataset.md | 1 + .../notebooks/synchronize_tags.ipynb | 48 ++++++++++++++++++- .../notebooks/tag_collection.yaml | 0 root/docs/_config.yml | 2 - root/docs/_toc.yml | 6 --- 10 files changed, 117 insertions(+), 9 deletions(-) create mode 100644 .github/workflows/build_book.yml create mode 100644 docs/_config.yml create mode 100644 docs/_toc.yml create mode 100644 docs/index.md rename root/docs/instructions/Transfer_dataset.md => docs/instructions/transfer_dataset.md (98%) rename {root/docs => docs}/notebooks/synchronize_tags.ipynb (88%) rename {root/docs => docs}/notebooks/tag_collection.yaml (100%) delete mode 100644 root/docs/_config.yml delete mode 100644 root/docs/_toc.yml diff --git a/.github/workflows/build_book.yml b/.github/workflows/build_book.yml new file mode 100644 index 0000000..a654457 --- /dev/null +++ b/.github/workflows/build_book.yml @@ -0,0 +1,36 @@ +name: deploy-book + +# Only run this when the master branch changes +on: + push: + branches: + - master + - main + +# This job installs dependencies, build the book, and pushes it to `gh-pages` +jobs: + deploy-book: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + # Install dependencies + - name: Set up Python 3.9 + uses: actions/setup-python@v4 + with: + python-version: 3.9 + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r ./docs/requirements.txt + # Build the book + - name: Build the book + run: | + jupyter-book build docs/ + # Push the book's HTML to github-pages + - name: GitHub Pages action + uses: peaceiris/actions-gh-pages@v3.5.9 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html diff --git a/.gitignore b/.gitignore index 82f9275..0a1bf19 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,9 @@ __pycache__/ # C extensions *.so +# exclude _build directory +_build/ + # Distribution / packaging .Python build/ diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..8a41061 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,12 @@ +title: "OMERO Tools" +author: "BiAPoL" + +execute: + execute_notebooks: off + +sphinx: + extra_extensions: + - 'sphinx.ext.autodoc' + - 'sphinx.ext.napoleon' + - 'sphinx.ext.viewcode' + - 'sphinx.ext.autosummary' diff --git a/docs/_toc.yml b/docs/_toc.yml new file mode 100644 index 0000000..592d77d --- /dev/null +++ b/docs/_toc.yml @@ -0,0 +1,6 @@ +format: jb-book +root: index + +chapters: + - file: instructions/transfer_dataset + - file: notebooks/synchronize_tags diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..5b09d9d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,12 @@ +# Omero-tools + +This repository contains a collection of tools for working with OMERO. Such tools can be working with the OMERO command line interface to [transfer datasets between repositories](OMERO.transfer_dataset), etc. If you find anything to be missing, please feel free to contribute to this repository or open an issue. + +## Contributions + +Contributions are welcome! Please feel free to open an issue or a pull request if you have any suggestions or improvements. To build the jupyter book on your local machine, you can use the following commands: + +```bash +pip install -r jupyter-book +jupyter-book build docs +``` \ No newline at end of file diff --git a/root/docs/instructions/Transfer_dataset.md b/docs/instructions/transfer_dataset.md similarity index 98% rename from root/docs/instructions/Transfer_dataset.md rename to docs/instructions/transfer_dataset.md index e157a4a..643847d 100644 --- a/root/docs/instructions/Transfer_dataset.md +++ b/docs/instructions/transfer_dataset.md @@ -1,3 +1,4 @@ +(OMERO.transfer_dataset)= # How to transfer a dataset between two omero instances It is a common task to transfer a dataset between two omero instances. This can be done using the OMERO API. The following steps will guide you through the process. Consider the following example: The dataset with id `dataset_id` is to be transferred from the source omero instance to the target omero instance. diff --git a/root/docs/notebooks/synchronize_tags.ipynb b/docs/notebooks/synchronize_tags.ipynb similarity index 88% rename from root/docs/notebooks/synchronize_tags.ipynb rename to docs/notebooks/synchronize_tags.ipynb index 2f6ef80..44d6a34 100644 --- a/root/docs/notebooks/synchronize_tags.ipynb +++ b/docs/notebooks/synchronize_tags.ipynb @@ -1,8 +1,23 @@ { "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Synchronize tags across groups\n", + "\n", + "To make sure that there is some standardization across projects with regard to how data is tagged and annotated, we need to synchronize tags across groups. The goal is to make sure that the tags used in the data are consistent across groups. This will make it easier to search for data and to use the data in the future. The defined tags themselves are based off of the [REMBI metadata schema](https://www.nature.com/articles/s41592-021-01166-8). More specifically, we orient ourselves on the tags used in the [provided spreadsheet](https://docs.google.com/spreadsheets/d/1Ck1NeLp-ZN4eMGdNYo2nV6KLEdSfN6oQBKnnWU6Npeo/edit).\n", + "\n", + "\n", + "To install the necessary packages, run the following command:\n", + "```bash\n", + "mamba install omero-py ezomero -c bioconda\n", + "```" + ] + }, { "cell_type": "code", - "execution_count": 1, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ @@ -15,6 +30,16 @@ "import yaml" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "\n", + "# Prerequisites\n", + "\n", + "We create user that is called `tag-man` and make sure that this user is member of all groups to which we want to synchronize tags. We then add these groups to the groups we want to synchronize." + ] + }, { "cell_type": "code", "execution_count": 6, @@ -32,6 +57,13 @@ "TARGET_GROUPS = ['BiAPoL', 'Campas Lab', 'Dye Lab']" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We need some utility functions to read tags from a tagset and to write tags to a tagset. We also need a function to synchronize tags across groups." + ] + }, { "cell_type": "code", "execution_count": 3, @@ -91,6 +123,13 @@ " return tag_names" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Lastly, this function will be called and iterates over every group that is part of the synchronization process (see above) and synchronizes the tags. For this, it checks existing tags and tagsets. If there is a tag that exists in the [local collection of tags](tag_collection.yaml) but doesn't exist in the remote tagset, it will be added. If a tag exists remotely but not locally in the preset collection, nothing happens. This makes sure that users can add their own individual tags to the tagmanager without them being overwritten by the synchronization process." + ] + }, { "cell_type": "code", "execution_count": 4, @@ -152,6 +191,13 @@ " #conn.getUpdateService().saveAndReturnObject(link)" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let's show all the tagsets and tags in our local collection and then synchronize them across groups." + ] + }, { "cell_type": "code", "execution_count": 7, diff --git a/root/docs/notebooks/tag_collection.yaml b/docs/notebooks/tag_collection.yaml similarity index 100% rename from root/docs/notebooks/tag_collection.yaml rename to docs/notebooks/tag_collection.yaml diff --git a/root/docs/_config.yml b/root/docs/_config.yml deleted file mode 100644 index 6e68493..0000000 --- a/root/docs/_config.yml +++ /dev/null @@ -1,2 +0,0 @@ -title: "OMERO Tools" -author: "BiAPoL" diff --git a/root/docs/_toc.yml b/root/docs/_toc.yml deleted file mode 100644 index 214824f..0000000 --- a/root/docs/_toc.yml +++ /dev/null @@ -1,6 +0,0 @@ -format: jb-book -root: index - -chapters: - - file: instructions/Transfer_dataset.md - - file: notebooks/synchronize_tags.ipynb