From 594fa90dcd581806a337a0a16396990945cc545f Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Fri, 27 Oct 2023 16:56:37 -0700 Subject: [PATCH 01/20] Upgrade docs --- .github/workflows/docs.yml | 1 + bioio/writers/timeseries_writer.py | 6 +- bioio/writers/two_d_writer.py | 8 +-- docs/CODE_OF_CONDUCT.md | 73 +++++++++++++++++++ CONTRIBUTING.md => docs/CONTRIBUTING.md | 30 +++++--- docs/GOVERNANCE.md | 93 +++++++++++++++++++++++++ docs/MISSION_AND_VALUES.md | 82 ++++++++++++++++++++++ docs/developer_resources.rst | 16 +++++ docs/index.rst | 26 ++++++- pyproject.toml | 1 + 10 files changed, 312 insertions(+), 24 deletions(-) create mode 100644 docs/CODE_OF_CONDUCT.md rename CONTRIBUTING.md => docs/CONTRIBUTING.md (72%) create mode 100644 docs/GOVERNANCE.md create mode 100644 docs/MISSION_AND_VALUES.md create mode 100644 docs/developer_resources.rst diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e88e059..8e64dc6 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -24,6 +24,7 @@ jobs: pip install .[docs] - name: Generate Docs run: | + gitchangelog just generate-docs touch docs/_build/.nojekyll - name: Publish Docs diff --git a/bioio/writers/timeseries_writer.py b/bioio/writers/timeseries_writer.py index 2b85656..dd6c94f 100644 --- a/bioio/writers/timeseries_writer.py +++ b/bioio/writers/timeseries_writer.py @@ -19,10 +19,6 @@ class TimeseriesWriter(Writer): """ A writer for timeseries Greyscale, RGB, or RGBA image data. Primarily directed at formats: "gif", "mp4", "mkv", etc. - - Notes - ----- - To use this writer, install with: `pip install aicsimageio[base-imageio]`. """ _TIMEPOINT_DIMENSIONS = [ @@ -124,7 +120,7 @@ def save( a non-time dimension. For example, creating a timeseries image where each frame is a Z-plane from a source volumetric image as seen below. - >>> image = AICSImageIO("some_z_stack.ome.tiff") + >>> image = BioImage("some_z_stack.ome.tiff") ... TimeseriesWriter.save( ... data=image.get_image_data("ZYX", T=0, C=0), ... uri="some_z_stack.mp4", diff --git a/bioio/writers/two_d_writer.py b/bioio/writers/two_d_writer.py index eca56b0..803adc6 100644 --- a/bioio/writers/two_d_writer.py +++ b/bioio/writers/two_d_writer.py @@ -18,10 +18,6 @@ class TwoDWriter(Writer): Primarily directed at formats: "png", "jpg", etc. This is primarily a passthrough to imageio.imwrite. - - Notes - ----- - To use this writer, install with: `pip install aicsimageio[base-imageio]`. """ _PLANE_DIMENSIONS = [ @@ -90,8 +86,8 @@ def save( The dimension order of the provided data. Default: None. Based off the number of dimensions, will assume the dimensions similar to how - aicsimageio.readers.default_reader.DefaultReader reads in - data. That is, two dimensions: YX and three dimensions: YXS. + https://github.com/bioio-devs/bioio-imageio/blob/main/bioio_imageio/reader.py + reads in data. That is, two dimensions: YX and three dimensions: YXS. fs_kwargs: Dict[str, Any] Any specific keyword arguments to pass down to the fsspec created filesystem. diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..b7f7e5e --- /dev/null +++ b/docs/CODE_OF_CONDUCT.md @@ -0,0 +1,73 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting any of the contributors from the Allen Institute and +we will attempt to resolve the issues with respect and dignity. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq diff --git a/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 72% rename from CONTRIBUTING.md rename to docs/CONTRIBUTING.md index ce440df..f900bb4 100644 --- a/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -79,15 +79,25 @@ Available recipes: ## Deploying A reminder for the maintainers on how to deploy. -Make sure the main branch is checked out and all desired changes -are merged. Then run: +1) Make sure all your changes are committed and merged into main. +2) Make sure branch is clean: + ```bash + git checkout main + git stash + git pull + ``` +3) Create tag and push new version to GitHub like so: + ```bash + just tag-for-release "vX.Y.Z" + just release + ``` +4) Wait for a [GitHub Action](https://github.com/bioio-devs/bioio/actions) to automatically publish to [PyPI](https://pypi.org/project/bioio/) +5) [Create GitHub release](https://github.com/bioio-devs/bioio/releases/new) for the corresponding version created. -```bash -just tag-for-release "vX.Y.Z" -just release -``` + 6a) Select tag for version created + + 6b) Ensure GitHub automatically generates releases notes ([click "Generate Release Notes"](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)) + + 6c) Double check format is similar to previous releases -The presence of a tag starting with "v" will trigger the `publish` step in the -main github workflow, which will build the package and upload it to PyPI. The -version will be injected into the package metadata by -[`setuptools-scm`](https://github.com/pypa/setuptools_scm) + 6d) Publish release diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md new file mode 100644 index 0000000..3fdfc2d --- /dev/null +++ b/docs/GOVERNANCE.md @@ -0,0 +1,93 @@ +# Governance Model + +## Abstract + +The purpose of this document is to formalize the governance process used by the +`bioio` project, to clarify how decisions are made and how the various +elements of our community interact. + +This is a consensus-based community project. Anyone with an interest in the +project can join the community, contribute to the project design, and +participate in the decision making process. This document describes how that +participation takes place, how to find consensus, and how deadlocks are +resolved. + +## Roles And Responsibilities + +### The Community + +The bioio community consists of anyone using or working with the project +in any way. + +### Contributors + +A community member can become a contributor by interacting directly with the +project in concrete ways, such as: + +- proposing a change to the code via a + [GitHub pull request](https://github.com/bioio-devs/bioio/pulls); +- reporting issues on our + [GitHub issues page](https://github.com/bioio-devs/bioio/issues); +- proposing a change to the documentation via a + [GitHub pull request](https://github.com/bioio-devs/bioio/pulls); +- discussing the design of bioio on existing + [issues](https://github.com/bioio-devs/bioio/issues) and / or + [pull requests](https://github.com/bioio-devs/bioio/pulls); +- reviewing [open pull requests](https://github.com/bioio-devs/bioio/pulls) + +among other possibilities. Any community member can become a contributor, and +all are encouraged to do so. By contributing to the project, community members +can directly help to shape its future. + +Contributors are encouraged to read the [contributing guide](./CONTRIBUTING.md). + +### Core developers + +Core developers are community members that have demonstrated continued +commitment to the project through ongoing contributions. They +have shown they can be trusted to maintain bioio with care. Becoming a +core developer allows contributors to merge approved pull requests, cast votes +for and against merging a pull-request, and be involved in deciding major +changes to the API, and thereby more easily carry on with their project related +activities. Core developers appear as team members on our +[@bioio-devs/trusted-developers](https://github.com/orgs/bioio-devs/teams/trusted-developers) +GitHub team. Core developers are asked to review code contributions. New core +developers can be nominated by any existing core developer. + +### Steering Council + +The Steering Council (SC) members are core developers who have additional +responsibilities to ensure the smooth running of the project. SC members are +expected to participate in strategic planning, approve changes to the +governance model. The purpose of the SC is to ensure smooth progress from the big +picture perspective. Changes that impact the full project require analysis informed by +long experience with both the project and the larger ecosystem. When the core +developer community (including the SC members) fails to reach such a consensus +in a reasonable time-frame, the SC is the entity that resolves the issue. + +The steering council is currently fixed to only include members directly from Allen +Institute for Cell Science. This may be changed in the future, but this results in the +steering council currently consisting of: + +- [Eva Maxfield Brown](https://github.com/evamaxfield) +- [Daniel Toloudis](https://github.com/toloudis) + +New members are added by nomination by a core developer. Nominees should have +demonstrated long-term, continued commitment to the project and its +[mission and values](./MISSION_AND_VALUES.md). + +## Decision Making Process + +Decisions about the future of the project are made through discussion with all +members of the community. All non-sensitive project management discussion takes +place on the [issue tracker](https://github.com/bioio-devs/bioio/issues). +Occasionally, sensitive discussion may occur through a private core developer channel. + +Decisions should be made in accordance with the +[mission and values](./MISSION_AND_VALUES.md) of the bioio project. + +bioio uses a “consensus seeking” process for making decisions. The group +tries to find a resolution that has no open objections among core developers. +Core developers are expected to distinguish between fundamental objections to a +proposal and minor perceived flaws that they can live with, and not hold up the +decision-making process for the latter. diff --git a/docs/MISSION_AND_VALUES.md b/docs/MISSION_AND_VALUES.md new file mode 100644 index 0000000..2c56081 --- /dev/null +++ b/docs/MISSION_AND_VALUES.md @@ -0,0 +1,82 @@ +# Mission and Values + +This document is meant to help guide decisions about the future of bioio, be it +in terms of whether to accept new functionality, changes to existing functionality, +changes to package administrative tasks, etc. It serves as a reference for core +developers in guiding their work, and, as an introduction for newcomers who want to +learn where the project is headed and what the team's values are. You can also learn +how the project is managed by looking at our [governance model](./GOVERNANCE.md). + +## Mission + +bioio aims to provide a **consistent intuitive API for reading in or out-of-memory +image pixel data and metadata** for the many existing proprietary microscopy file +formats, and, an **easy-to-use API for converting from proprietary file formats to an +open, common, standard** -- all using either language agnostic or pure Python tooling. + +In short: +> bioio provides a method to fully read and convert from an existing proprietary +> microscopy file format to, or _emulate_, a Python representation of the community +> standard metadata model regardless of image size, format, or location. + +(The current community standard for microscopy images is the +[Open Microscopy Environment](https://www.openmicroscopy.org/)) + +We hope to accomplish this by: +* being **easy to use and install**. We will take extra care to ensure that this library +is easy to use and fully installable on Windows, Mac-OS, and Ubuntu. +* being **well-documented** with our entire API having up-to-date, useful docstrings +and additionally providing examples of more complex use-cases when possible. +* providing a **consistent and stable API** to users by following +[semantic versioning](https://semver.org/) and limiting the amount of breaking changes +introduced unless necessary for the future robustness or scalability of the library. +* sustaining **comparable or better performance when compared to more tailored file +format reading libraries**. We will regularly run benchmarks utilizing a set of varied +size images from all the file formats the library is capable of reading. +* **working closely with the microscopy community** while deciding on standards and best +practices for open, accessible, file formats and imaging and in deciding which +proprietary file formats and metadata selection are in need of support. + +## Values +* We are **inclusive**. We welcome and mentor newcomers who are making their first +contribution and strive to grow our most dedicated contributors into core developers. We +have a [Code of Conduct](./CODE_OF_CONDUCT.md) to ensure that the bioio remains +a welcoming place for all. +* We are **community-driven**. We respond to feature requests and proposals on our +[issue tracker](https://github.com/bioio-devs/bioio/issues) and make +decisions that are driven by our user's requirements. +* We focus on **file IO and metadata conversion**, leaving image analysis functionality +and visualization to other libraries. +* We aim to **develop new methods of metadata extraction and conversion**, instead of +duplicating existing, or porting, from other libraries primarily by creating **language +agnostic methods** for metadata manipulation. +* We value **simple, readable implementations**. Readable code that is easy to +understand, for newcomers and maintainers alike, makes it easier to contribute new code +as well as prevent bugs. +* We value **education and documentation**. All functions should have docstrings, +preferably with examples, and major functionality should be explained in our tutorials. +Core developers can take an active role in finishing documentation examples. +* We **minimize [magic](https://en.wikipedia.org/wiki/Magic_(programming))** and always +provide a way for users to opt out of magical behaviour and guessing by providing +explicit ways to control functionality. + +## Acknowledgments +We share a lot of our mission and values with the `napari` project, and acknowledge the +influence of their mission and values statement on this document. + +Additionally, much of the work produced for this library is built on the shoulders of +giants. Notably: +* [Christoph Gohlke](https://www.lfd.uci.edu/~gohlke/) -- maintainer of `tifffile`, +`czifile`, and the `imagecodecs` libraries +* [Paul Watkins](https://github.com/elhuhdron) -- original creator of `pylibczi` +* [OME and Bio-Formats Team](https://github.com/ome/bioformats) -- proprietary +microscopy file format conversion and standards development +* [Python-Bio-Formats Team](https://github.com/CellProfiler/python-bioformats) -- +Python Java Bridge for Bio-Formats and original implementations of OME Python +representation +* [imageio Team](https://github.com/imageio/imageio) -- robust, expansive, cross +platform image reading +* [Dask Team](https://dask.org/) -- delayed and out-of-memory parallel array +manipulation +* [xarray Team](https://github.com/pydata/xarray) -- coordinate and metadata attached +array handling and manipulation diff --git a/docs/developer_resources.rst b/docs/developer_resources.rst new file mode 100644 index 0000000..489db0c --- /dev/null +++ b/docs/developer_resources.rst @@ -0,0 +1,16 @@ +Developer Resources +=================== + +A compiled list of resources for new and existing developers and maintainers of the +library. If you believe a document or information is missing please check our +`issue tracker `_. + +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: Contents: + + Contributing + Code of Conduct + Governance Model + Mission and Values diff --git a/docs/index.rst b/docs/index.rst index 6ce6de6..698f30e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,8 +7,28 @@ Welcome to bioio's documentation! :caption: Contents: Overview - installation - Package modules - contributing + Installation + Full API Reference + Developer Resources + Changelog .. mdinclude:: ../README.md + +Specific Doc Pages +================== + +.. autosummary:: + :toctree: + :caption: Important Classes: + + bioio.BioImage + bioio.writers.OmeTiffWriter + bioio.writers.OmeZarrWriter + bioio.writers.TimeseriesWriter + bioio.writers.TwoDWriter + +Indices and tables +================== +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/pyproject.toml b/pyproject.toml index e4c9ae1..f958587 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -61,6 +61,7 @@ test = [ ] docs = [ # Sphinx + Doc Gen + Styling + "gitchangelog>=3.0.4", "m2r2>=0.2.7", "Sphinx>=4.0.0", "furo>=2022.4.7", From 155c4a60c0ee4200dd5c039061aa1493228085c9 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Mon, 30 Oct 2023 12:53:10 -0700 Subject: [PATCH 02/20] Add auto-generated changelog --- .gitchangelog.rc | 293 +++++++++++++++++++++++++++++++++++++++++++++ docs/CHANGELOG.rst | 2 + pyproject.toml | 1 + 3 files changed, 296 insertions(+) create mode 100644 .gitchangelog.rc create mode 100644 docs/CHANGELOG.rst diff --git a/.gitchangelog.rc b/.gitchangelog.rc new file mode 100644 index 0000000..b29f383 --- /dev/null +++ b/.gitchangelog.rc @@ -0,0 +1,293 @@ +# -*- coding: utf-8; mode: python -*- +## +## Format +## +## ACTION: COMMIT_MSG [!TAG ...] +## +## Description +## +## ACTION is one of 'feature', 'bugfix', 'other' +## +## COMMIT_MSG is ... well ... the commit message itself. +## +## TAGs are additionnal adjective as 'refactor' 'minor' 'cosmetic' +## +## They are preceded with a '!' or a '@' (prefer the former, as the +## latter is wrongly interpreted in github.) Commonly used tags are: +## +## 'refactor' is obviously for refactoring code only +## 'minor' is for a very meaningless change (a typo, adding a comment) +## 'cosmetic' is for cosmetic driven change (re-indentation, 80-col...) +## 'wip' is for partial functionality but complete subfunctionality. +## +## Example: +## +## feature/use-dask +## +## Please note that multi-line commit message are supported, and only the +## first line will be considered as the "summary" of the commit message. So +## tags, and other rules only applies to the summary. The body of the commit +## message will be displayed in the changelog without reformatting. + + +## +## ``ignore_regexps`` is a line of regexps +## +## Any commit having its full commit message matching any regexp listed here +## will be ignored and won't be reported in the changelog. +## +ignore_regexps = [ + r'^(.{3,3}\s*:)?\s*[fF]irst commit.?\s*$', + r'^[iI]ntial commit.?\s*$', + r'^$', ## ignore commits with empty messages + r'^Bump version: .*', +] + + +## ``section_regexps`` is a list of 2-tuples associating a string label and a +## list of regexp +## +## Commit messages will be classified in sections thanks to this. Section +## titles are the label, and a commit is classified under this section if any +## of the regexps associated is matching. +## +## Please note that ``section_regexps`` will only classify commits and won't +## make any changes to the contents. So you'll probably want to go check +## ``subject_process`` (or ``body_process``) to do some changes to the subject, +## whenever you are tweaking this variable. +## +section_regexps = [ + ('New', [ + r'^[fF]eature.*$' + ]), + ('Fix', [ + r'^[bB]ugfix.*$', + r'^[fF]ix.*$', + r'^[hH]otfix.*$', + ]), + ('Other', None), ## Match all lines +] + + +## ``body_process`` is a callable +## +## This callable will be given the original body and result will +## be used in the changelog. +## +## Available constructs are: +## +## - any python callable that take one txt argument and return txt argument. +## +## - ReSub(pattern, replacement): will apply regexp substitution. +## +## - Indent(chars=" "): will indent the text with the prefix +## Please remember that template engines gets also to modify the text and +## will usually indent themselves the text if needed. +## +## - Wrap(regexp=r"\n\n"): re-wrap text in separate paragraph to fill 80-Columns +## +## - noop: do nothing +## +## - ucfirst: ensure the first letter is uppercase. +## (usually used in the ``subject_process`` pipeline) +## +## - final_dot: ensure text finishes with a dot +## (usually used in the ``subject_process`` pipeline) +## +## - strip: remove any spaces before or after the content of the string +## +## - SetIfEmpty(msg="No commit message."): will set the text to +## whatever given ``msg`` if the current text is empty. +## +## Additionally, you can `pipe` the provided filters, for instance: +#body_process = Wrap(regexp=r'\n(?=\w+\s*:)') | Indent(chars=" ") +#body_process = Wrap(regexp=r'\n(?=\w+\s*:)') +#body_process = noop +#body_process = ReSub(r'((^|\n)[A-Z]\w+(-\w+)*: .*(\n\s+.*)*)+$', r'') | strip +body_process = ReSub(r'.*', '') | strip + + +## ``subject_process`` is a callable +## +## This callable will be given the original subject and result will +## be used in the changelog. +## +## Available constructs are those listed in ``body_process`` doc. +#subject_process = (strip | +# ReSub(r'^([cC]hg|[fF]ix|[nN]ew)\s*:\s*((dev|use?r|pkg|test|doc)\s*:\s*)?([^\n@]*)(@[a-z]+\s+)*$', r'\4') | +# SetIfEmpty("No commit message.") | ucfirst | final_dot) +subject_process = ReSub( + r'^(.*)(\ ?\(\#([0-9]+)\))$', + r'\1 (`#\3 `_)' +) +#subject_process = ReSub(r'.*', '') + + +## ``tag_filter_regexp`` is a regexp +## +## Tags that will be used for the changelog must match this regexp. +## +tag_filter_regexp = r'^v[0-9]+\.[0-9]+(\.[0-9]+)?$' + + +## ``unreleased_version_label`` is a string or a callable that outputs a string +## +## This label will be used as the changelog Title of the last set of changes +## between last valid tag and HEAD if any. +unreleased_version_label = "(unreleased)" + + +## ``output_engine`` is a callable +## +## This will change the output format of the generated changelog file +## +## Available choices are: +## +## - rest_py +## +## Legacy pure python engine, outputs ReSTructured text. +## This is the default. +## +## - mustache() +## +## Template name could be any of the available templates in +## ``templates/mustache/*.tpl``. +## Requires python package ``pystache``. +## Examples: +## - mustache("markdown") +## - mustache("restructuredtext") +## +## - makotemplate() +## +## Template name could be any of the available templates in +## ``templates/mako/*.tpl``. +## Requires python package ``mako``. +## Examples: +## - makotemplate("restructuredtext") +## +output_engine = rest_py +#output_engine = mustache("restructuredtext") +#output_engine = mustache("markdown") +#output_engine = makotemplate("restructuredtext") + + +## ``include_merge`` is a boolean +## +## This option tells git-log whether to include merge commits in the log. +## The default is to include them. +include_merge = False + + +## ``log_encoding`` is a string identifier +## +## This option tells gitchangelog what encoding is outputed by ``git log``. +## The default is to be clever about it: it checks ``git config`` for +## ``i18n.logOutputEncoding``, and if not found will default to git's own +## default: ``utf-8``. +#log_encoding = 'utf-8' + + +## ``publish`` is a callable +## +## Sets what ``gitchangelog`` should do with the output generated by +## the output engine. ``publish`` is a callable taking one argument +## that is an interator on lines from the output engine. +## +## Some helper callable are provided: +## +## Available choices are: +## +## - stdout +## +## Outputs directly to standard output +## (This is the default) +## +## - FileInsertAtFirstRegexMatch(file, pattern, idx=lamda m: m.start()) +## +## Creates a callable that will parse given file for the given +## regex pattern and will insert the output in the file. +## ``idx`` is a callable that receive the matching object and +## must return a integer index point where to insert the +## the output in the file. Default is to return the position of +## the start of the matched string. +## +## - FileRegexSubst(file, pattern, replace, flags) +## +## Apply a replace inplace in the given file. Your regex pattern must +## take care of everything and might be more complex. Check the README +## for a complete copy-pastable example. +## +#publish = stdout +OUTPUT_FILE = "docs/CHANGELOG.rst" +INSERT_POINT_REGEX = r'''(?isxu) +^ +( + \s*Changelog\s*(\n|\r\n|\r) ## ``Changelog`` line + ==+\s*(\n|\r\n|\r){2} ## ``=========`` rest underline +) + +( ## Match all between changelog and release rev + ( + (?! + (?<=(\n|\r)) ## look back for newline + %(rev)s ## revision + \s+ + \([0-9]+-[0-9]{2}-[0-9]{2}\)(\n|\r\n|\r) ## date + --+(\n|\r\n|\r) ## ``---`` underline + ) + . + )* +) + +(?P%(rev)s) +''' % {'rev': r"v[0-9]+\.[0-9]+(\.[0-9]+)?"} + +revs = [ + Caret(FileFirstRegexMatch(OUTPUT_FILE, INSERT_POINT_REGEX)), + "HEAD" +] + +publish = FileRegexSubst(OUTPUT_FILE, INSERT_POINT_REGEX, r"\1\o\g") + + +## ``revs`` is a list of callable or a list of string +## +## callable will be called to resolve as strings and allow dynamical +## computation of these. The result will be used as revisions for +## gitchangelog (as if directly stated on the command line). This allows +## to filter exaclty which commits will be read by gitchangelog. +## +## To get a full documentation on the format of these strings, please +## refer to the ``git rev-list`` arguments. There are many examples. +## +## Using callables is especially useful, for instance, if you +## are using gitchangelog to generate incrementally your changelog. +## +## Some helpers are provided, you can use them:: +## +## - FileFirstRegexMatch(file, pattern): will return a callable that will +## return the first string match for the given pattern in the given file. +## If you use named sub-patterns in your regex pattern, it'll output only +## the string matching the regex pattern named "rev". +## +## - Caret(rev): will return the rev prefixed by a "^", which is a +## way to remove the given revision and all its ancestor. +## +## Please note that if you provide a rev-list on the command line, it'll +## replace this value (which will then be ignored). +## +## If empty, then ``gitchangelog`` will act as it had to generate a full +## changelog. +## +## The default is to use all commits to make the changelog. +#revs = ["^1.0.3", ] + +# revs = [ +# Caret( +# FileFirstRegexMatch( +# "docs/CHANGELOG.rst", +# r"(?Pv[0-9]+\.[0-9]+(\.[0-9]+)?)\s+\([0-9]+-[0-9]{2}-[0-9]{2}\)\n--+\n")), +# "HEAD" +# ] + +revs = [] diff --git a/docs/CHANGELOG.rst b/docs/CHANGELOG.rst new file mode 100644 index 0000000..a5693d9 --- /dev/null +++ b/docs/CHANGELOG.rst @@ -0,0 +1,2 @@ +Changelog +========= diff --git a/pyproject.toml b/pyproject.toml index f958587..9eb55fa 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -109,6 +109,7 @@ use_parentheses = true ignore = [ ".editorconfig", ".pre-commit-config.yaml", + ".gitchangelog.rc", "CODE_OF_CONDUCT.md", "CONTRIBUTING.md", "Justfile", From 360b2b57a179527223229754f2cdfb45face8db4 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Mon, 30 Oct 2023 14:27:10 -0700 Subject: [PATCH 03/20] Update README --- README.md | 334 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 325 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 06b36a2..4600630 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,349 @@ -# bioio +# BioIO [![Build Status](https://github.com/bioio-devs/bioio/actions/workflows/ci.yml/badge.svg)](https://github.com/bioio-devs/bioio/actions) [![Documentation](https://github.com/bioio-devs/bioio/actions/workflows/docs.yml/badge.svg)](https://bioio-devs.github.io/bioio) [![PyPI version](https://badge.fury.io/py/bioio.svg)](https://badge.fury.io/py/bioio) +[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) +[![Python 3.6](https://img.shields.io/badge/python-3.9,3.10,3.11-blue.svg)](https://www.python.org/downloads/release/python-360/) - -Image reading, metadata management, and image writing for Microscopy images in Python +Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python --- +## Features + +- Image Reading + - BioIO can read many various image formats (ex. `OME-TIFF`, `PNG`, `ND2`), but only when paired with the appropriate plug-in for the image format. See [Reader Installation](#reader-installation) for a full list of the currently supported image formats as well as how to install them. +- Image Writing + - Supports writing metadata and imaging data for: + - `OME-TIFF` + - `OME-ZARR` + - `PNG`, `GIF`, [and other similar formats seen here](https://github.com/imageio/imageio) +- Various File Systems (HTTP URLs, s3, gcs, etc.) + - Supports reading and writing to [fsspec](https://github.com/intake/filesystem_spec) supported file system wherever possible: + - Local paths (i.e. `my-file.png`) + - HTTP URLs (i.e. `https://my-domain.com/my-file.png`) + - [s3fs](https://github.com/dask/s3fs) (i.e. `s3://my-bucket/my-file.png`) + - [gcsfs](https://github.com/dask/gcsfs) (i.e. `gcs://my-bucket/my-file.png`) + - See [Cloud IO Support](#cloud-io-support) for more details. + ## Installation **Stable Release:** `pip install bioio`
**Development Head:** `pip install git+https://github.com/bioio-devs/bioio.git` +BioIO is supported on Windows, Mac, and Ubuntu. +For other platforms, you will likely need to build from source. + +### Reader Installation + +BioIO is a plug-in based system of readers meaning in addition to the `bioio` package you need to install the packages +that support the file types you are using. For example, if attempting to read `.ome.tiff` and `.zarr` files you'll want to install the `bioio-ome-tiff` & `bioio-ome-zarr` packages alongside `bioio` (ex. `pip install bioio bioio-ome-zarr bioio-ome-tiff`). +BioIO will then determine which reader to use for which file automatically. + +This is a list of currently known and maintained reader plug-ins available: +| Package | Supported file types | +| ------------ | -------------------- | +| [bioio-czi](https://github.com/bioio-devs/bioio-czi) | `CZI` | +| [bioio-dv](https://github.com/bioio-devs/bioio-dv) | `DV` | +| [bioio-imageio](https://github.com/bioio-devs/bioio-imageio) | `PNG`, `GIF`, [& other similar formats seen here](https://github.com/imageio/imageio) | +| [bioio-lif](https://github.com/bioio-devs/bioio-lif) | `LIF` | +| [bioio-nd2](https://github.com/bioio-devs/bioio-nd2) | `ND2` | +| [bioio-ome-tiff](https://github.com/bioio-devs/bioio-ome-tiff) | `OME-TIFF` (non-tiled) | +| [bioio-ome-tiled-tiff](https://github.com/bioio-devs/bioio-ome-tiled-tiff) | `OME-TIFF` (tiled) | +| [bioio-ome-zarr](https://github.com/bioio-devs/bioio-ome-zarr) | `ZARR` | +| [bioio-sldy](https://github.com/bioio-devs/bioio-sldy) | `SLDY` | +| [bioio-tifffile](https://github.com/bioio-devs/bioio-tifffile) | `TIFF` (non-globbed) | +| [bioio-tiff-glob](https://github.com/bioio-devs/bioio-tiff-glob) | `TIFF` (globbed) | +| [bioio-bioformats](https://github.com/bioio-devs/bioio-bioformats) | Files supported by [Bio-Formats](https://docs.openmicroscopy.org/bio-formats/latest/supported-formats.html) (Requires `java` and `maven`, see below for details) | + +## Documentation + +For full package documentation please visit +[https://bioio-devs.github.io/bioio/](https://bioio-devs.github.io/bioio/). + ## Quickstart +### Full Image Reading + +If your image fits in memory: + ```python -from bioio import example +from bioio import BioImage + +# Get an BioImage object +img = BioImage("my_file.tiff") # selects the first scene found +img.data # returns 5D TCZYX numpy array +img.xarray_data # returns 5D TCZYX xarray data array backed by numpy +img.dims # returns a Dimensions object +img.dims.order # returns string "TCZYX" +img.dims.X # returns size of X dimension +img.shape # returns tuple of dimension sizes in TCZYX order +img.get_image_data("CZYX", T=0) # returns 4D CZYX numpy array + +# Get the id of the current operating scene +img.current_scene -print(example.str_len("hello")) # prints 5 +# Get a list valid scene ids +img.scenes + +# Change scene using name +img.set_scene("Image:1") +# Or by scene index +img.set_scene(1) + +# Use the same operations on a different scene +# ... ``` -## Documentation +#### Full Image Reading Notes + +The `.data` and `.xarray_data` properties will load the whole scene into memory. +The `.get_image_data` function will load the whole scene into memory and then retrieve +the specified chunk. + +### Delayed Image Reading + +If your image doesn't fit in memory: + +```python +from bioio import BioImage + +# Get an BioImage object +img = BioImage("my_file.tiff") # selects the first scene found +img.dask_data # returns 5D TCZYX dask array +img.xarray_dask_data # returns 5D TCZYX xarray data array backed by dask array +img.dims # returns a Dimensions object +img.dims.order # returns string "TCZYX" +img.dims.X # returns size of X dimension +img.shape # returns tuple of dimension sizes in TCZYX order + +# Pull only a specific chunk in-memory +lazy_t0 = img.get_image_dask_data("CZYX", T=0) # returns out-of-memory 4D dask array +t0 = lazy_t0.compute() # returns in-memory 4D numpy array + +# Get the id of the current operating scene +img.current_scene + +# Get a list valid scene ids +img.scenes + +# Change scene using name +img.set_scene("Image:1") +# Or by scene index +img.set_scene(1) + +# Use the same operations on a different scene +# ... +``` + +#### Delayed Image Reading Notes + +The `.dask_data` and `.xarray_dask_data` properties and the `.get_image_dask_data` +function will not load any piece of the imaging data into memory until you specifically +call `.compute` on the returned Dask array. In doing so, you will only then load the +selected chunk in-memory. + +### Mosaic Image Reading + +Read stitched data or single tiles as a dimension. + +Known plug-in packages that support mosaic tile stitching: + +- `bioio-czi` +- `bioio-lif` + +#### BioImage + +If the file format reader supports stitching mosaic tiles together, the +`BioImage` object will default to stitching the tiles back together. + +```python +img = BioImage("very-large-mosaic.lif") +img.dims.order # T, C, Z, big Y, big X, (S optional) +img.dask_data # Dask chunks fall on tile boundaries, pull YX chunks out of the image +``` + +This behavior can be manually turned off: + +```python +img = BioImage("very-large-mosaic.lif", reconstruct_mosaic=False) +img.dims.order # M (tile index), T, C, Z, small Y, small X, (S optional) +img.dask_data # Chunks use normal ZYX +``` + +If the reader does not support stitching tiles together the M tile index will be +available on the `BioImage` object: + +```python +img = BioImage("some-unsupported-mosaic-stitching-format.ext") +img.dims.order # M (tile index), T, C, Z, small Y, small X, (S optional) +img.dask_data # Chunks use normal ZYX +``` + +#### Reader + +If the file format reader detects mosaic tiles in the image, the `BioImage` object +will store the tiles as a dimension. + +If tile stitching is implemented, the `BioImage` can also return the stitched image. + +```python +reader = BioImage("ver-large-mosaic.lif") +reader.dims.order # M, T, C, Z, tile size Y, tile size X, (S optional) +reader.dask_data # normal operations, can use M dimension to select individual tiles +reader.mosaic_dask_data # returns stitched mosaic - T, C, Z, big Y, big, X, (S optional) +``` -For full package documentation please visit [bioio-devs.github.io/bioio](https://bioio-devs.github.io/bioio). +#### Single Tile Absolute Positioning + +There are functions available on the `BioImage` object +to help with single tile positioning: + +```python +img = BioImage("very-large-mosaic.lif") +img.mosaic_tile_dims # Returns a Dimensions object with just Y and X dim sizes +img.mosaic_tile_dims.Y # 512 (for example) + +# Get the tile start indices (top left corner of tile) +y_start_index, x_start_index = img.get_mosaic_tile_position(12) +``` + +### Metadata Reading + +```python +from bioio import BioImage + +# Get an BioImage object +img = BioImage("my_file.tiff") # selects the first scene found +img.metadata # returns the metadata object for this file format (XML, JSON, etc.) +img.channel_names # returns a list of string channel names found in the metadata +img.physical_pixel_sizes.Z # returns the Z dimension pixel size as found in the metadata +img.physical_pixel_sizes.Y # returns the Y dimension pixel size as found in the metadata +img.physical_pixel_sizes.X # returns the X dimension pixel size as found in the metadata +``` + +### Xarray Coordinate Plane Attachment + +If `bioio` finds coordinate information for the spatial-temporal dimensions of +the image in metadata, you can use +[xarray](http://xarray.pydata.org/en/stable/index.html) for indexing by coordinates. + +```python +from bioio import BioImage + +# Get an BioImage object +img = BioImage("my_file.ome.tiff") + +# Get the first ten seconds (not frames) +first_ten_seconds = img.xarray_data.loc[:10] # returns an xarray.DataArray + +# Get the first ten major units (usually micrometers, not indices) in Z +first_ten_mm_in_z = img.xarray_data.loc[:, :, :10] + +# Get the first ten major units (usually micrometers, not indices) in Y +first_ten_mm_in_y = img.xarray_data.loc[:, :, :, :10] + +# Get the first ten major units (usually micrometers, not indices) in X +first_ten_mm_in_x = img.xarray_data.loc[:, :, :, :, :10] +``` + +See `xarray` +["Indexing and Selecting Data" Documentation](http://xarray.pydata.org/en/stable/indexing.html) +for more information. + +### Cloud IO Support + +[File-System Specification (fsspec)](https://github.com/intake/filesystem_spec) allows +for common object storage services (S3, GCS, etc.) to act like normal filesystems by +following the same base specification across them all. AICSImageIO utilizes this +standard specification to make it possible to read directly from remote resources when +the specification is installed. + +```python +from bioio import BioImage + +# Get an BioImage object +img = BioImage("http://my-website.com/my_file.tiff") +img = BioImage("s3://my-bucket/my_file.tiff") +img = BioImage("gcs://my-bucket/my_file.tiff") + +# Or read with specific filesystem creation arguments +img = BioImage("s3://my-bucket/my_file.tiff", fs_kwargs=dict(anon=True)) +img = BioImage("gcs://my-bucket/my_file.tiff", fs_kwargs=dict(anon=True)) + +# All other normal operations work just fine +``` + +Remote reading requires that the file-system specification implementation for the +target backend is installed. + +- For `s3`: `pip install s3fs` +- For `gs`: `pip install gcsfs` + +See the [list of known implementations](https://filesystem-spec.readthedocs.io/en/latest/?badge=latest#implementations). + +### Saving to OME-TIFF + +The simpliest method to save your image as an OME-TIFF file with key pieces of +metadata is to use the `save` function. + +```python +from bioio import BioImage + +BioImage("my_file.czi").save("my_file.ome.tiff") +``` + +**Note:** By default `BioImage` will generate only a portion of metadata to pass +along from the reader to the OME model. This function currently does not do a full +metadata translation. + +For finer grain customization of the metadata, scenes, or if you want to save an array +as an OME-TIFF, the writer class can also be used to customize as needed. + +```python +import numpy as np +from bioio.writers import OmeTiffWriter + +image = np.random.rand(10, 3, 1024, 2048) +OmeTiffWriter.save(image, "file.ome.tif", dim_order="ZCYX") +``` + +See +[OmeTiffWriter documentation](./aicsimageio.writers.html#aicsimageio.writers.ome_tiff_writer.OmeTiffWriter.save) +for more details. + +#### Other Writers + +In most cases, `BioImage.save` is usually a good default but there are other image +writers available. For more information, please refer to +[our writers documentation](https://bioio-devs.github.io/bioio/bioio.writers.html). ## Development -See [CONTRIBUTING.md](CONTRIBUTING.md) for information related to developing the code. +See our +[developer resources](https://bioio-devs.github.io/bioio/developer_resources.html) +for information related to developing the code. + +## Citation + +If you find `bioio` useful, please cite this repository as: + +# TODO: should this remain the same?? +> Eva Maxfield Brown, Dan Toloudis, Jamie Sherman, Madison Swain-Bowden, Talley Lambert, AICSImageIO Contributors (2021). AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python [Computer software]. GitHub. https://github.com/AllenCellModeling/aicsimageio + +bibtex: + +```bibtex +@misc{aicsimageio, + author = {Brown, Eva Maxfield and Toloudis, Dan and Sherman, Jamie and Swain-Bowden, Madison and Lambert, Talley and {AICSImageIO Contributors}}, + title = {AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python}, + year = {2021}, + publisher = {GitHub}, + url = {https://github.com/AllenCellModeling/aicsimageio} +} +``` + +_Free software: BSD-3-Clause_ -**BSD License** +_(Each reader plug-in has its own license, including some that may be more restrictive than this package's BSD-3-Clause)_ From 473d1d325705ba83903d978780daca949dcac540 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Wed, 1 Nov 2023 15:35:30 -0700 Subject: [PATCH 04/20] Add migration doc --- README.md | 4 ++++ docs/MIGRATION.md | 35 +++++++++++++++++++++++++++++++++++ docs/index.rst | 5 +++-- 3 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 docs/MIGRATION.md diff --git a/README.md b/README.md index 4600630..e0948cb 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,10 @@ Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in P --- +## Migrating from AICSImageIO? + +[See the migration document on the full documentation site](https://bioio-devs.github.io/bioio/MIGRATION.html) + ## Features - Image Reading diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md new file mode 100644 index 0000000..d8d97a1 --- /dev/null +++ b/docs/MIGRATION.md @@ -0,0 +1,35 @@ +# Migration from AICSImageIO to BioIO + +## How different is the API? + +Very little about the API has changed between `aicsimageio` version 4.0.0+ and `bioio`, the API is largely the same with the biggest differences being: +* You use a different Python package (`bioio` instead of `aicsimageio`) + * **Important** - See the [Reader Installation Instructions](https://github.com/bioio-devs/bioio/main/README.md#reader-installation) for which additional packages (`bioio` plug-ins) you'll need to support the files you want to interact with +* The main class exported was renamed from `AICSImage` to `BioImage` + +Example of **OLD** code using `aicsimageio` +```python +from aicsimageio import AICSImage + +image = AICSImage("/some/path/to/my/path") +print(image.dims) +print(image.scenes) +``` + +Example of how that looks using `bioio` + +```python +from bioio import BioImage + +image = BioImage("/some/path/to/my/path") +print(image.dims) +print(image.scenes) +``` + +## Why use BioIO rather than AICSImageIO? +A few reasons: +* Licensing is easier to understand and manage with `bioio` since each file reader is installed separately. +* Fewer dependencies are necessary for users that require only a subset of the total available readers. +* Readers can evolve independently of each other. For example (totally hypothetical), if `bioio-czi` (AKA the CZI reader) needs to start using `dask` version `4.0.0+`, but `bioio-tifffile` (AKA the TIFF reader) needs `dask` version `3.4.0-3.9.0` then we can upgrade `bioio-czi` without conflicting with `bioio-tifffile`. +* `aicsimageio` will be moving into "maintenance" only mode meaning only critical bugfixes will be made to the codebase and `bioio` will be where new features / support for new version of python are made. + diff --git a/docs/index.rst b/docs/index.rst index 698f30e..32f28d9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,6 +11,7 @@ Welcome to bioio's documentation! Full API Reference Developer Resources Changelog + AICSImageIO Migration .. mdinclude:: ../README.md @@ -24,8 +25,8 @@ Specific Doc Pages bioio.BioImage bioio.writers.OmeTiffWriter bioio.writers.OmeZarrWriter - bioio.writers.TimeseriesWriter - bioio.writers.TwoDWriter + bioio.writers.timeseries_writer.TimeseriesWriter + bioio.writers.two_d_writer.TwoDWriter Indices and tables ================== From bc0a7768adb79d94afc16d7f0cc39379cb32f729 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Wed, 1 Nov 2023 15:36:13 -0700 Subject: [PATCH 05/20] Temp branch addition to workflow --- .github/workflows/docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8e64dc6..ca47562 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,6 +4,7 @@ on: push: branches: - main + - feature/upgrade-docs # TODO: Remove before merge :) jobs: docs: From 9489a3b3da29413cca96ba40a580f4196f7dd0a2 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Wed, 1 Nov 2023 17:13:40 -0700 Subject: [PATCH 06/20] Fix reference to OME TIFF writer & aicsimageio usage --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e0948cb..c686780 100644 --- a/README.md +++ b/README.md @@ -260,7 +260,7 @@ for more information. [File-System Specification (fsspec)](https://github.com/intake/filesystem_spec) allows for common object storage services (S3, GCS, etc.) to act like normal filesystems by -following the same base specification across them all. AICSImageIO utilizes this +following the same base specification across them all. BioIO utilizes this standard specification to make it possible to read directly from remote resources when the specification is installed. @@ -314,7 +314,7 @@ OmeTiffWriter.save(image, "file.ome.tif", dim_order="ZCYX") ``` See -[OmeTiffWriter documentation](./aicsimageio.writers.html#aicsimageio.writers.ome_tiff_writer.OmeTiffWriter.save) +[OmeTiffWriter documentation](https://bioio-devs.github.io/bioio/bioio.writers.html) for more details. #### Other Writers From e079c7ec5c22438ca8dd28a4fc52e01eabc14953 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Wed, 1 Nov 2023 17:49:57 -0700 Subject: [PATCH 07/20] Add link to all open issues in org for dev ease --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index c686780..b1a7470 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python +[_Click here to view all open issues in bioio-devs organization at once_](https://github.com/search?q=user%3Abioio-devs+is%3Aissue+is%3Aopen&type=issues&ref=advsearch) + --- ## Migrating from AICSImageIO? From a8dd28dbec318379f81edd5e986f9e54410f4887 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Thu, 2 Nov 2023 16:07:10 -0700 Subject: [PATCH 08/20] Better wording in docs; typos --- README.md | 12 +++++++----- docs/MIGRATION.md | 3 +++ 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b1a7470..45b274b 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,8 @@ Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in P ## Installation +BioIO requires Python version 3.9 and up + **Stable Release:** `pip install bioio`
**Development Head:** `pip install git+https://github.com/bioio-devs/bioio.git` @@ -77,7 +79,7 @@ If your image fits in memory: ```python from bioio import BioImage -# Get an BioImage object +# Get a BioImage object img = BioImage("my_file.tiff") # selects the first scene found img.data # returns 5D TCZYX numpy array img.xarray_data # returns 5D TCZYX xarray data array backed by numpy @@ -115,7 +117,7 @@ If your image doesn't fit in memory: ```python from bioio import BioImage -# Get an BioImage object +# Get a BioImage object img = BioImage("my_file.tiff") # selects the first scene found img.dask_data # returns 5D TCZYX dask array img.xarray_dask_data # returns 5D TCZYX xarray data array backed by dask array @@ -220,7 +222,7 @@ y_start_index, x_start_index = img.get_mosaic_tile_position(12) ```python from bioio import BioImage -# Get an BioImage object +# Get a BioImage object img = BioImage("my_file.tiff") # selects the first scene found img.metadata # returns the metadata object for this file format (XML, JSON, etc.) img.channel_names # returns a list of string channel names found in the metadata @@ -238,7 +240,7 @@ the image in metadata, you can use ```python from bioio import BioImage -# Get an BioImage object +# Get a BioImage object img = BioImage("my_file.ome.tiff") # Get the first ten seconds (not frames) @@ -269,7 +271,7 @@ the specification is installed. ```python from bioio import BioImage -# Get an BioImage object +# Get a BioImage object img = BioImage("http://my-website.com/my_file.tiff") img = BioImage("s3://my-bucket/my_file.tiff") img = BioImage("gcs://my-bucket/my_file.tiff") diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index d8d97a1..061de6a 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -5,6 +5,7 @@ Very little about the API has changed between `aicsimageio` version 4.0.0+ and `bioio`, the API is largely the same with the biggest differences being: * You use a different Python package (`bioio` instead of `aicsimageio`) * **Important** - See the [Reader Installation Instructions](https://github.com/bioio-devs/bioio/main/README.md#reader-installation) for which additional packages (`bioio` plug-ins) you'll need to support the files you want to interact with +* Reader plugins are separate packages that are installed separately. OmeTiffReeader and OmeZarrReader are preinstalled with the default distribution of bioio. * The main class exported was renamed from `AICSImage` to `BioImage` Example of **OLD** code using `aicsimageio` @@ -31,5 +32,7 @@ A few reasons: * Licensing is easier to understand and manage with `bioio` since each file reader is installed separately. * Fewer dependencies are necessary for users that require only a subset of the total available readers. * Readers can evolve independently of each other. For example (totally hypothetical), if `bioio-czi` (AKA the CZI reader) needs to start using `dask` version `4.0.0+`, but `bioio-tifffile` (AKA the TIFF reader) needs `dask` version `3.4.0-3.9.0` then we can upgrade `bioio-czi` without conflicting with `bioio-tifffile`. +* Community Reader development is now made easier. You can write and maintain +your own custom reader without having to submit it to the core bioio package. We always encourage publicizing useful readers for the imaging community at large. * `aicsimageio` will be moving into "maintenance" only mode meaning only critical bugfixes will be made to the codebase and `bioio` will be where new features / support for new version of python are made. From f963622148441dcd1a26a7d9e2c80308d8fa985a Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Thu, 2 Nov 2023 16:17:34 -0700 Subject: [PATCH 09/20] Split up stuff in README --- README.md | 323 ++----------------------------------------- docs/OVERVIEW.md | 348 +++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 2 +- 3 files changed, 362 insertions(+), 311 deletions(-) create mode 100644 docs/OVERVIEW.md diff --git a/README.md b/README.md index 45b274b..e203920 100644 --- a/README.md +++ b/README.md @@ -8,73 +8,25 @@ Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python -[_Click here to view all open issues in bioio-devs organization at once_](https://github.com/search?q=user%3Abioio-devs+is%3Aissue+is%3Aopen&type=issues&ref=advsearch) - --- -## Migrating from AICSImageIO? - -[See the migration document on the full documentation site](https://bioio-devs.github.io/bioio/MIGRATION.html) - -## Features - -- Image Reading - - BioIO can read many various image formats (ex. `OME-TIFF`, `PNG`, `ND2`), but only when paired with the appropriate plug-in for the image format. See [Reader Installation](#reader-installation) for a full list of the currently supported image formats as well as how to install them. -- Image Writing - - Supports writing metadata and imaging data for: - - `OME-TIFF` - - `OME-ZARR` - - `PNG`, `GIF`, [and other similar formats seen here](https://github.com/imageio/imageio) -- Various File Systems (HTTP URLs, s3, gcs, etc.) - - Supports reading and writing to [fsspec](https://github.com/intake/filesystem_spec) supported file system wherever possible: - - Local paths (i.e. `my-file.png`) - - HTTP URLs (i.e. `https://my-domain.com/my-file.png`) - - [s3fs](https://github.com/dask/s3fs) (i.e. `s3://my-bucket/my-file.png`) - - [gcsfs](https://github.com/dask/gcsfs) (i.e. `gcs://my-bucket/my-file.png`) - - See [Cloud IO Support](#cloud-io-support) for more details. - -## Installation - -BioIO requires Python version 3.9 and up - -**Stable Release:** `pip install bioio`
-**Development Head:** `pip install git+https://github.com/bioio-devs/bioio.git` - -BioIO is supported on Windows, Mac, and Ubuntu. -For other platforms, you will likely need to build from source. - -### Reader Installation - -BioIO is a plug-in based system of readers meaning in addition to the `bioio` package you need to install the packages -that support the file types you are using. For example, if attempting to read `.ome.tiff` and `.zarr` files you'll want to install the `bioio-ome-tiff` & `bioio-ome-zarr` packages alongside `bioio` (ex. `pip install bioio bioio-ome-zarr bioio-ome-tiff`). -BioIO will then determine which reader to use for which file automatically. +## Documentation -This is a list of currently known and maintained reader plug-ins available: -| Package | Supported file types | -| ------------ | -------------------- | -| [bioio-czi](https://github.com/bioio-devs/bioio-czi) | `CZI` | -| [bioio-dv](https://github.com/bioio-devs/bioio-dv) | `DV` | -| [bioio-imageio](https://github.com/bioio-devs/bioio-imageio) | `PNG`, `GIF`, [& other similar formats seen here](https://github.com/imageio/imageio) | -| [bioio-lif](https://github.com/bioio-devs/bioio-lif) | `LIF` | -| [bioio-nd2](https://github.com/bioio-devs/bioio-nd2) | `ND2` | -| [bioio-ome-tiff](https://github.com/bioio-devs/bioio-ome-tiff) | `OME-TIFF` (non-tiled) | -| [bioio-ome-tiled-tiff](https://github.com/bioio-devs/bioio-ome-tiled-tiff) | `OME-TIFF` (tiled) | -| [bioio-ome-zarr](https://github.com/bioio-devs/bioio-ome-zarr) | `ZARR` | -| [bioio-sldy](https://github.com/bioio-devs/bioio-sldy) | `SLDY` | -| [bioio-tifffile](https://github.com/bioio-devs/bioio-tifffile) | `TIFF` (non-globbed) | -| [bioio-tiff-glob](https://github.com/bioio-devs/bioio-tiff-glob) | `TIFF` (globbed) | -| [bioio-bioformats](https://github.com/bioio-devs/bioio-bioformats) | Files supported by [Bio-Formats](https://docs.openmicroscopy.org/bio-formats/latest/supported-formats.html) (Requires `java` and `maven`, see below for details) | +[See the full documentation on our GitHub pages site](https://bioio-devs.github.io/bioio/) -## Documentation +## Example Usage (see full documentation for more examples) -For full package documentation please visit -[https://bioio-devs.github.io/bioio/](https://bioio-devs.github.io/bioio/). +Assumptions for the below example ([if untrue, see full documentation for more examples](https://bioio-devs.github.io/bioio/)): +* File is an OME TIFF + * BioIO supports additional file types, this example is specific to OME TIFF +* File fits in memory + * BioIO can work with images that cannot be stored in memory, this example is specific to an image that does fit in memory -## Quickstart -### Full Image Reading +#### Example Installation +Install with pip `pip install bioio bioio-ome-tiff` -If your image fits in memory: +#### Exmaple Snippet ```python from bioio import BioImage @@ -104,254 +56,5 @@ img.set_scene(1) # ... ``` -#### Full Image Reading Notes - -The `.data` and `.xarray_data` properties will load the whole scene into memory. -The `.get_image_data` function will load the whole scene into memory and then retrieve -the specified chunk. - -### Delayed Image Reading - -If your image doesn't fit in memory: - -```python -from bioio import BioImage - -# Get a BioImage object -img = BioImage("my_file.tiff") # selects the first scene found -img.dask_data # returns 5D TCZYX dask array -img.xarray_dask_data # returns 5D TCZYX xarray data array backed by dask array -img.dims # returns a Dimensions object -img.dims.order # returns string "TCZYX" -img.dims.X # returns size of X dimension -img.shape # returns tuple of dimension sizes in TCZYX order - -# Pull only a specific chunk in-memory -lazy_t0 = img.get_image_dask_data("CZYX", T=0) # returns out-of-memory 4D dask array -t0 = lazy_t0.compute() # returns in-memory 4D numpy array - -# Get the id of the current operating scene -img.current_scene - -# Get a list valid scene ids -img.scenes - -# Change scene using name -img.set_scene("Image:1") -# Or by scene index -img.set_scene(1) - -# Use the same operations on a different scene -# ... -``` - -#### Delayed Image Reading Notes - -The `.dask_data` and `.xarray_dask_data` properties and the `.get_image_dask_data` -function will not load any piece of the imaging data into memory until you specifically -call `.compute` on the returned Dask array. In doing so, you will only then load the -selected chunk in-memory. - -### Mosaic Image Reading - -Read stitched data or single tiles as a dimension. - -Known plug-in packages that support mosaic tile stitching: - -- `bioio-czi` -- `bioio-lif` - -#### BioImage - -If the file format reader supports stitching mosaic tiles together, the -`BioImage` object will default to stitching the tiles back together. - -```python -img = BioImage("very-large-mosaic.lif") -img.dims.order # T, C, Z, big Y, big X, (S optional) -img.dask_data # Dask chunks fall on tile boundaries, pull YX chunks out of the image -``` - -This behavior can be manually turned off: - -```python -img = BioImage("very-large-mosaic.lif", reconstruct_mosaic=False) -img.dims.order # M (tile index), T, C, Z, small Y, small X, (S optional) -img.dask_data # Chunks use normal ZYX -``` - -If the reader does not support stitching tiles together the M tile index will be -available on the `BioImage` object: - -```python -img = BioImage("some-unsupported-mosaic-stitching-format.ext") -img.dims.order # M (tile index), T, C, Z, small Y, small X, (S optional) -img.dask_data # Chunks use normal ZYX -``` - -#### Reader - -If the file format reader detects mosaic tiles in the image, the `BioImage` object -will store the tiles as a dimension. - -If tile stitching is implemented, the `BioImage` can also return the stitched image. - -```python -reader = BioImage("ver-large-mosaic.lif") -reader.dims.order # M, T, C, Z, tile size Y, tile size X, (S optional) -reader.dask_data # normal operations, can use M dimension to select individual tiles -reader.mosaic_dask_data # returns stitched mosaic - T, C, Z, big Y, big, X, (S optional) -``` - -#### Single Tile Absolute Positioning - -There are functions available on the `BioImage` object -to help with single tile positioning: - -```python -img = BioImage("very-large-mosaic.lif") -img.mosaic_tile_dims # Returns a Dimensions object with just Y and X dim sizes -img.mosaic_tile_dims.Y # 512 (for example) - -# Get the tile start indices (top left corner of tile) -y_start_index, x_start_index = img.get_mosaic_tile_position(12) -``` - -### Metadata Reading - -```python -from bioio import BioImage - -# Get a BioImage object -img = BioImage("my_file.tiff") # selects the first scene found -img.metadata # returns the metadata object for this file format (XML, JSON, etc.) -img.channel_names # returns a list of string channel names found in the metadata -img.physical_pixel_sizes.Z # returns the Z dimension pixel size as found in the metadata -img.physical_pixel_sizes.Y # returns the Y dimension pixel size as found in the metadata -img.physical_pixel_sizes.X # returns the X dimension pixel size as found in the metadata -``` - -### Xarray Coordinate Plane Attachment - -If `bioio` finds coordinate information for the spatial-temporal dimensions of -the image in metadata, you can use -[xarray](http://xarray.pydata.org/en/stable/index.html) for indexing by coordinates. - -```python -from bioio import BioImage - -# Get a BioImage object -img = BioImage("my_file.ome.tiff") - -# Get the first ten seconds (not frames) -first_ten_seconds = img.xarray_data.loc[:10] # returns an xarray.DataArray - -# Get the first ten major units (usually micrometers, not indices) in Z -first_ten_mm_in_z = img.xarray_data.loc[:, :, :10] - -# Get the first ten major units (usually micrometers, not indices) in Y -first_ten_mm_in_y = img.xarray_data.loc[:, :, :, :10] - -# Get the first ten major units (usually micrometers, not indices) in X -first_ten_mm_in_x = img.xarray_data.loc[:, :, :, :, :10] -``` - -See `xarray` -["Indexing and Selecting Data" Documentation](http://xarray.pydata.org/en/stable/indexing.html) -for more information. - -### Cloud IO Support - -[File-System Specification (fsspec)](https://github.com/intake/filesystem_spec) allows -for common object storage services (S3, GCS, etc.) to act like normal filesystems by -following the same base specification across them all. BioIO utilizes this -standard specification to make it possible to read directly from remote resources when -the specification is installed. - -```python -from bioio import BioImage - -# Get a BioImage object -img = BioImage("http://my-website.com/my_file.tiff") -img = BioImage("s3://my-bucket/my_file.tiff") -img = BioImage("gcs://my-bucket/my_file.tiff") - -# Or read with specific filesystem creation arguments -img = BioImage("s3://my-bucket/my_file.tiff", fs_kwargs=dict(anon=True)) -img = BioImage("gcs://my-bucket/my_file.tiff", fs_kwargs=dict(anon=True)) - -# All other normal operations work just fine -``` - -Remote reading requires that the file-system specification implementation for the -target backend is installed. - -- For `s3`: `pip install s3fs` -- For `gs`: `pip install gcsfs` - -See the [list of known implementations](https://filesystem-spec.readthedocs.io/en/latest/?badge=latest#implementations). - -### Saving to OME-TIFF - -The simpliest method to save your image as an OME-TIFF file with key pieces of -metadata is to use the `save` function. - -```python -from bioio import BioImage - -BioImage("my_file.czi").save("my_file.ome.tiff") -``` - -**Note:** By default `BioImage` will generate only a portion of metadata to pass -along from the reader to the OME model. This function currently does not do a full -metadata translation. - -For finer grain customization of the metadata, scenes, or if you want to save an array -as an OME-TIFF, the writer class can also be used to customize as needed. - -```python -import numpy as np -from bioio.writers import OmeTiffWriter - -image = np.random.rand(10, 3, 1024, 2048) -OmeTiffWriter.save(image, "file.ome.tif", dim_order="ZCYX") -``` - -See -[OmeTiffWriter documentation](https://bioio-devs.github.io/bioio/bioio.writers.html) -for more details. - -#### Other Writers - -In most cases, `BioImage.save` is usually a good default but there are other image -writers available. For more information, please refer to -[our writers documentation](https://bioio-devs.github.io/bioio/bioio.writers.html). - -## Development - -See our -[developer resources](https://bioio-devs.github.io/bioio/developer_resources.html) -for information related to developing the code. - -## Citation - -If you find `bioio` useful, please cite this repository as: - -# TODO: should this remain the same?? -> Eva Maxfield Brown, Dan Toloudis, Jamie Sherman, Madison Swain-Bowden, Talley Lambert, AICSImageIO Contributors (2021). AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python [Computer software]. GitHub. https://github.com/AllenCellModeling/aicsimageio - -bibtex: - -```bibtex -@misc{aicsimageio, - author = {Brown, Eva Maxfield and Toloudis, Dan and Sherman, Jamie and Swain-Bowden, Madison and Lambert, Talley and {AICSImageIO Contributors}}, - title = {AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python}, - year = {2021}, - publisher = {GitHub}, - url = {https://github.com/AllenCellModeling/aicsimageio} -} -``` - -_Free software: BSD-3-Clause_ - -_(Each reader plug-in has its own license, including some that may be more restrictive than this package's BSD-3-Clause)_ +## Issues +[_Click here to view all open issues in bioio-devs organization at once_](https://github.com/search?q=user%3Abioio-devs+is%3Aissue+is%3Aopen&type=issues&ref=advsearch) diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md new file mode 100644 index 0000000..65f1a55 --- /dev/null +++ b/docs/OVERVIEW.md @@ -0,0 +1,348 @@ +# BioIO + +[![Build Status](https://github.com/bioio-devs/bioio/actions/workflows/ci.yml/badge.svg)](https://github.com/bioio-devs/bioio/actions) +[![Documentation](https://github.com/bioio-devs/bioio/actions/workflows/docs.yml/badge.svg)](https://bioio-devs.github.io/bioio) +[![PyPI version](https://badge.fury.io/py/bioio.svg)](https://badge.fury.io/py/bioio) +[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) +[![Python 3.6](https://img.shields.io/badge/python-3.9,3.10,3.11-blue.svg)](https://www.python.org/downloads/release/python-360/) + +Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python + +[_Click here to view all open issues in bioio-devs organization at once_](https://github.com/search?q=user%3Abioio-devs+is%3Aissue+is%3Aopen&type=issues&ref=advsearch) + +--- + +## Features + +- Image Reading + - BioIO can read many various image formats (ex. `OME-TIFF`, `PNG`, `ND2`), but only when paired with the appropriate plug-in for the image format. See [Reader Installation](#reader-installation) for a full list of the currently supported image formats as well as how to install them. +- Image Writing + - Supports writing metadata and imaging data for: + - `OME-TIFF` + - `OME-ZARR` + - `PNG`, `GIF`, [and other similar formats seen here](https://github.com/imageio/imageio) +- Various File Systems (HTTP URLs, s3, gcs, etc.) + - Supports reading and writing to [fsspec](https://github.com/intake/filesystem_spec) supported file system wherever possible: + - Local paths (i.e. `my-file.png`) + - HTTP URLs (i.e. `https://my-domain.com/my-file.png`) + - [s3fs](https://github.com/dask/s3fs) (i.e. `s3://my-bucket/my-file.png`) + - [gcsfs](https://github.com/dask/gcsfs) (i.e. `gcs://my-bucket/my-file.png`) + - See [Cloud IO Support](#cloud-io-support) for more details. + +## Installation + +BioIO requires Python version 3.9 and up + +**Stable Release:** `pip install bioio`
+**Development Head:** `pip install git+https://github.com/bioio-devs/bioio.git` + +BioIO is supported on Windows, Mac, and Ubuntu. +For other platforms, you will likely need to build from source. + +### Reader Installation + +BioIO is a plug-in based system of readers meaning in addition to the `bioio` package you need to install the packages +that support the file types you are using. For example, if attempting to read `.ome.tiff` and `.zarr` files you'll want to install the `bioio-ome-tiff` & `bioio-ome-zarr` packages alongside `bioio` (ex. `pip install bioio bioio-ome-zarr bioio-ome-tiff`). +BioIO will then determine which reader to use for which file automatically. + +This is a list of currently known and maintained reader plug-ins available: +| Package | Supported file types | +| ------------ | -------------------- | +| [bioio-czi](https://github.com/bioio-devs/bioio-czi) | `CZI` | +| [bioio-dv](https://github.com/bioio-devs/bioio-dv) | `DV` | +| [bioio-imageio](https://github.com/bioio-devs/bioio-imageio) | `PNG`, `GIF`, [& other similar formats seen here](https://github.com/imageio/imageio) | +| [bioio-lif](https://github.com/bioio-devs/bioio-lif) | `LIF` | +| [bioio-nd2](https://github.com/bioio-devs/bioio-nd2) | `ND2` | +| [bioio-ome-tiff](https://github.com/bioio-devs/bioio-ome-tiff) | `OME-TIFF` (non-tiled) | +| [bioio-ome-tiled-tiff](https://github.com/bioio-devs/bioio-ome-tiled-tiff) | `OME-TIFF` (tiled) | +| [bioio-ome-zarr](https://github.com/bioio-devs/bioio-ome-zarr) | `ZARR` | +| [bioio-sldy](https://github.com/bioio-devs/bioio-sldy) | `SLDY` | +| [bioio-tifffile](https://github.com/bioio-devs/bioio-tifffile) | `TIFF` (non-globbed) | +| [bioio-tiff-glob](https://github.com/bioio-devs/bioio-tiff-glob) | `TIFF` (globbed) | +| [bioio-bioformats](https://github.com/bioio-devs/bioio-bioformats) | Files supported by [Bio-Formats](https://docs.openmicroscopy.org/bio-formats/latest/supported-formats.html) (Requires `java` and `maven`, see below for details) | + +## Quickstart + +### Full Image Reading + +If your image fits in memory: + +```python +from bioio import BioImage + +# Get a BioImage object +img = BioImage("my_file.tiff") # selects the first scene found +img.data # returns 5D TCZYX numpy array +img.xarray_data # returns 5D TCZYX xarray data array backed by numpy +img.dims # returns a Dimensions object +img.dims.order # returns string "TCZYX" +img.dims.X # returns size of X dimension +img.shape # returns tuple of dimension sizes in TCZYX order +img.get_image_data("CZYX", T=0) # returns 4D CZYX numpy array + +# Get the id of the current operating scene +img.current_scene + +# Get a list valid scene ids +img.scenes + +# Change scene using name +img.set_scene("Image:1") +# Or by scene index +img.set_scene(1) + +# Use the same operations on a different scene +# ... +``` + +#### Full Image Reading Notes + +The `.data` and `.xarray_data` properties will load the whole scene into memory. +The `.get_image_data` function will load the whole scene into memory and then retrieve +the specified chunk. + +### Delayed Image Reading + +If your image doesn't fit in memory: + +```python +from bioio import BioImage + +# Get a BioImage object +img = BioImage("my_file.tiff") # selects the first scene found +img.dask_data # returns 5D TCZYX dask array +img.xarray_dask_data # returns 5D TCZYX xarray data array backed by dask array +img.dims # returns a Dimensions object +img.dims.order # returns string "TCZYX" +img.dims.X # returns size of X dimension +img.shape # returns tuple of dimension sizes in TCZYX order + +# Pull only a specific chunk in-memory +lazy_t0 = img.get_image_dask_data("CZYX", T=0) # returns out-of-memory 4D dask array +t0 = lazy_t0.compute() # returns in-memory 4D numpy array + +# Get the id of the current operating scene +img.current_scene + +# Get a list valid scene ids +img.scenes + +# Change scene using name +img.set_scene("Image:1") +# Or by scene index +img.set_scene(1) + +# Use the same operations on a different scene +# ... +``` + +#### Delayed Image Reading Notes + +The `.dask_data` and `.xarray_dask_data` properties and the `.get_image_dask_data` +function will not load any piece of the imaging data into memory until you specifically +call `.compute` on the returned Dask array. In doing so, you will only then load the +selected chunk in-memory. + +### Mosaic Image Reading + +Read stitched data or single tiles as a dimension. + +Known plug-in packages that support mosaic tile stitching: + +- `bioio-czi` +- `bioio-lif` + +#### BioImage + +If the file format reader supports stitching mosaic tiles together, the +`BioImage` object will default to stitching the tiles back together. + +```python +img = BioImage("very-large-mosaic.lif") +img.dims.order # T, C, Z, big Y, big X, (S optional) +img.dask_data # Dask chunks fall on tile boundaries, pull YX chunks out of the image +``` + +This behavior can be manually turned off: + +```python +img = BioImage("very-large-mosaic.lif", reconstruct_mosaic=False) +img.dims.order # M (tile index), T, C, Z, small Y, small X, (S optional) +img.dask_data # Chunks use normal ZYX +``` + +If the reader does not support stitching tiles together the M tile index will be +available on the `BioImage` object: + +```python +img = BioImage("some-unsupported-mosaic-stitching-format.ext") +img.dims.order # M (tile index), T, C, Z, small Y, small X, (S optional) +img.dask_data # Chunks use normal ZYX +``` + +#### Reader + +If the file format reader detects mosaic tiles in the image, the `BioImage` object +will store the tiles as a dimension. + +If tile stitching is implemented, the `BioImage` can also return the stitched image. + +```python +reader = BioImage("ver-large-mosaic.lif") +reader.dims.order # M, T, C, Z, tile size Y, tile size X, (S optional) +reader.dask_data # normal operations, can use M dimension to select individual tiles +reader.mosaic_dask_data # returns stitched mosaic - T, C, Z, big Y, big, X, (S optional) +``` + +#### Single Tile Absolute Positioning + +There are functions available on the `BioImage` object +to help with single tile positioning: + +```python +img = BioImage("very-large-mosaic.lif") +img.mosaic_tile_dims # Returns a Dimensions object with just Y and X dim sizes +img.mosaic_tile_dims.Y # 512 (for example) + +# Get the tile start indices (top left corner of tile) +y_start_index, x_start_index = img.get_mosaic_tile_position(12) +``` + +### Metadata Reading + +```python +from bioio import BioImage + +# Get a BioImage object +img = BioImage("my_file.tiff") # selects the first scene found +img.metadata # returns the metadata object for this file format (XML, JSON, etc.) +img.channel_names # returns a list of string channel names found in the metadata +img.physical_pixel_sizes.Z # returns the Z dimension pixel size as found in the metadata +img.physical_pixel_sizes.Y # returns the Y dimension pixel size as found in the metadata +img.physical_pixel_sizes.X # returns the X dimension pixel size as found in the metadata +``` + +### Xarray Coordinate Plane Attachment + +If `bioio` finds coordinate information for the spatial-temporal dimensions of +the image in metadata, you can use +[xarray](http://xarray.pydata.org/en/stable/index.html) for indexing by coordinates. + +```python +from bioio import BioImage + +# Get a BioImage object +img = BioImage("my_file.ome.tiff") + +# Get the first ten seconds (not frames) +first_ten_seconds = img.xarray_data.loc[:10] # returns an xarray.DataArray + +# Get the first ten major units (usually micrometers, not indices) in Z +first_ten_mm_in_z = img.xarray_data.loc[:, :, :10] + +# Get the first ten major units (usually micrometers, not indices) in Y +first_ten_mm_in_y = img.xarray_data.loc[:, :, :, :10] + +# Get the first ten major units (usually micrometers, not indices) in X +first_ten_mm_in_x = img.xarray_data.loc[:, :, :, :, :10] +``` + +See `xarray` +["Indexing and Selecting Data" Documentation](http://xarray.pydata.org/en/stable/indexing.html) +for more information. + +### Cloud IO Support + +[File-System Specification (fsspec)](https://github.com/intake/filesystem_spec) allows +for common object storage services (S3, GCS, etc.) to act like normal filesystems by +following the same base specification across them all. BioIO utilizes this +standard specification to make it possible to read directly from remote resources when +the specification is installed. + +```python +from bioio import BioImage + +# Get a BioImage object +img = BioImage("http://my-website.com/my_file.tiff") +img = BioImage("s3://my-bucket/my_file.tiff") +img = BioImage("gcs://my-bucket/my_file.tiff") + +# Or read with specific filesystem creation arguments +img = BioImage("s3://my-bucket/my_file.tiff", fs_kwargs=dict(anon=True)) +img = BioImage("gcs://my-bucket/my_file.tiff", fs_kwargs=dict(anon=True)) + +# All other normal operations work just fine +``` + +Remote reading requires that the file-system specification implementation for the +target backend is installed. + +- For `s3`: `pip install s3fs` +- For `gs`: `pip install gcsfs` + +See the [list of known implementations](https://filesystem-spec.readthedocs.io/en/latest/?badge=latest#implementations). + +### Saving to OME-TIFF + +The simpliest method to save your image as an OME-TIFF file with key pieces of +metadata is to use the `save` function. + +```python +from bioio import BioImage + +BioImage("my_file.czi").save("my_file.ome.tiff") +``` + +**Note:** By default `BioImage` will generate only a portion of metadata to pass +along from the reader to the OME model. This function currently does not do a full +metadata translation. + +For finer grain customization of the metadata, scenes, or if you want to save an array +as an OME-TIFF, the writer class can also be used to customize as needed. + +```python +import numpy as np +from bioio.writers import OmeTiffWriter + +image = np.random.rand(10, 3, 1024, 2048) +OmeTiffWriter.save(image, "file.ome.tif", dim_order="ZCYX") +``` + +See +[OmeTiffWriter documentation](https://bioio-devs.github.io/bioio/bioio.writers.html) +for more details. + +#### Other Writers + +In most cases, `BioImage.save` is usually a good default but there are other image +writers available. For more information, please refer to +[our writers documentation](https://bioio-devs.github.io/bioio/bioio.writers.html). + +## Development + +See our +[developer resources](https://bioio-devs.github.io/bioio/developer_resources.html) +for information related to developing the code. + +## Citation + +If you find `bioio` useful, please cite this repository as: + +# TODO: should this remain the same?? +> Eva Maxfield Brown, Dan Toloudis, Jamie Sherman, Madison Swain-Bowden, Talley Lambert, AICSImageIO Contributors (2021). AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python [Computer software]. GitHub. https://github.com/AllenCellModeling/aicsimageio + +bibtex: + +```bibtex +@misc{aicsimageio, + author = {Brown, Eva Maxfield and Toloudis, Dan and Sherman, Jamie and Swain-Bowden, Madison and Lambert, Talley and {AICSImageIO Contributors}}, + title = {AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python}, + year = {2021}, + publisher = {GitHub}, + url = {https://github.com/AllenCellModeling/aicsimageio} +} +``` + +_Free software: BSD-3-Clause_ + +_(Each reader plug-in has its own license, including some that may be more restrictive than this package's BSD-3-Clause)_ diff --git a/docs/index.rst b/docs/index.rst index 32f28d9..16fe4e5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ Welcome to bioio's documentation! :maxdepth: 1 :caption: Contents: - Overview + Overview Installation Full API Reference Developer Resources From bf826a0ec44bf927f94ac491a127b549613ade4c Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Thu, 2 Nov 2023 16:20:35 -0700 Subject: [PATCH 10/20] Remove README from doc site --- docs/index.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 16fe4e5..3e53e64 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,8 +13,6 @@ Welcome to bioio's documentation! Changelog AICSImageIO Migration -.. mdinclude:: ../README.md - Specific Doc Pages ================== From 4ca1a136875c83ef27b3a84d907ae15767da48cb Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Thu, 2 Nov 2023 16:24:52 -0700 Subject: [PATCH 11/20] Adjust links to docs --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e203920..8448d3f 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,11 @@ Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in P ## Documentation -[See the full documentation on our GitHub pages site](https://bioio-devs.github.io/bioio/) +[See the full documentation on our GitHub pages site](https://bioio-devs.github.io/bioio/OVERVIEW.html) ## Example Usage (see full documentation for more examples) -Assumptions for the below example ([if untrue, see full documentation for more examples](https://bioio-devs.github.io/bioio/)): +Assumptions for the below example ([if untrue, see full documentation for more examples](https://bioio-devs.github.io/bioio/OVERVIEW.html)): * File is an OME TIFF * BioIO supports additional file types, this example is specific to OME TIFF * File fits in memory From 5e762088be60c3c33a8ed3793c0e5658f2fa49f8 Mon Sep 17 00:00:00 2001 From: Sean LeRoy <41307451+SeanLeRoy@users.noreply.github.com> Date: Fri, 3 Nov 2023 09:47:38 -0700 Subject: [PATCH 12/20] Update README.md Co-authored-by: toloudis --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8448d3f..6f4f443 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Assumptions for the below example ([if untrue, see full documentation for more e #### Example Installation Install with pip `pip install bioio bioio-ome-tiff` -#### Exmaple Snippet +#### Example Snippet ```python from bioio import BioImage From cbdcf86ee5d1ddeaf59a0f83d95533df64f96073 Mon Sep 17 00:00:00 2001 From: Sean LeRoy <41307451+SeanLeRoy@users.noreply.github.com> Date: Fri, 3 Nov 2023 09:51:33 -0700 Subject: [PATCH 13/20] Update README.md Co-authored-by: toloudis --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6f4f443..3c09514 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in P ## Example Usage (see full documentation for more examples) -Assumptions for the below example ([if untrue, see full documentation for more examples](https://bioio-devs.github.io/bioio/OVERVIEW.html)): +Assumptions for the below example ([see full documentation for more examples](https://bioio-devs.github.io/bioio/OVERVIEW.html)): * File is an OME TIFF * BioIO supports additional file types, this example is specific to OME TIFF * File fits in memory From 797668af1f11c666ec61a092818cd1ad6080c899 Mon Sep 17 00:00:00 2001 From: Sean LeRoy <41307451+SeanLeRoy@users.noreply.github.com> Date: Fri, 3 Nov 2023 09:55:01 -0700 Subject: [PATCH 14/20] Update docs/OVERVIEW.md Co-authored-by: toloudis --- docs/OVERVIEW.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index 65f1a55..4013b82 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -4,7 +4,7 @@ [![Documentation](https://github.com/bioio-devs/bioio/actions/workflows/docs.yml/badge.svg)](https://bioio-devs.github.io/bioio) [![PyPI version](https://badge.fury.io/py/bioio.svg)](https://badge.fury.io/py/bioio) [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) -[![Python 3.6](https://img.shields.io/badge/python-3.9,3.10,3.11-blue.svg)](https://www.python.org/downloads/release/python-360/) +[![Python 3.9+](https://img.shields.io/badge/python-3.9,3.10,3.11-blue.svg)](https://www.python.org/downloads/release/python-390/) Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python From 7a4b9e441e6606a576d54d9c80fb22bf2d282c22 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Fri, 3 Nov 2023 10:01:23 -0700 Subject: [PATCH 15/20] PR Feedback about docs --- README.md | 14 +++----------- docs/OVERVIEW.md | 8 -------- 2 files changed, 3 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 3c09514..550f752 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![Documentation](https://github.com/bioio-devs/bioio/actions/workflows/docs.yml/badge.svg)](https://bioio-devs.github.io/bioio) [![PyPI version](https://badge.fury.io/py/bioio.svg)](https://badge.fury.io/py/bioio) [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) -[![Python 3.6](https://img.shields.io/badge/python-3.9,3.10,3.11-blue.svg)](https://www.python.org/downloads/release/python-360/) +[![Python 3.9+](https://img.shields.io/badge/python-3.9,3.10,3.11-blue.svg)](https://www.python.org/downloads/release/python-390/) Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python @@ -16,17 +16,9 @@ Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in P ## Example Usage (see full documentation for more examples) -Assumptions for the below example ([see full documentation for more examples](https://bioio-devs.github.io/bioio/OVERVIEW.html)): -* File is an OME TIFF - * BioIO supports additional file types, this example is specific to OME TIFF -* File fits in memory - * BioIO can work with images that cannot be stored in memory, this example is specific to an image that does fit in memory +Install bioio and bioio OME TIFF plug-in with pip: - -#### Example Installation -Install with pip `pip install bioio bioio-ome-tiff` - -#### Example Snippet +`pip install bioio bioio-ome-tiff` ```python from bioio import BioImage diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index 4013b82..d2310a0 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -1,15 +1,7 @@ # BioIO -[![Build Status](https://github.com/bioio-devs/bioio/actions/workflows/ci.yml/badge.svg)](https://github.com/bioio-devs/bioio/actions) -[![Documentation](https://github.com/bioio-devs/bioio/actions/workflows/docs.yml/badge.svg)](https://bioio-devs.github.io/bioio) -[![PyPI version](https://badge.fury.io/py/bioio.svg)](https://badge.fury.io/py/bioio) -[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) -[![Python 3.9+](https://img.shields.io/badge/python-3.9,3.10,3.11-blue.svg)](https://www.python.org/downloads/release/python-390/) - Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python -[_Click here to view all open issues in bioio-devs organization at once_](https://github.com/search?q=user%3Abioio-devs+is%3Aissue+is%3Aopen&type=issues&ref=advsearch) - --- ## Features From 538d10f052c131a7c019c9672560bd67c763a251 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Fri, 3 Nov 2023 10:03:51 -0700 Subject: [PATCH 16/20] Adjust citation --- docs/OVERVIEW.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index d2310a0..fa7efcd 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -320,18 +320,17 @@ for information related to developing the code. If you find `bioio` useful, please cite this repository as: -# TODO: should this remain the same?? -> Eva Maxfield Brown, Dan Toloudis, Jamie Sherman, Madison Swain-Bowden, Talley Lambert, AICSImageIO Contributors (2021). AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python [Computer software]. GitHub. https://github.com/AllenCellModeling/aicsimageio +> Eva Maxfield Brown, Dan Toloudis, Jamie Sherman, Madison Swain-Bowden, Talley Lambert, Sean Meharry, Brian Whitney, AICSImageIO Contributors (2023). AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python [Computer software]. GitHub. https://github.com/AllenCellModeling/aicsimageio bibtex: ```bibtex -@misc{aicsimageio, - author = {Brown, Eva Maxfield and Toloudis, Dan and Sherman, Jamie and Swain-Bowden, Madison and Lambert, Talley and {AICSImageIO Contributors}}, - title = {AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python}, - year = {2021}, +@misc{bioio, + author = {Brown, Eva Maxfield and Toloudis, Dan and Sherman, Jamie and Swain-Bowden, Madison and Lambert, Talley and Meharry, Sean and Whitney, Brian and {AICSImageIO Contributors}}, + title = {BioIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python}, + year = {2023}, publisher = {GitHub}, - url = {https://github.com/AllenCellModeling/aicsimageio} + url = {https://github.com/bioio-devs/bioio} } ``` From e858146811ff49dcd37df74c8e422fc64ca3ce88 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Fri, 3 Nov 2023 10:38:46 -0700 Subject: [PATCH 17/20] Use HTML for table formatting; adjust cloud io link --- docs/OVERVIEW.md | 144 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 129 insertions(+), 15 deletions(-) diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index fa7efcd..6b4caa9 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -19,7 +19,7 @@ Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in P - HTTP URLs (i.e. `https://my-domain.com/my-file.png`) - [s3fs](https://github.com/dask/s3fs) (i.e. `s3://my-bucket/my-file.png`) - [gcsfs](https://github.com/dask/gcsfs) (i.e. `gcs://my-bucket/my-file.png`) - - See [Cloud IO Support](#cloud-io-support) for more details. + - See [Cloud IO Support](#id2) for more details. ## Installation @@ -38,20 +38,134 @@ that support the file types you are using. For example, if attempting to read `. BioIO will then determine which reader to use for which file automatically. This is a list of currently known and maintained reader plug-ins available: -| Package | Supported file types | -| ------------ | -------------------- | -| [bioio-czi](https://github.com/bioio-devs/bioio-czi) | `CZI` | -| [bioio-dv](https://github.com/bioio-devs/bioio-dv) | `DV` | -| [bioio-imageio](https://github.com/bioio-devs/bioio-imageio) | `PNG`, `GIF`, [& other similar formats seen here](https://github.com/imageio/imageio) | -| [bioio-lif](https://github.com/bioio-devs/bioio-lif) | `LIF` | -| [bioio-nd2](https://github.com/bioio-devs/bioio-nd2) | `ND2` | -| [bioio-ome-tiff](https://github.com/bioio-devs/bioio-ome-tiff) | `OME-TIFF` (non-tiled) | -| [bioio-ome-tiled-tiff](https://github.com/bioio-devs/bioio-ome-tiled-tiff) | `OME-TIFF` (tiled) | -| [bioio-ome-zarr](https://github.com/bioio-devs/bioio-ome-zarr) | `ZARR` | -| [bioio-sldy](https://github.com/bioio-devs/bioio-sldy) | `SLDY` | -| [bioio-tifffile](https://github.com/bioio-devs/bioio-tifffile) | `TIFF` (non-globbed) | -| [bioio-tiff-glob](https://github.com/bioio-devs/bioio-tiff-glob) | `TIFF` (globbed) | -| [bioio-bioformats](https://github.com/bioio-devs/bioio-bioformats) | Files supported by [Bio-Formats](https://docs.openmicroscopy.org/bio-formats/latest/supported-formats.html) (Requires `java` and `maven`, see below for details) | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PackageSupported File Types
+ bioio-czi + + + CZI + +
+ bioio-dv + + + DV + +
+ bioio-imageio + + + PNG + , + + GIF + , + & other similar formats seen here +
+ bioio-lif + + + LIF + +
+ bioio-nd2 + + + ND2 + +
+ bioio-ome-tiff + + + OME-TIFF + (non-tiled) +
+ bioio-ome-tiled-tiff + + + OME TIFF + (tiled) +
+ bioio-ome-zarr + + + ZARR + +
+ bioio-sldy + + + SLDY + +
+ bioio-tifffile + + + TIFF + (non-globbed) +
+ bioio-tiff-glob + + + TIFF + (globbed) +
+ bioio-bioformats + + Files supported by Bio-Formats (Requires java and maven, see below for details) +
## Quickstart From f1a2f535935ebace2a6192ec5c9a3bfcfbc1d47b Mon Sep 17 00:00:00 2001 From: Sean LeRoy <41307451+SeanLeRoy@users.noreply.github.com> Date: Fri, 3 Nov 2023 10:39:13 -0700 Subject: [PATCH 18/20] Update docs/OVERVIEW.md Co-authored-by: toloudis --- docs/OVERVIEW.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index 6b4caa9..f2bb9c1 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -434,7 +434,7 @@ for information related to developing the code. If you find `bioio` useful, please cite this repository as: -> Eva Maxfield Brown, Dan Toloudis, Jamie Sherman, Madison Swain-Bowden, Talley Lambert, Sean Meharry, Brian Whitney, AICSImageIO Contributors (2023). AICSImageIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python [Computer software]. GitHub. https://github.com/AllenCellModeling/aicsimageio +> Eva Maxfield Brown, Dan Toloudis, Jamie Sherman, Madison Swain-Bowden, Talley Lambert, Sean Meharry, Brian Whitney, AICSImageIO Contributors (2023). BioIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python [Computer software]. GitHub. https://github.com/bioio-devs/bioio bibtex: From 9183b23722add769d393de531cd74e049e5bc0d7 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Fri, 3 Nov 2023 11:12:08 -0700 Subject: [PATCH 19/20] Update reader install link --- docs/OVERVIEW.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index f2bb9c1..47f3777 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -7,7 +7,7 @@ Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in P ## Features - Image Reading - - BioIO can read many various image formats (ex. `OME-TIFF`, `PNG`, `ND2`), but only when paired with the appropriate plug-in for the image format. See [Reader Installation](#reader-installation) for a full list of the currently supported image formats as well as how to install them. + - BioIO can read many various image formats (ex. `OME-TIFF`, `PNG`, `ND2`), but only when paired with the appropriate plug-in for the image format. See [Reader Installation](#id1) for a full list of the currently supported image formats as well as how to install them. - Image Writing - Supports writing metadata and imaging data for: - `OME-TIFF` From eaf9029a27d1cc2016dfa94553c3ed8220be3f46 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Wed, 29 Nov 2023 10:55:46 -0800 Subject: [PATCH 20/20] Minor PR Feedback --- .github/workflows/docs.yml | 1 - README.md | 4 ++-- docs/MIGRATION.md | 2 +- docs/OVERVIEW.md | 4 ++-- 4 files changed, 5 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ca47562..8e64dc6 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -4,7 +4,6 @@ on: push: branches: - main - - feature/upgrade-docs # TODO: Remove before merge :) jobs: docs: diff --git a/README.md b/README.md index 550f752..3cb09f5 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,9 @@ Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in P ## Example Usage (see full documentation for more examples) -Install bioio and bioio OME TIFF plug-in with pip: +Install bioio alongside OME TIFF and OME ZARR plug-ins with pip (this example won't use the OME ZARR plug-in): -`pip install bioio bioio-ome-tiff` +`pip install bioio bioio-ome-tiff bioio-ome-zarr` ```python from bioio import BioImage diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 061de6a..35af972 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -1,4 +1,4 @@ -# Migration from AICSImageIO to BioIO +# Migration from AICSImageIO v4 to BioIO v1 ## How different is the API? diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index 47f3777..be8e4ce 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -37,7 +37,7 @@ BioIO is a plug-in based system of readers meaning in addition to the `bioio` pa that support the file types you are using. For example, if attempting to read `.ome.tiff` and `.zarr` files you'll want to install the `bioio-ome-tiff` & `bioio-ome-zarr` packages alongside `bioio` (ex. `pip install bioio bioio-ome-zarr bioio-ome-tiff`). BioIO will then determine which reader to use for which file automatically. -This is a list of currently known and maintained reader plug-ins available: +This is a list of currently known and maintained reader plug-ins available, however other plug-ins may be available outside of these: @@ -440,7 +440,7 @@ bibtex: ```bibtex @misc{bioio, - author = {Brown, Eva Maxfield and Toloudis, Dan and Sherman, Jamie and Swain-Bowden, Madison and Lambert, Talley and Meharry, Sean and Whitney, Brian and {AICSImageIO Contributors}}, + author = {Brown, Eva Maxfield and Toloudis, Dan and Sherman, Jamie and Swain-Bowden, Madison and Lambert, Talley and Meharry, Sean and Whitney, Brian and {BioIO Contributors}}, title = {BioIO: Image Reading, Metadata Conversion, and Image Writing for Microscopy Images in Pure Python}, year = {2023}, publisher = {GitHub},
Package