Merge pull request #24 from kabilar/main

Update readme and docs

Author: Thinh Nguyen

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: false
 contact_links:
   - name: DataJoint Contribution Guideline
-    url: https://docs.datajoint.org/python/community/02-Contribute.html
+    url: https://datajoint.com/docs/community/contribute/
     about: Please make sure to review the DataJoint Contribution Guidelines

.github/workflows/u24_element_release_call.yaml

@@ -17,7 +17,6 @@ jobs:
     secrets:
       TWINE_USERNAME: ${{secrets.TWINE_TEST_USERNAME}}
       TWINE_PASSWORD: ${{secrets.TWINE_TEST_PASSWORD}}
-      GOOGLE_ANALYTICS_KEY: ${{secrets.GOOGLE_ANALYTICS_KEY}}
   call_u24_elements_release_alpine:
     if: >-
       github.event.workflow_run.conclusion == 'success' && github.repository_owner == 'datajoint' && !contains(github.event.workflow_run.head_branch, 'test')
@@ -27,4 +26,3 @@ jobs:
     secrets:
       TWINE_USERNAME: ${{secrets.TWINE_USERNAME}}
       TWINE_PASSWORD: ${{secrets.TWINE_PASSWORD}}
-      GOOGLE_ANALYTICS_KEY: ${{secrets.GOOGLE_ANALYTICS_KEY}}

CHANGELOG.md

@@ -3,10 +3,11 @@
 Observes [Semantic Versioning](https://semver.org/spec/v2.0.0.html) standard and
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) convention.
 
-## [0.1.3] - Unreleased
+## [0.1.3] - 2023-04-06
 
 + Add - Notebook rendering in docs
 + Add - Pre-commit, cspell, and markdown linters
++ Update - Docs and readme
 
 ## [0.1.2] - 2022-10-21
 

README.md

@@ -1,12 +1,26 @@
 # DataJoint Element - Electrode Localization
 
