DuguidLab · celefthe · Jan 27, 2026 · Apr 7, 2025 · Apr 7, 2025 · Apr 7, 2025
diff --git a/README.md b/README.md
@@ -1,3 +1,117 @@
-# mesoscopy
+![https://www.mesoscopy.org](./resources/mesoscopy-logo-banner.png)
 
-Analysis pipeline for rodent widefield calcium imaging data
+---
+
+[![Build & Test](https://github.com/DuguidLab/mesoscopy/actions/workflows/build-and-test.yml/badge.svg?branch=main)](https://github.com/DuguidLab/mesoscopy/actions/workflows/build-and-test.yml)
+![PyPI - Version](https://img.shields.io/pypi/v/mesoscopy)
+
+Mesoscopy is an open-source package for the analysis of mesoscale calcium recordings. It handles the preprocessing of mesoscale recording files to extract ∆F responses, the anatomical registration of recordings to the Allen Brain atlas as well as analysis of recordings captured at rest or with behaviour.
+
+## Prerequisites
+
+Mesoscopy works best with data acquired in the [NWB](https://www.nwb.org) format. Alternatively, recordings acquired as HDF5 files compatible with mesoscopy's [raw data schema](docs/design-principles/data-structure.md) may be used.
+
+Dual-channel recordings with an accompanying haemodynamic response channel (e.g. using both 470nm and 405nm excitation for GCaMP) will be automatically separated during preprocessing and yield a corrected ∆F signal.
+
+An example acquisition script (designed for FLIR Grasshopper cameras) can be found [here](https://gist.github.com/celefthe/d069e4e90397039b3aaf53292446fbd1).
+
+## Installing mesoscopy
+
+The recommended way to install `mesoscopy` is by using `pipx` (<https://pypa.github.io/pipx/>). `pipx` will create an isolated python environment from which `mesoscopy` will run, leaving the system python alone. This is the recommended way to install `mesoscopy`, as it will not interfere with any other python packages you may have installed on your system.
+
+### On Linux
+
+1. Install `pipx`.
+    - On Ubuntu / Debian:
+
+        ```bash
+        sudo apt update
+        sudo apt install pipx
+        pipx ensurepath
+        sudo pipx ensurepath
+        ```
+
+    - On Fedora:
+
+        ```bash
+        sudo dnf install pipx
+        pipx ensurepath
+        sudo pipx ensurepath
+        ```
+
+    - For other distributions, install `pipx` with `pip`:
+
+        ```bash
+        python3 -m pip install --user pipx
+        python3 -m pipx ensurepath
+        sudo pipx ensurepath
+        ```
+
+2. Install `mesoscopy`.
+
+    ```bash
+    pipx install mesoscopy
+    ```
+
+### On MacOS
+
+1. Install `pipx` with [homebrew](https://brew.sh).
+
+    ```bash
+    brew install pipx
+    pipx ensurepath
+    sudo pipx ensurepath
+    ```
+
+2. Install `mesoscopy`.
+
+    ```bash
+    pipx install mesoscopy
+    ```
+
+### On Windows
+
+With Windows, you have two choices. You can either use `mesoscopy` with the [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) and follow the instructions above for installing `mesoscopy` on Linux (recommended), or you can run `mesoscopy` directly on Windows via PowerShell. The choice is of course yours, but you should bear in mind that `mesoscopy` primarily targets Unix-like OSs (Linux & MacOS) at the moment, so while everything _should_ work fine on Windows, your mileage may vary.
+
+To install `mesoscopy` directly on Windows, first install `pipx` using [Scoop](https://scoop.sh):
+
+```powershell
+scoop install pipx
+pipx ensurepath
+```
+
+Then install `mesoscopy` via `pipx`:
+
+```powershell
+pipx install mesoscopy
+```
+
+## Usage
+
+For detailed documentation on how to use `mesoscopy`, please refer to our [documentation](mesoscopy.org).
+
+To see all available `mesoscopy` commands, run
+
+```bash
+mesoscopy --help
+```
+
+`mesoscopy` commands are self-documenting. Run `mesoscopy <command> --help` to get more information or see available sub-commands.
+
+## Upgrading
+
+Use `pipx` to upgrade mesoscopy:
+
+```bash
+pipx upgrade mesoscopy
+```
+
+## Contributing
+
+Mesoscopy is currently closed to PRs, except bugfixes. Please open an issue if you wish to contribute.
+
+## Funders
+
+<p align="left">
+  <img width="250" src="./resources/sidb.jpg"  alt="logo"/>
+</p>
diff --git a/docs/assets/favicon.ico b/docs/assets/favicon.ico
diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png
diff --git a/docs/assets/mesoscopy-favicon.png b/docs/assets/mesoscopy-favicon.png
diff --git a/docs/assets/mesoscopy-logo-banner.png b/docs/assets/mesoscopy-logo-banner.png
diff --git a/docs/assets/mesoscopy-logo.png b/docs/assets/mesoscopy-logo.png
diff --git a/docs/index.md b/docs/index.md
@@ -1,3 +1,7 @@
+![https://www.mesoscopy.org](../assets/mesoscopy-logo-banner.png)
+
+---
+
 # Getting Started
 
 Mesoscopy is an open-source package for the analysis of mesoscale calcium recordings. It handles the preprocessing of mesoscale recording files to extract ∆F responses, the anatomical registration of recordings to the Allen Brain atlas as well as analysis of recordings captured at rest or with behaviour.

diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -1,8 +1,63 @@
-:root  > * {
-    --md-primary-fg-color:        #585992;
-    /* --md-primary-fg-color--light: #E1DFFF;
-    --md-primary-fg-color--dark:  #C1C1FF;
-    --md-accent-fg-color: #422236;
-    --md-accent-fg-color--dark: #C6C4DD; */
-    /* --md-accent-bg-color: #FFFFFF; */
-; }
+/* cyrillic-ext */
+@font-face {
+    font-family: 'Advent Pro';
+    font-style: normal;
+    font-weight: 500;
+    font-stretch: 100%;
+    font-display: swap;
+    src: url(https://fonts.gstatic.com/s/adventpro/v23/V8mqoQfxVT4Dvddr_yOwrzaFxV7JtdQgFqXdUAQrGp_zgX5sWCpLcSN_RpAvvQhKBXYCqYg.woff) format('woff');
+    unicode-range: U+0460-052F, U+1C80-1C88, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
+  }
+  /* cyrillic */
+  @font-face {
+    font-family: 'Advent Pro';
+    font-style: normal;
+    font-weight: 500;
+    font-stretch: 100%;
+    font-display: swap;
+    src: url(https://fonts.gstatic.com/s/adventpro/v23/V8mqoQfxVT4Dvddr_yOwrzaFxV7JtdQgFqXdUAQrGp_zgX5sWCpLcSN_T5AvvQhKBXYCqYg.woff) format('woff');
+    unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
+  }
+  /* greek */
+  @font-face {
+    font-family: 'Advent Pro';
+    font-style: normal;
+    font-weight: 500;
+    font-stretch: 100%;
+    font-display: swap;
+    src: url(https://fonts.gstatic.com/s/adventpro/v23/V8mqoQfxVT4Dvddr_yOwrzaFxV7JtdQgFqXdUAQrGp_zgX5sWCpLcSN_SJAvvQhKBXYCqYg.woff) format('woff');
+    unicode-range: U+0370-03FF;
+  }
+  /* latin-ext */
+  @font-face {
+    font-family: 'Advent Pro';
+    font-style: normal;
+    font-weight: 500;
+    font-stretch: 100%;
+    font-display: swap;
+    src: url(https://fonts.gstatic.com/s/adventpro/v23/V8mqoQfxVT4Dvddr_yOwrzaFxV7JtdQgFqXdUAQrGp_zgX5sWCpLcSN_RZAvvQhKBXYCqYg.woff) format('woff');
+    unicode-range: U+0100-02AF, U+0304, U+0308, U+0329, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20CF, U+2113, U+2C60-2C7F, U+A720-A7FF;
+  }
+  /* latin */
+  @font-face {
+    font-family: 'Advent Pro';
+    font-style: normal;
+    font-weight: 500;
+    font-stretch: 100%;
+    font-display: swap;
+    src: url(https://fonts.gstatic.com/s/adventpro/v23/V8mqoQfxVT4Dvddr_yOwrzaFxV7JtdQgFqXdUAQrGp_zgX5sWCpLcSN_S5AvvQhKBXYC.woff) format('woff');
+    unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+  }
+
+.md-header {
+    background-color:        #585992;
+  }
+
+.md-header__ellipsis {
+    font-family: "Advent Pro";
+    text-transform: uppercase;
+}
+
+.md-tabs {
+    background-color:        #585992;
+  }
diff --git a/docs/typical-workflow.md b/docs/typical-workflow.md
@@ -7,7 +7,7 @@ mesoscopy convert /path/to/example-recording.h5
 ```
 
 !!! note
-    See also our guide to [converting video files to HDF5](how-to/convert-video-to-h5.md) if you're recording videos in AVI or MP4 format. 
+    See also our guide to [converting video files to HDF5](how-to/convert-video-to-h5.md) if you're recording videos in AVI or MP4 format.
 
 ## Inspect raw data
 
@@ -27,18 +27,14 @@ mesoscopy preprocess /path/to/example-recording.nwb
 mesoscopy register mark-landmarks /path/to/example-recording.nwb
 ```
 
-
-
 ```bash
 mesoscopy register landmarks --template-points example-recording_landmarks.csv /path/to/example-recording.nwb
 ```
 
-
 ## Extract area responses
 
 ```bash
 mesoscopy process area-responses /path/to/example-recording.nwb
 ```
 
-
 ## Next steps
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -5,11 +5,11 @@ repo_name: DuguidLab/mesoscopy
 
 theme:
   name: material
-  # favicon: assets/mesoscopy_logo_icon.png
+  favicon: assets/favicon.png
   # custom_dir: docs/overrides
   font:
     text: Montserrat 
-  # logo: assets/mesoscopy_logo_icon.png
+  logo: assets/mesoscopy-logo.png
   icon:
     repo: fontawesome/brands/github
   features:
@@ -29,16 +29,16 @@ theme:
   palette:
     - media: "(prefers-color-scheme: light)"
       primary: deep purple
-      accent: blue
+      accent: teal
       toggle:
-        icon: material/moon-waxing-crescent
+        icon: material/eye
         name: Switch to dark mode
     - media: "(prefers-color-scheme: dark)"
       scheme: slate
       primary: deep purple
-      accent: blue
+      accent: teal
       toggle:
-        icon: material/weather-sunny
+        icon: material/eye-outline
         name: Switch to light mode
 
 extra_css:

diff --git a/pyproject.toml b/pyproject.toml
@@ -88,6 +88,7 @@ docs = [
   "mkdocstrings-python",
   "pymdown-extensions",
   "material-plausible-plugin",
+  "ruff"
 ]
 lint = [
   "ruff",

diff --git a/resources/mesoscopy-favicon.png b/resources/mesoscopy-favicon.png
diff --git a/resources/mesoscopy-logo-banner.png b/resources/mesoscopy-logo-banner.png