diff --git a/README.md b/README.md index 32f7c3d..30cdcd6 100644 --- 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` (). `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 --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 + +

+ logo +

diff --git a/docs/assets/favicon.ico b/docs/assets/favicon.ico new file mode 100644 index 0000000..b41d648 Binary files /dev/null and b/docs/assets/favicon.ico differ diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png new file mode 100644 index 0000000..9fedd70 Binary files /dev/null and b/docs/assets/favicon.png differ diff --git a/docs/assets/mesoscopy-favicon.png b/docs/assets/mesoscopy-favicon.png new file mode 100644 index 0000000..ab1172e Binary files /dev/null and b/docs/assets/mesoscopy-favicon.png differ diff --git a/docs/assets/mesoscopy-logo-banner.png b/docs/assets/mesoscopy-logo-banner.png new file mode 100644 index 0000000..98d977e Binary files /dev/null and b/docs/assets/mesoscopy-logo-banner.png differ diff --git a/docs/assets/mesoscopy-logo.png b/docs/assets/mesoscopy-logo.png new file mode 100644 index 0000000..f7be8dd Binary files /dev/null and b/docs/assets/mesoscopy-logo.png differ diff --git a/docs/index.md b/docs/index.md index a588d26..bc6d6a5 100644 --- 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 index b8443d4..efafa4d 100644 --- 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; */ -; } \ No newline at end of file +/* 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; + } \ No newline at end of file diff --git a/docs/typical-workflow.md b/docs/typical-workflow.md index e0a3a19..412c5bb 100644 --- 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 index 754aa33..f157d88 100644 --- 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 index 708b794..a9c1625 100644 --- 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 new file mode 100644 index 0000000..32ec43f Binary files /dev/null and b/resources/mesoscopy-favicon.png differ diff --git a/resources/mesoscopy-logo-banner.png b/resources/mesoscopy-logo-banner.png new file mode 100644 index 0000000..98d977e Binary files /dev/null and b/resources/mesoscopy-logo-banner.png differ diff --git a/resources/mesoscopy-logo-bow.svg b/resources/mesoscopy-logo-bow.svg new file mode 100644 index 0000000..ef6d2e1 --- /dev/null +++ b/resources/mesoscopy-logo-bow.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/resources/mesoscopy-logo-square.png b/resources/mesoscopy-logo-square.png new file mode 100644 index 0000000..cc55e01 Binary files /dev/null and b/resources/mesoscopy-logo-square.png differ diff --git a/resources/mesoscopy-logo-wob.svg b/resources/mesoscopy-logo-wob.svg new file mode 100644 index 0000000..8505314 --- /dev/null +++ b/resources/mesoscopy-logo-wob.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/resources/mesoscopy-logo.png b/resources/mesoscopy-logo.png new file mode 100644 index 0000000..4abedd5 Binary files /dev/null and b/resources/mesoscopy-logo.png differ diff --git a/resources/mesoscopy-logo.svg b/resources/mesoscopy-logo.svg new file mode 100644 index 0000000..74f1d63 --- /dev/null +++ b/resources/mesoscopy-logo.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/resources/sidb.jpg b/resources/sidb.jpg new file mode 100644 index 0000000..416f2bb Binary files /dev/null and b/resources/sidb.jpg differ