Skip to content

Commit 723aa62

Browse files
finsbergfinsberg
authored
Merge pull request #18 from scientificcomputing/docs
Docs
2 parents 44ba480 + cb41661 commit 723aa62

26 files changed

Lines changed: 690 additions & 116 deletions

‎.github/workflows/build_docs.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Build documentation
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
workflow_call:
7+
workflow_dispatch:
8+
9+
10+
jobs:
11+
12+
build:
13+
runs-on: ubuntu-22.04
14+
env:
15+
PUBLISH_DIR: ./build
16+
17+
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v6
21+
22+
- name: Setup Python
23+
uses: actions/setup-python@v6
24+
with:
25+
python-version: "3.10"
26+
27+
- name: Install dependencies
28+
run: python3 -m pip install ".[docs]"
29+
30+
- name: Build docs
31+
run: python3 -m sphinx -b html . build
32+
33+
- name: Upload artifact
34+
uses: actions/upload-pages-artifact@v4
35+
with:
36+
path: ${{ env.PUBLISH_DIR }}

‎.github/workflows/deploy_docs.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Publish documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: "pages"
16+
cancel-in-progress: true
17+
18+
jobs:
19+
20+
build:
21+
uses: ./.github/workflows/build_docs.yml
22+
23+
deploy:
24+
needs: build
25+
environment:
26+
name: github-pages
27+
url: ${{ steps.deployment.outputs.page_url }}
28+
29+
runs-on: ubuntu-latest
30+
31+
steps:
32+
- name: Checkout
33+
uses: actions/checkout@v6
34+
35+
- name: Setup Pages
36+
uses: actions/configure-pages@v5
37+
38+
39+
- name: Deploy to GitHub Pages
40+
id: deployment
41+
uses: actions/deploy-pages@v4

‎CONTRIBUTING.md‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,6 @@ Thank you for your interest in contributing to `mri-toolkit`! We welcome contrib
44

55
This document outlines the guidelines for contributing to ensure a smooth process for everyone involved.
66