-DataJoint Element for electrode localization using Allen Brain Atlases. DataJoint
-Elements collectively standardize and automate data collection and analysis for
-neuroscience experiments.  Each Element is a modular pipeline for data storage and
-processing with corresponding database tables that can be combined with other Elements
+DataJoint Element for localizing Neuropixels electrodes within the Allen brain atlas - 
+[Allen Mouse Common Coordinate Framework (CCF)](http://atlas.brain-map.org/). DataJoint 
+Elements collectively standardize and automate data collection and analysis for 
+neuroscience experiments. Each Element is a modular pipeline for data storage and 
+processing with corresponding database tables that can be combined with other Elements 
 to assemble a fully functional pipeline.
 
-![diagram](https://raw.githubusercontent.com/datajoint/element-electrode-localization/main/images/diagram_flowchart.svg)
+## Experiment Flowchart
 
-Installation and usage instructions can be found at the
-[Element documentation](https://datajoint.com/docs/elements/element-electrode-localization).
+![flowchart](https://raw.githubusercontent.com/datajoint/element-electrode-localization/main/images/flowchart.svg)
+
+## Data Pipeline
+
+![pipeline](https://raw.githubusercontent.com/datajoint/element-electrode-localization/main/images/pipeline.svg)
+
+## Getting Started
+
++ Install from PyPI
+
+     ```bash
+     pip install element-electrode-localization
+     ```
+
++ [Documentation & Tutorials](https://datajoint.com/docs/elements/element-electrode-localization)

docs/.docker/pip_requirements.txt

@@ -8,4 +8,5 @@ mkdocs-gen-files
 mkdocs-literate-nav
 mkdocs-exclude-search
 mkdocs-markdownextradata-plugin
-mkdocs-jupyter
+mkdocs-jupyter
+mkdocs-section-index

docs/docker-compose.yaml

@@ -1,6 +1,4 @@
 # MODE="LIVE|QA|BUILD" PACKAGE=element_electrode_localization UPSTREAM_REPO=https://github.com/datajoint/element-electrode-localization.git HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
-#
-# navigate to http://localhost/
 version: "2.4"
 services:
   docs:

docs/mkdocs.yaml

@@ -6,10 +6,11 @@ repo_url: https://github.com/datajoint/element-electrode-localization
 repo_name: datajoint/element-electrode-localization
 nav:
   - Element Electrode Localization: index.md
-  - Concepts: concepts.md
+  - Data Pipeline: pipeline.md
   - Tutorials: 
-    - Overview: tutorials/index.md
+    - tutorials/index.md
     - Notebook: tutorials/08-electrode-localization.ipynb
+  - Concepts: concepts.md
   - Citation: citation.md
   - API: api/ # defer to gen-files + literate-nav
   - Changelog: changelog.md
@@ -44,17 +45,14 @@ nav:
 #     UPSTREAM_REPO=https://github.com/datajoint/element-{ELEMENT}.git \
 #     HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
 #     ```
-# 02. Site analytics depend on a local environment variable GOOGLE_ANALYTICS_KEY
-#     You can find this in LastPass or declare with any string to suppress errors
-# 03. The API section will pull docstrings.
+# 02. The API section will pull docstrings.
 #     A. Follow google style guide e.g., 
 #        https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
 #        With typing suggestions: https://docs.python.org/3/library/typing.html
 #     B. To pull a specific workflow fork, change ./docs/src/api/make_pages.py#L19
-# 04. To see your fork of the workflow-{element} in this render, change the
+# 03. To see your fork of the workflow-{element} in this render, change the
 #     URL in ./docs/src/api/make_pages.py#L19 to your fork.
-# 05. For redirecting options For redirect options, see 'redirects' below.
-# 06. To deploy this site on your fork, 
+# 04. To deploy this site on your fork, 
 #     A. declare a branch called gh-pages
 #     B. go to the your fork > settings > pages 
 #     C. direct pages to render from the gh-pages branch at root
@@ -89,9 +87,7 @@ theme:
 plugins:
   - markdownextradata: {}
   - search
-  # - redirects: # OPTIONAL REDIRECTS
-  #     redirect_maps:
-  #       "index.md": "getting_started.md"
+  - section-index
   - mkdocstrings:
       default_handler: python
       handlers:
@@ -110,7 +106,6 @@ plugins:
         - "*/navigation.md"
   - mkdocs-jupyter:
       ignore_h1_titles: True
-  - footnotes
 markdown_extensions:
   - attr_list
   - toc:
@@ -131,13 +126,13 @@ markdown_extensions:
       linenums: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
-  
+  - footnotes
+  - pymdownx.magiclink # Displays bare URLs as links
+  - pymdownx.tasklist: # Renders check boxes in tasks lists
+      custom_checkbox: true
 extra:
   PATCH_VERSION: !ENV PATCH_VERSION
   generator: false # Disable watermark
-  analytics:
-    provider: google
-    property: !ENV GOOGLE_ANALYTICS_KEY
   version:
     provider: mike
   social:

docs/src/citation.md

@@ -7,5 +7,4 @@ Resource Identifier (RRID).
   Reimer J, Walker EY, Tolias AS. DataJoint Elements: Data Workflows for
   Neurophysiology. bioRxiv. 2021 Jan 1. doi: https://doi.org/10.1101/2021.03.30.437358
 
-+ DataJoint Elements ([RRID:SCR_021894](https://scicrunch.org/resolver/SCR_021894)) -
-  Element Electrode Localization (version {{ PATCH_VERSION }})
++ DataJoint Element Electrode Localization - [RRID:SCR_021894](https://scicrunch.org/resolver/SCR_021894) - Version {{ PATCH_VERSION }}

docs/src/concepts.md

@@ -7,64 +7,29 @@ studies wherein in vitro slices were compared to develop a complete model of the
 With dyes, researchers could compare recordings to the reconstructed location of a given
 recording device. Through clever experimental design, researchers could further
 associate highly localized regions to their task-dependent function. Advances in 3D
-modeling have permitted parallel advances in multi-subject averaged anatomical models.
-An atlas serves as a shared reference frame for a given species.
-[The Allen Institute](https://mouse.brain-map.org/) has been a leader in the development
-of mouse atlases since 2007[^1], with regular
-updates[^2] that provide researchers with a shared reference
-frame in the study of functional neuroanatomy.
-
-[^1]: Lein, E. S., Hawrylycz, M. J., Ao, N., Ayres, M., Bensinger, A., Bernard, A., ...
-    & Jones, A. R. (2007). Genome-wide atlas of gene expression in the adult mouse
-    brain. *Nature*, 445(7124), 168-176.
-
-[^2]: Wang, Q., Ding, S. L., Li, Y., Royall, J., Feng, D., Lesnar, P., ... & Ng, L.
-    (2020). The Allen mouse brain common coordinate framework: a 3D reference atlas.
-    *Cell*, 181(4), 936-953.
-
-## Element Architecture
-
-Each of the DataJoint Elements are a set of tables for common neuroinformatics
-modalities to organize, preprocess, and analyze data. Each node in the following diagram
-is either a table in the Element itself or a table that would be connected to the
-Element.
-
-![element-electrode-localization diagram](https://raw.githubusercontent.com/datajoint/element-electrode-localization/main/images/diagram_electrode_localization.svg)
-
-The Element is separated into two schemas:
-
-+ `coordinate_framework` ingests standard atlases and retains voxel-based lookup tables,
-  including references to brain region information, acronyms and standardized color
-  codes.
-+ `electrode_localization` pairs the above reference tables with Neuropixels probe
-  location data in a `probe` schema, optionally from
-  [Element Array Ephys](https://github.com/datajoint/element-array-ephys)
+modeling have permitted parallel advances in multi-subject averaged anatomical atlases, 
+which serve as a shared reference frame to study functional neuroanatomy.
+The [Allen Institute](https://mouse.brain-map.org/){:target="_blank"} has been a leader in the development of such mouse atlases since 2007 
+([Lein et al., Nature 2007](https://doi.org/10.1038/nature05453){:target="_blank"}; 
+[Wang et al., Cell 2020](https://doi.org/10.1016/j.cell.2020.04.007){:target="_blank"}).
 
 ## Key Partnerships
 
-In coordination with both the Mesoscale Activity Project and the International Brain
-Lab, DataJoint developed mechanisms for pairing recording coordinates with the published
-atlases in project-specific cases that have since been generalized.
-
-## Pipeline Development and Limitations
-
-The Element's table architecture was generalized from existing project-specific
-pipelines such as International Brain Laboratory's
-[iblapps](https://github.com/int-brain-lab/iblapps/wiki/) as well as the Allen
-Institute's
-[atlas files](https://community.brain-map.org/t/allen-mouse-ccf-accessing-and-using-related-data-and-tools/359).
+Labs have developed project-specific DataJoint pipelines for pairing the coordinates of recording electrodes with the location in published atlases. The DataJoint team collaborated with several and interviewed these teams to understand their experiment workflow, associated tools, and interfaces. These teams include:
 
-One notable consession was made in development: acronyms in DataJoint do not perfectly
-map on to the Allen Institute's published standard. By default, DataJoint databases are
-not case sensitive. Instead, acronyms are converted to
-[snake case](https://en.wikipedia.org/wiki/Snake_case) to avoid naming collisions. While
-we depart from the standard, preliminary interviews with users indicate no bias toward
-the official standard. Visit our
-[localization notebook](https://github.com/datajoint/workflow-array-ephys/blob/main/notebooks/08-electrode-localization.ipynb)
-for a demonstration of converting between the case sensitive and snake case standards.
++ Mesoscale Activity Project
++ International Brain Lab
 
-## Roadmap
+## Element Roadmap
 
+Through our interviews and direct collaboration on the key projects, we identified the common motifs to create Element Electrode Localization with the repository hosted on [GitHub](https://github.com/datajoint/element-electrode-localization){:target="_blank"}.
 Further development of this Element is community driven. Upon user requests we will
 continue adding features to this Element, such as improved region- and subregion-based
 topological referencing.
+
+- [x] Generalize the table architecture from existing project-specific pipelines:
+
+  - [x] International Brain Laboratory's 
+[iblapps](https://github.com/int-brain-lab/iblapps/wiki/){:target="_blank"}
+
+  - [x] Allen Institute's [atlas files](https://community.brain-map.org/t/allen-mouse-ccf-accessing-and-using-related-data-and-tools/359){:target="_blank"}

docs/src/index.md

@@ -1,10 +1,32 @@
 # Element Electrode Localization
 
-This Element features DataJoint schemas for localizing Neuropixels electrodes within
-the [Allen Mouse Common Coordinate Framework (CCF)](http://atlas.brain-map.org/).
+DataJoint Element for localizing Neuropixels electrodes within the Allen brain atlas - 
+[Allen Mouse Common Coordinate Framework (CCF)](http://atlas.brain-map.org/){:target="_blank"}. DataJoint 
+Elements collectively standardize and automate data collection and analysis for 
+neuroscience experiments. Each Element is a modular pipeline for data storage and 
+processing with corresponding database tables that can be combined with other Elements 
+to assemble a fully functional pipeline.
 
-![diagram](https://raw.githubusercontent.com/datajoint/element-electrode-localization/main/images/diagram_flowchart.svg)
+## Experiment Flowchart
 
-The Element consists of `coordinate_framework` and `electrode_localization`. Visit the
-[Concepts page](./concepts.md) for more information about the use cases of this Element
-and an explanation of the tables.
+![flowchart](https://raw.githubusercontent.com/datajoint/element-electrode-localization/main/images/flowchart.svg)
+
+## Data Pipeline
+
+![pipeline](https://raw.githubusercontent.com/datajoint/element-electrode-localization/main/images/pipeline.svg)
+
+## Getting Started
+
++ Install from PyPI
+
+     ```bash
+     pip install element-electrode-localization
+     ```
+
++ [Data Pipeline](./pipeline.md) - Pipeline and table descriptions
+
++ [Tutorials](./tutorials.md) - Start building your data pipeline
+
++ [Concepts](./concepts.md) - Key partnerships and roadmap
+
++ [Code Repository](https://github.com/datajoint/element-electrode-localization/){:target="_blank"}