diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..31fe9fc
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,39 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: 'bug'
+assignees: ''
+
+---
+
+## Bug Report
+
+### Description
+
+A clear and concise description of what is the overall operation that is intended to be
+performed that resulted in an error.
+
+### Reproducibility
+Include:
+- OS (WIN | MACOS | Linux)
+- DataJoint Element Version
+- MySQL Version
+- MySQL Deployment Strategy (local-native | local-docker | remote)
+- Minimum number of steps to reliably reproduce the issue
+- Complete error stack as a result of evaluating the above steps
+
+### Expected Behavior
+A clear and concise description of what you expected to happen.
+
+### Screenshots
+If applicable, add screenshots to help explain your problem.
+
+### Additional Research and Context
+Add any additional research or context that was conducted in creating this report.
+
+For example:
+- Related GitHub issues and PR's either within this repository or in other relevant
+ repositories.
+- Specific links to specific lines or a focus within source code.
+- Relevant summary of Maintainers development meetings, milestones, projects, etc.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..d31fbac
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+ - name: DataJoint Contribution Guideline
+ url: https://docs.datajoint.org/python/community/02-Contribute.html
+ about: Please make sure to review the DataJoint Contribution Guidelines
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..1f2b784
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,57 @@
+---
+name: Feature request
+about: Suggest an idea for a new feature
+title: ''
+labels: 'enhancement'
+assignees: ''
+
+---
+
+## Feature Request
+
+### Problem
+
+A clear and concise description how this idea has manifested and the context. Elaborate
+on the need for this feature and/or what could be improved. Ex. I'm always frustrated
+when [...]
+
+### Requirements
+
+A clear and concise description of the requirements to satisfy the new feature. Detail
+what you expect from a successful implementation of the feature. Ex. When using this
+feature, it should [...]
+
+### Justification
+
+Provide the key benefits in making this a supported feature. Ex. Adding support for this
+feature would ensure [...]
+
+### Alternative Considerations
+
+Do you currently have a work-around for this? Provide any alternative solutions or
+features you've considered.
+
+### Related Errors
+Add any errors as a direct result of not exposing this feature.
+
+Please include steps to reproduce provided errors as follows:
+- OS (WIN | MACOS | Linux)
+- DataJoint Element Version
+- MySQL Version
+- MySQL Deployment Strategy (local-native | local-docker | remote)
+- Minimum number of steps to reliably reproduce the issue
+- Complete error stack as a result of evaluating the above steps
+
+### Screenshots
+If applicable, add screenshots to help explain your feature.
+
+### Additional Research and Context
+Add any additional research or context that was conducted in creating this feature request.
+
+For example:
+- Related GitHub issues and PR's either within this repository or in other relevant
+ repositories.
+- Specific links to specific lines or a focus within source code.
+- Relevant summary of Maintainers development meetings, milestones, projects, etc.
+- Any additional supplemental web references or links that would further justify this
+ feature request.
diff --git a/.github/workflows/development.yaml b/.github/workflows/development.yaml
new file mode 100644
index 0000000..549f126
--- /dev/null
+++ b/.github/workflows/development.yaml
@@ -0,0 +1,147 @@
+name: Development
+on:
+ pull_request:
+ push:
+ tags:
+ - '*.*.*'
+jobs:
+ test-changelog:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+ - name: Get changelog entry
+ id: changelog_reader
+ uses: guzman-raphael/changelog-reader-action@v5
+ with:
+ path: ./CHANGELOG.md
+ - name: Verify changelog parsing
+ env:
+ TAG_NAME: ${{steps.changelog_reader.outputs.version}}
+ RELEASE_NAME: Release ${{steps.changelog_reader.outputs.version}}
+ BODY: ${{steps.changelog_reader.outputs.changes}}
+ PRERELEASE: ${{steps.changelog_reader.outputs.status == 'prereleased'}}
+ DRAFT: ${{steps.changelog_reader.outputs.status == 'unreleased'}}
+ run: |
+ echo "TAG_NAME=${TAG_NAME}"
+ echo "RELEASE_NAME=${RELEASE_NAME}"
+ echo "BODY=${BODY}"
+ echo "PRERELEASE=${PRERELEASE}"
+ echo "DRAFT=${DRAFT}"
+ build:
+ needs: test-changelog
+ runs-on: ubuntu-latest
+ strategy:
+ matrix:
+ include:
+ - py_ver: 3.8
+ distro: alpine
+ image: djbase
+ env:
+ PY_VER: ${{matrix.py_ver}}
+ DISTRO: ${{matrix.distro}}
+ IMAGE: ${{matrix.image}}
+ DOCKER_CLIENT_TIMEOUT: "120"
+ COMPOSE_HTTP_TIMEOUT: "120"
+ steps:
+ - uses: actions/checkout@v2
+ - name: Compile image
+ run: |
+ export PKG_NAME=$(python3 -c "print([p for p in __import__('setuptools').find_packages() if '.' not in p][0])")
+ export PKG_VERSION=$(cat ${PKG_NAME}/version.py | awk -F\' '/__version__ = / {print $2}')
+ export HOST_UID=$(id -u)
+ docker-compose -f docker-compose-build.yaml up --exit-code-from element --build
+ IMAGE=$(docker images --filter "reference=datajoint/${PKG_NAME}*" \
+ --format "{{.Repository}}")
+ TAG=$(docker images --filter "reference=datajoint/${PKG_NAME}*" --format "{{.Tag}}")
+ docker save "${IMAGE}:${TAG}" | \
+ gzip > "image-${PKG_NAME}-${PKG_VERSION}-py${PY_VER}-${DISTRO}.tar.gz"
+ echo "PKG_NAME=${PKG_NAME}" >> $GITHUB_ENV
+ echo "PKG_VERSION=${PKG_VERSION}" >> $GITHUB_ENV
+ - name: Add image artifact
+ uses: actions/upload-artifact@v2
+ with:
+ name: image-${{env.PKG_NAME}}-${{env.PKG_VERSION}}-py${{matrix.py_ver}}-${{matrix.distro}}
+ path: "image-${{env.PKG_NAME}}-${{env.PKG_VERSION}}-py${{matrix.py_ver}}-\
+ ${{matrix.distro}}.tar.gz"
+ retention-days: 1
+ - if: matrix.py_ver == '3.8' && matrix.distro == 'alpine'
+ name: Add pip artifacts
+ uses: actions/upload-artifact@v2
+ with:
+ name: pip-${{env.PKG_NAME}}-${{env.PKG_VERSION}}
+ path: dist
+ retention-days: 1
+ publish-release:
+ if: github.event_name == 'push'
+ needs: build
+ runs-on: ubuntu-latest
+ env:
+ TWINE_USERNAME: ${{secrets.twine_username}}
+ TWINE_PASSWORD: ${{secrets.twine_password}}
+ outputs:
+ release_upload_url: ${{steps.create_gh_release.outputs.upload_url}}
+ steps:
+ - uses: actions/checkout@v2
+ - name: Determine package version
+ run: |
+ PKG_NAME=$(python3 -c "print([p for p in __import__('setuptools').find_packages() if '.' not in p][0])")
+ SDIST_PKG_NAME=$(echo ${PKG_NAME} | sed 's|_|-|g')
+ PKG_VERSION=$(cat ${PKG_NAME}/version.py | awk -F\' '/__version__ = / {print $2}')
+ echo "PKG_NAME=${PKG_NAME}" >> $GITHUB_ENV
+ echo "PKG_VERSION=${PKG_VERSION}" >> $GITHUB_ENV
+ echo "SDIST_PKG_NAME=${SDIST_PKG_NAME}" >> $GITHUB_ENV
+ - name: Get changelog entry
+ id: changelog_reader
+ uses: guzman-raphael/changelog-reader-action@v5
+ with:
+ path: ./CHANGELOG.md
+ version: ${{env.PKG_VERSION}}
+ - name: Create GH release
+ id: create_gh_release
+ uses: actions/create-release@v1
+ env:
+ GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+ with:
+ tag_name: ${{steps.changelog_reader.outputs.version}}
+ release_name: Release ${{steps.changelog_reader.outputs.version}}
+ body: ${{steps.changelog_reader.outputs.changes}}
+ prerelease: ${{steps.changelog_reader.outputs.status == 'prereleased'}}
+ draft: ${{steps.changelog_reader.outputs.status == 'unreleased'}}
+ - name: Fetch image artifact
+ uses: actions/download-artifact@v2
+ with:
+ name: image-${{env.PKG_NAME}}-${{env.PKG_VERSION}}-py3.8-alpine
+ - name: Fetch pip artifacts
+ uses: actions/download-artifact@v2
+ with:
+ name: pip-${{env.PKG_NAME}}-${{env.PKG_VERSION}}
+ path: dist
+ - name: Publish pip release
+ run: |
+ export HOST_UID=$(id -u)
+ docker load < "image-${{env.PKG_NAME}}-${PKG_VERSION}-py3.8-alpine.tar.gz"
+ docker-compose -f docker-compose-build.yaml run \
+ -e TWINE_USERNAME=${TWINE_USERNAME} -e TWINE_PASSWORD=${TWINE_PASSWORD} element \
+ sh -lc "pip install twine && python -m twine upload dist/*"
+ - name: Determine pip artifact paths
+ run: |
+ echo "PKG_WHEEL_PATH=$(ls dist/${PKG_NAME}-*.whl)" >> $GITHUB_ENV
+ echo "PKG_SDIST_PATH=$(ls dist/${SDIST_PKG_NAME}-*.tar.gz)" >> $GITHUB_ENV
+ - name: Upload pip wheel asset to release
+ uses: actions/upload-release-asset@v1
+ env:
+ GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+ with:
+ upload_url: ${{steps.create_gh_release.outputs.upload_url}}
+ asset_path: ${{env.PKG_WHEEL_PATH}}
+ asset_name: pip-${{env.PKG_NAME}}-${{env.PKG_VERSION}}.whl
+ asset_content_type: application/zip
+ - name: Upload pip sdist asset to release
+ uses: actions/upload-release-asset@v1
+ env:
+ GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+ with:
+ upload_url: ${{steps.create_gh_release.outputs.upload_url}}
+ asset_path: ${{env.PKG_SDIST_PATH}}
+ asset_name: pip-${{env.SDIST_PKG_NAME}}-${{env.PKG_VERSION}}.tar.gz
+ asset_content_type: application/gzip
diff --git a/Background.md b/Background.md
deleted file mode 100644
index c1895d1..0000000
--- a/Background.md
+++ /dev/null
@@ -1,81 +0,0 @@
-
-
-# Miniscope Element
-
-## Description of modality, user population
-
-Miniature fluorescence microscopes (miniscopes) are a head-mounted calcium imaging full-frame video modality first introduced in 2005 by Mark Schnitzer's lab ([Flusberg et al., Optics Letters 2005](https://pubmed.ncbi.nlm.nih.gov/16190441/)). Due to their light weight, these miniscopes allow measuring the dynamic activity of populations of cortical neurons in freely behaving animals. In 2011, Inscopix Inc. was founded to support one-photon miniscopes as a commercial neuroscience research platform, providing proprietary hardware, acquisition software, and analysis software. Today, they estimate their active user base is 491 labs with a total of 1179 installs. An open-source alternative was launched by a UCLA team led by Daniel Aharoni and Peyman Golshani ([Cai et al., Nature 2016](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5063500/); [Aharoni and Hoogland, Frontiers in Cellular Neuroscience 2019](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6461004/)). In our conversation with Dr. Aharoni, he estimated about 700 labs currently using the UCLA system alone. The Inscopix user base is smaller but more established. Several two-photon miniscopes have been developed but lack widespread adoption likely due to the expensive hardware required for the two-photon excitation ([Helmchen et al., Neuron 2001](https://pubmed.ncbi.nlm.nih.gov/11580892/); [Zong et al., Nature Methods 2017](https://pubmed.ncbi.nlm.nih.gov/28553965/); [Aharoni and Hoogland, Frontiers in Cellular Neuroscience 2019](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6461004/)). Due to the low costs and ability to record during natural behaviors, one-photon miniscope imaging appears to be the fastest growing calcium imaging modality in the field today. In Year 1, we focused our efforts on supporting the UCLA platform due its fast growth and deficiency of standardization in acquisition and processing pipelines. In future phases, we will reach out to Inscopix to support their platform as well.
-
-
-## Acquisition tools
-Daniel Aharoni's lab has developed iterations of the UCLA Miniscope platform. Based on interviews, we have found labs using the two most recent versions including [Miniscope DAQ V3](http://miniscope.org/index.php/Information_on_the_(previous_Version_3)_Miniscope_platform) and [Miniscope DAQ V4](https://github.com/Aharoni-Lab/Miniscope-v4/wiki). Labs also use the Bonsai OpenEphys tool for data acquisition with the UCLA miniscope. Inscopix provides the Inscopix Data Acquisition Software (IDAS) for the nVista and nVoke systems.
-
-## Preprocessing tools
-The preprocessing workflow for miniscope imaging includes denoising, motion correction, cell segmentation, and calcium event extraction (sometimes described as "deconvolution" or "spike inference"). For the UCLA Miniscopes, the following [analysis packages](https://github.com/Aharoni-Lab/Miniscope-v4/wiki/Analysis-Packages) are commonly used:
-
-(Package, Developer [Affiliation], Programming Language)
-
-+ [Miniscope Denoising](https://github.com/Aharoni-Lab/Miniscope-v4/wiki/Removing-Horizontal-Noise-from-Recordings), Daniel Aharoni (UCLA), Python
-+ [NoRMCorre](https://github.com/flatironinstitute/NoRMCorre), Flatiron Institute, MATLAB
-+ [CNMF-E](https://github.com/zhoupc/CNMF_E), Pengcheng Zhou (Liam Paninski’s Lab, Columbia University), MATLAB
-+ [CaImAn](https://github.com/flatironinstitute/CaImAn), Flatiron Institute, Python
-+ [miniscoPy](https://github.com/PeyracheLab/miniscoPy), Guillaume Viejo (Adrien Peyrache’s Lab, McGill University), Python
-+ [MIN1PIPE](https://github.com/JinghaoLu/MIN1PIPE), Jinghao Lu (Fan Wang’s Lab, MIT), MATLAB
-+ [CIAtah](https://github.com/bahanonu/calciumImagingAnalysis), Biafra Ahanonu, MATLAB
-+ [MiniAn](https://github.com/DeniseCaiLab/minian), Phil Dong (Denise Cai's Lab, Mount Sinai), Python
-+ [MiniscopeAnalysis](https://github.com/etterguillaume/MiniscopeAnalysis), Guillaume Etter (Sylvain Williams’ Lab, McGill University), MATLAB
-+ [PIMPN](https://github.com/etterguillaume/PIMPN), Guillaume Etter (Sylvain Williams’ Lab, McGill University), Python
-+ [CellReg](https://github.com/zivlab/CellReg), Liron Sheintuch (Yaniv Ziv’s Lab, Weizmann Institute of Science), MATLAB
-+ Inscopix Data Processing Software (IDPS)
-+ Inscopix Multimodal Image Registration and Analysis (MIRA)
-
-Based on interviews with UCLA and Inscopix miniscope users and developers, each research lab uses a different preprocessing workflow. These custom workflows are often closed source and not tracked with version control software. For the preprocessing tools that are open source, they are often developed by an individual during their training period and lack funding for long term maintenance. These factors result in a lack of standardization for miniscope preprocessing tools, which is a major obstacle to adoption for new labs.
-
-
-## Precursor projects and interviews
-Until recently, DataJoint had not been used for miniscope pipelines. However, labs we have contacted have been eager to engage and adopt DataJoint-based workflows in their labs.
-
-(Date, Person [Role], Lab, Institution)
-
-+ March 16, 2021, Niccoló Calcini (Postdoctoral scholar) & Antoine Adamantidis (Associate Professor), Antoine Adamantidis’ Lab, University of Bern
-+ March 12, 2021, Biafra Ahanonu (Postdoctoral scholar), Allan Basbaum’s Lab, UCSF
-+ March 1, 2021, Lukas Oesch (Postdoctoral scholar), Anne Churchland’s Lab, UCLA
-+ February 25, 2021, Manolis Froudarakis (Assistant Professor), Manolis Froudarakis’ Lab, FORTH
-+ February 22, 2021, Jinghao Lu (Doctoral student) & Vincent Prevosto (Research scientist), Fan Wang’s Lab, MIT
-+ February 12, 2021, Guillaume Viejo (Postdoctoral scholar) & Adrien Peyrache (Assistant Professor), Adrien Peyrache’s Lab, McGill University
-+ February 11, 2021, Daniel Aharoni (Assistant Professor), Daniel Aharoni’s Lab, UCLA
-+ January 29, 2021, Pingping Zhao & Ronen Reshef (Postdoctoral scholars), Peyman Golshani’s Lab, UCLA
-
-## Pipeline Development
-
-With assistance from Peyman Golshani’s Lab (UCLA) we have added support for the UCLA Miniscope DAQ V3 acquisition tool and MiniscopeAnalysis preprocessing tool in `element-miniscope` and `workflow-miniscope`. They have provided example data for development, and will begin validating in March 2021.
-
-Based on interviews, we are considering adding support for the tools listed below. The deciding factors include the number of users, long term support, quality controls, and python programming language (so that the preprocessing tool can be triggered within the element).
-
-+ Acquisition tools
- + Miniscope DAQ V4
- + Inscopix Data Acquisition Software (IDAS)
-+ Preprocessing tools
- + Inscopix Data Processing Software (IDPS)
- + Inscopix Multimodal Image Registration and Analysis (MIRA)
- + MiniAn
- + CaImAn
- + CNMF-E
- + CellReg
-
-## Alpha release: Validation sites
-
-We have recruited the following teams as alpha users to jointly develop and validate the miniscope workflow in their experiments.
-
-(Lab [PI], Institution, Hosting arrangement, Start time, Experiment 0 target)
-
-+ Peyman Golshani, UCLA, djHub, January 2021, March 2021
-+ Anne Churchland, UCLA, Lab server, April 2021, May 2021
-+ Fan Wang, MIT, djHub, April 2021, May 2021
-+ Antoine Adamantidis, University of Bern, djHub, April 2021, June 2021
-+ Manolis Froudarakis, FORTH, Lab server, April 2021, June 2021
-
-## Beta release
-As the validation progresses, we expect to produce a beta version of the workflow for users to adopt independently by May 1, 2021.
-
-
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..912de5b
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,13 @@
+# Changelog
+
+Observes [Semantic Versioning](https://semver.org/spec/v2.0.0.html) standard and [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) convention.
+
+## Unreleased - 2022-04-25
++ Add - Load data acquired with Miniscope-DAQ-V4
++ Add - Load data analyzed with CaImAn
++ Add - Trigger CaImAn analysis
++ Remove - Load data analyzed with MiniscopeAnalysis
+
+## 0.1.1 - 2021-04-01
++ Add - Load data acquired with Miniscope-DAQ-V3
++ Add - Load data analyzed with MiniscopeAnalysis
\ No newline at end of file
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..c144a40
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,15 @@
+ARG PY_VER
+ARG DISTRO
+ARG IMAGE
+ARG PKG_NAME
+ARG PKG_VERSION
+
+FROM datajoint/${IMAGE}:py${PY_VER}-${DISTRO}
+COPY --chown=anaconda:anaconda ./requirements.txt ./setup.py \
+ /main/
+COPY --chown=anaconda:anaconda ./${PKG_NAME} /main/${PKG_NAME}
+RUN \
+ cd /main && \
+ pip install . && \
+ rm -R /main/*
+WORKDIR /main
diff --git a/LICENSE b/LICENSE
index d394fe3..2f92789 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
MIT License
-Copyright (c) 2021 DataJoint NEURO
+Copyright (c) 2022 DataJoint
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
index b84bd9e..bd95a9b 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,23 @@
# DataJoint Element - Miniscope Calcium Imaging
-+ This repository features DataJoint pipeline design for functional calcium imaging,
-with `Miniscope DAQ V3` acquisition system and `MiniscopeAnalysis` suite for analysis.
++ This repository features a DataJoint pipeline design for functional calcium imaging
+data acquired with the UCLA Miniscope and `Miniscope DAQ V4` acquisition system, and
+analyzed with `CaImAn`.
+ The element presented here is not a complete workflow by itself,
- but rather a modular design of tables and dependencies specific to the functional calcium imaging workflow.
+ but rather a modular design of tables and dependencies specific to the miniscope
+ functional calcium imaging workflow.
-+ This modular element can be flexibly attached downstream to
-any particular design of experiment session, thus assembling
-a fully functional calcium imaging workflow.
++ This modular element can be flexibly attached downstream to any particular design of
+experiment session, thus assembling a fully functional miniscope workflow.
-+ See [Background](Background.md) for the background information and development timeline.
++ See the [Element Miniscope documentation](
+ https://elements.datajoint.org/description/miniscope/) for the background
+ information and development timeline.
-+ See [DataJoint Elements](https://github.com/datajoint/datajoint-elements) for descriptions of the other `elements` and `workflows` developed as part of this initiative.
-
-## Element usage
-
-+ See [workflow-miniscope](https://github.com/datajoint/workflow-miniscope)
-repository for an example usage of `element-miniscope`.
++ For more information on the DataJoint Elements project, please visit
+https://elements.datajoint.org. This work is supported by the National Institutes of
+Health.
## Element architecture
@@ -25,47 +25,151 @@ repository for an example usage of `element-miniscope`.
+ As the diagram depicts, `elements-miniscope` starts immediately downstream from `Session`, and also requires some notion of:
- + `Scanner` for equipment/device
+ + `Equipment` for equipment/device
- + `Location` as a dependency for `ScanLocation`
+ + `AnatomicalLocation` as a dependency for `RecordingLocation`
-### Scan
+## Table definitions
-+ A `Session` (more specifically an experimental session) may have multiple scans, where each scan describes a complete 4D dataset (i.e. 3D volume over time) from one scanning session, typically from the moment of pressing the *start* button to pressing the *stop* button.
+The `miniscope` schema contains all tables in this Element, including for the
+acquired metadata and analysis results.
-+ `Scan` - table containing information about the equipment used (e.g. the Scanner information)
+### Recording
-+ `ScanInfo` - meta information about this scan, from ScanImage header (e.g. frame rate, number of channels, scanning depths, frames, etc.)
+
+Click to expand details
-+ `ScanInfo.Field` - a field is a 2D image at a particular xy-coordinate and plane (scanning depth) within the field-of-view (FOV) of the scan.
++ A `Session` (more specifically an experimental session) may have multiple recordings,
+where each recording describes a complete 3D dataset (i.e. 2d image over time) from one
+recording session, typically from the moment of pressing the start button to pressing
+the stop button.
- + For resonant scanner, a field is usually the 2D image occupying the entire FOV from a certain plane (at some depth).
++ `Recording` - table containing information about the equipment used
+(e.g. the acquisition hardware information)
- + For mesoscope scanner, with much wider FOV, there may be multiple fields on one plane.
++ `RecordingInfo` - metadata about this recording from the Miniscope DAQ software
+(e.g. frame rate, number of channels, frames, etc.)
+
+
### Motion correction
-+ `MotionCorrection` - motion correction information performed on a scan
+
+Click to expand details
+
++ `MotionCorrection` - motion correction information performed on a recording
-+ `MotionCorrection.RigidMotionCorrection` - details of the rigid motion correction (e.g. shifting in x, y) at a per `ScanInfo.Field` level
++ `MotionCorrection.RigidMotionCorrection` - details of the rigid motion correction
+(e.g. shifting in x, y)
-+ `MotionCorrection.NonRigidMotionCorrection` and `MotionCorrection.Block` tables are used to describe the non-rigid motion correction performed on each `ScanInfo.Field`
++ `MotionCorrection.NonRigidMotionCorrection` and `MotionCorrection.Block` tables are
+used to describe the non-rigid motion correction.
+
++ `MotionCorrection.Summary` - summary images after motion correction
+(e.g. average image, correlation image, etc.)
+
+
-+ `MotionCorrection.Summary` - summary images for each `ScanInfo.Field` after motion correction (e.g. average image, correlation image)
-
### Segmentation
-+ `Segmentation` - table specifies the segmentation step and its outputs, following the motion correction step.
-
-+ `Segmentation.Mask` - image mask for the segmented region of interest from a particular `ScanInfo.Field`
+
+Click to expand details
+
++ `Segmentation` - table specifies the segmentation step and its outputs, following the
+ motion correction step.
+
++ `Segmentation.Mask` - image mask for the segmented region of interest
+
++ `MaskClassification` - classification of `Segmentation.Mask` into a type
+ (e.g. soma, axon, dendrite, artifact, etc.)
-+ `MaskClassification` - classification of `Segmentation.Mask` into different type (e.g. soma, axon, dendrite, artifact, etc.)
+
### Neural activity extraction
+
+Click to expand details
+
+ `Fluorescence` - fluorescence traces extracted from each `Segmentation.Mask`
-+ `ActivityExtractionMethod` - activity extraction method (e.g. deconvolution) to be applied on fluorescence trace
++ `ActivityExtractionMethod` - activity extraction method (e.g. deconvolution) applied
+ on the fluorescence trace
+ `Activity` - computed neuronal activity trace from fluorescence trace (e.g. spikes)
+
+
+## Installation
+
++ The installation instructions can be found at the
+[DataJoint Elements documentation](https://elements.datajoint.org/usage/install/).
+
++ Install `element-miniscope`
+ ```
+ pip install element-miniscope
+ ```
+
++ Install `element-interface`
+
+ + `element-interface` contains data loading utilities for `element-miniscope`.
+
+ + `element-interface` is a dependency of `element-miniscope`, however it is not contained within `requirements.txt`, therefore, must be installed in addition to the installation of the `element-miniscope`.
+ ```bash
+ pip install "element-interface @ git+https://github.com/datajoint/element-interface"
+ ```
+
+ + `element-interface` can also be used to install packages used for reading acquired data and running analysis (e.g. `CaImAn`).
+
+ + If your workflow uses these packages, you should install them when you install `element-interface`.
+
+## Usage
+
+### Element activation
+
+When using this Element, one needs to run `miniscope.activate` to declare the schemas
+and tables on the database.
+
+
+Click to expand details
+
+To activate `element-miniscope`, ones need to provide:
+
+1. Schema names
+ + schema name for the miniscope module
+
+2. Upstream tables
+ + Session table: A set of keys identifying a recording session (see [Element-Session](https://github.com/datajoint/element-session)).
+ + Equipment table: A reference table for Recording, specifying the equipment used for the acquisition (see [example pipeline](https://github.com/datajoint/workflow-miniscope/blob/main/workflow_miniscope/pipeline.py)).
+ + AnatomicalLocation table: A reference table for RecordingLocation, specifying
+ the brain location where the recording is acquired
+
+3. Utility functions. See [example definitions here](https://github.com/datajoint/workflow-miniscope/blob/main/workflow_miniscope/paths.py).
+ + get_miniscope_root_data_dir(): Returns your root data directory.
+ + get_session_directory(): Returns the path of the session data relative to the
+ root directory.
+
+For more details, check the docstring of `element-miniscope`:
+```python
+ help(miniscope.activate)
+```
+
+
+
+### Element usage
+
++ See the [workflow-miniscope](https://github.com/datajoint/workflow-miniscope)
+repository for an example usage of `element-miniscope`.
+
+## Citation
+
++ If your work uses DataJoint and DataJoint Elements, please cite the respective Research Resource Identifiers (RRIDs) and manuscripts.
+
++ DataJoint for Python or MATLAB
+ + Yatsenko D, Reimer J, Ecker AS, Walker EY, Sinz F, Berens P, Hoenselaar A, Cotton RJ, Siapas AS, Tolias AS. DataJoint: managing big scientific data using MATLAB or Python. bioRxiv. 2015 Jan 1:031658. doi: https://doi.org/10.1101/031658
+
+ + DataJoint ([RRID:SCR_014543](https://scicrunch.org/resolver/SCR_014543)) - DataJoint for `