7-
## Table of Contents
8-
1. [Reporting Issues](#reporting-issues)
9-
2. [Setting Up Your Development Environment](#setting-up-your-development-environment)
10-
3. [Code Style and Quality](#code-style-and-quality)
11-
4. [Running Tests](#running-tests)
12-
5. [Submitting a Pull Request](#submitting-a-pull-request)
13-
6. [License](#license)
14-
157
## Reporting Issues
168

179
If you encounter a bug or have a feature request, please use the [GitHub Issues](https://github.com/scientificcomputing/mri-toolkit/issues) tracker.

‎README.md‎

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,30 @@
1-
# MRI-toolkit
2-
`MRI-toolkit` provides a set of features dedicated to human MRI data post-processing.
3-
The implementation is based on [`gMRI2FEM`](https://github.com/jorgenriseth/gMRI2FEM)
1+
# MRI-Toolkit
2+
3+
`MRI-toolkit` provides a set of features dedicated to human MRI data post-processing and analysis. The implementation is based on [gMRI2FEM](https://github.com/jorgenriseth/gMRI2FEM).
4+
5+
## Installation
6+
7+
```bash
8+
pip install mri-toolkit
9+
```
10+
11+
## Documentation
12+
13+
The documentation is available at [https://scientificcomputing.github.io/mri-toolkit/](https://scientificcomputing.github.io/mri-toolkit/). It includes detailed usage instructions, API references, and examples.
14+
15+
16+
## Quick Start
17+
18+
To get started with `mri-toolkit`, you can use the command-line interface (CLI) to inspect and analyze your MRI data.
19+
20+
![readme](https://github.com/user-attachments/assets/404bc4be-7267-4d1c-9126-0bee7c4a316c)
21+
22+
23+
## Features
24+
25+
* **File Inspection**: detailed NIfTI header analysis (affine, voxel size, shape).
26+
* **Statistics**: Compute comprehensive statistics (volume, mean, median, std, percentiles) for MRI regions based on segmentation maps.
27+
* **Visualization**:
28+
* **Terminal**: View orthogonal slices (Sagittal, Coronal, Axial) directly in your console.
29+
* **Napari**: Launch the Napari viewer for interactive 3D inspection.
30+
* **Data Management**: Utilities to download test datasets.

‎_toc.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
format: jb-book
2+
root: README
3+
4+
parts:
5+
- caption: Getting Started
6+
chapters:
7+
- file: "docs/install.md" # Installation instructions (also for extras and development)
8+
- file: "docs/datasets.md" # Information about the datasets that can be downloaded with mritk
9+
- caption: Command Line Interface
10+
chapters:
11+
- file: "docs/info.md" # About the mritk info command
12+
- file: "docs/show.md" # About the mritk show command
13+
- file: "docs/napari.md" # About the mritk napari command
14+
15+
- caption: Community
16+
chapters:
17+
- file: "CONTRIBUTING.md" # Contributing guidelines
18+
- caption: Python API
19+
chapters:
20+
- file: "docs/api.rst" # API documentation (generated with sphinx)

‎conf.py‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
###############################################################################
2+
# Auto-generated by `jupyter-book config`
3+
# If you wish to continue using _config.yml, make edits to that file and
4+
# re-generate this one.
5+
###############################################################################
6+
author = "Simula Research Laboratory"
7+
bibtex_bibfiles = ["docs/refs.bib"]
8+
codeautolink_concat_default = True
9+
comments_config = {"hypothesis": False, "utterances": False}
10+
copyright = "2026"
11+
exclude_patterns = [
12+
"**.ipynb_checkpoints",
13+
".DS_Store",
14+
".github/*",
15+
".pytest_cache/*",
16+
".tox/*",
17+
"Thumbs.db",
18+
"_build",
19+
"third_party/*",
20+
"jupyter_execute/",
21+
"**.jupyter_cache",
22+
]
23+
extensions = [
24+
"sphinx_togglebutton",
25+
"sphinx_copybutton",
26+
"myst_parser",
27+
"sphinx_comments",
28+
"sphinx_external_toc",
29+
"sphinx.ext.intersphinx",
30+
"sphinx_design",
31+
"sphinx_book_theme",
32+
"sphinx.ext.autodoc",
33+
"sphinx.ext.napoleon",
34+
"sphinx.ext.viewcode",
35+
"sphinxcontrib.bibtex",
36+
"sphinx_codeautolink",
37+
"sphinx_multitoc_numbering",
38+
]
39+
myst_enable_extensions = [
40+
"amsmath",
41+
"attrs_inline",
42+
"colon_fence",
43+
"deflist",
44+
"dollarmath",
45+
"fieldlist",
46+
"html_admonition",
47+
"html_image",
48+
"linkify",
49+
"replacements",
50+
"smartquotes",
51+
"strikethrough",
52+
"substitution",
53+
"tasklist",
54+
]
55+
external_toc_exclude_missing = True
56+
external_toc_path = "_toc.yml"
57+
html_baseurl = ""
58+
html_favicon = ""
59+
html_last_updated_fmt = "%b %d, %Y"
60+
html_logo = "docs/logo.png"
61+
html_sourcelink_suffix = ""
62+
# html_static_path = ["_static"]
63+
html_theme = "sphinx_book_theme"
64+
html_theme_options = {
65+
"search_bar_text": "Search this book...",
66+
"launch_buttons": {
67+
"notebook_interface": "classic",
68+
"binderhub_url": "",
69+
"jupyterhub_url": "",
70+
"thebe": False,
71+
"colab_url": "",
72+
"deepnote_url": "",
73+
},
74+
"path_to_docs": "",
75+
"repository_url": "https://github.com/scientificcomputing/mri-toolkit",
76+
"repository_branch": "main",
77+
"extra_footer": "",
78+
"home_page_in_toc": True,
79+
"announcement": "",
80+
"analytics": {
81+
"google_analytics_id": "",
82+
"plausible_analytics_domain": "",
83+
"plausible_analytics_url": "https://plausible.io/js/script.js",
84+
},
85+
"use_repository_button": True,
86+
"use_edit_page_button": False,
87+
"use_issues_button": True,
88+
}
89+
html_title = "mri-toolkit"
90+
intersphinx_mapping = {
91+
"numpy": ["https://numpy.org/doc/stable/", None],
92+
"matplotlib": ["https://matplotlib.org/stable/", None],
93+
"packaging": ["https://packaging.pypa.io/en/stable/", None],
94+
}
95+
latex_engine = "pdflatex"
96+
myst_url_schemes = ["mailto", "http", "https"]
97+
nb_custom_formats = {".py": ["jupytext.reads", {"fmt": "py"}]}
98+
nb_execution_allow_errors = False
99+
nb_execution_cache_path = ""
100+
nb_execution_excludepatterns: list[str] = []
101+
nb_execution_in_temp = False
102+
nb_execution_mode = "cache"
103+
nb_execution_show_tb = True
104+
nb_execution_timeout = 3000
105+
nb_output_stderr = "show"
106+
numfig = True
107+
pygments_style = "sphinx"
108+
suppress_warnings = ["mystnb.unknown_mime_type", "bibtex.duplicate_citation"]
109+
use_jupyterbook_latex = True
110+
use_multitoc_numbering = True

‎docs/api.rst‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
API Reference
2+
=============
3+
4+
cli
5+
---
6+
7+
.. automodule:: mritk.cli
8+
:members:
9+
:inherited-members:
10+
11+
12+
datasets
13+
--------
14+
15+
.. automodule:: mritk.datasets
16+
:members:
17+
:inherited-members:
18+
19+
20+
info
21+
----
22+
23+
.. automodule:: mritk.info
24+
:members:
25+
:inherited-members:
26+
27+
28+
napari
29+
------
30+
31+
.. automodule:: mritk.napari
32+
:members:
33+
:inherited-members:
34+
35+
show
36+
----
37+
38+
.. automodule:: mritk.show
39+
:members:
40+
:inherited-members:
41+
42+
43+
statistics
44+
----------
45+
46+
.. automodule:: mritk.statistics
47+
:members:
48+
:inherited-members:
49+
50+
.. automodule:: mritk.statistics.utils
51+
:members:
52+
:inherited-members:
53+
54+
.. automodule:: mritk.statistics.compute_stats
55+
:members:
56+
:inherited-members:
57+
58+
.. automodule:: mritk.statistics.cli
59+
:members:
60+
:inherited-members:
61+
62+
63+
data
64+
----
65+
66+
.. automodule:: mritk.data
67+
:members:
68+
:inherited-members:
69+
70+
.. automodule:: mritk.data.io
71+
:members:
72+
:inherited-members:
73+
74+
.. automodule:: mritk.data.orientation
75+
:members:
76+
:inherited-members:
77+
78+
.. automodule:: mritk.data.base
79+
:members:
80+
:inherited-members:
81+
82+
83+
segmentation
84+
------------
85+
86+
.. automodule:: mritk.segmentation
87+
:members:
88+
:inherited-members:
89+
90+
.. automodule:: mritk.segmentation.groups
91+
:members:
92+
:inherited-members:
93+
94+
.. automodule:: mritk.segmentation.lookup_table
95+
:members:
96+
:inherited-members:

‎docs/datasets.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Datasets
2+
3+
The `datasets` subcommand provides tools for listing and downloading example datasets.
4+
5+
To list available datasets, use:
6+
7+
```bash
8+
mritk datasets list
9+
```
10+
You can also get more information about a specific dataset:
11+
12+
```bash
13+
mritk datasets info <dataset_name>
14+
```
15+
16+
To download a dataset, use:
17+
18+
```bash
19+
mritk datasets download <dataset_name> -o /path/to/download
20+
```
21+
22+
![data](https://github.com/user-attachments/assets/7e35f2d8-ca97-42e7-b9b9-3b609ba5148f)

‎docs/info.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Info command
2+
3+
The `info` command allows you to quickly inspect the metadata of an MRI file. It displays the image shape, voxel size, data type, and the affine transformation matrix.
4+
5+
## Usage
6+
7+
```bash
8+
mritk info <file_path> [OPTIONS]
9+
```
10+
11+
**Arguments:**
12+
* `file`: Path to the file to display information about.
13+
14+
**Options:**
15+
* `--json`: Output information in JSON format. Useful for programmatic parsing.
16+
17+
18+
![info](https://github.com/user-attachments/assets/fc0e734d-3c94-48fa-8e25-3e65bfc86ebe)

0 commit comments

Comments
 (0)