Skip to content

Commit 470198d

Browse files
dimitri-yatsenkodimitri-yatsenko
authored
Merge pull request #62 from CBroz1/docs
Adds docs
2 parents a2d2c94 + 8157fa9 commit 470198d

27 files changed

+888
-317
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# User data
22
.DS_Store
3+
temp*
34

45
# Byte-compiled / optimized / DLL files
56
__pycache__/

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22

33
Observes [Semantic Versioning](https://semver.org/spec/v2.0.0.html) standard and [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) convention.
44

5+
## [0.3.1] - Unreleased
6+
7+
+ Add - mkdocs documentation
8+
+ Add - improved docstrings for mkdocs
9+
510
## [0.3.0] - 2022-10-7
611

712
+ Add - Function `prairieviewreader` to parse metadata from Bruker PrarieView acquisition system

‎README.md‎

Lines changed: 9 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -1,109 +1,11 @@
1-
# DataJoint Elements Interface for external analysis packages
1+
# Elements Interface for external analysis packages
22

3-
+ This repository serves a few purposes:
4-
+ Load neurophysiological data into the
5-
[DataJoint Elements](https://github.com/datajoint/datajoint-elements).
6-
+ Trigger packages used for neurophysiological data processing.
7-
+ Functions common to the DataJoint Elements (e.g. search directory tree for data files).
3+
DataJoint Element for interoperability with other software. DataJoint Elements
4+
collectively standardize and automate data collection and analysis for neuroscience
5+
experiments. Typical Elements are modular pipelines for data storage and processing with
6+
corresponding database tables that can be combined with other Elements to assemble a
7+
fully functional pipeline. Element Interface is home to a number of utilities that make
8+
this possible.
89

9-
+ See [DataJoint Elements](https://github.com/datajoint/datajoint-elements) for descriptions
10-
of the `elements` and `workflows` developed as part of this initiative.
11-
12-
# Architecture
13-
14-
+ The functions for each acquisition and analysis package are stored within a separate module.
15-
16-
+ Acquisition packages
17-
+ `scanimage_utils.py`
18-
19-
+ Analysis packages
20-
+ `suite2p_loader.py`
21-
+ `caiman_loader.py`
22-
+ `run_caiman.py`
23-
24-
# Installation
25-
26-
+ Install `element-interface`:
27-
```
28-
pip install element-interface
29-
```
30-
31-
+ This package is to be used in combination with the other DataJoint Elements (e.g. `element-calcium-imaging`). The installation of packages used for data processing (e.g. `Suite2p`) will be included within the respective DataJoint Element (e.g. `element-calcium-imaging`).
32-
33-
# Usage
34-
35-
+ See the [workflow-calcium-imaging](https://github.com/datajoint/workflow-calcium-imaging)
36-
and [element-calcium-imaging](https://github.com/datajoint/element-calcium-imaging)
37-
repositories for example usage of `element-interface`.
38-
39-
+ ScanImage
40-
```python
41-
import scanreader
42-
from element_interface import scanimage_utils
43-
44-
# ScanImage file path
45-
scan_filepath = '<imaging_root_data_dir>/subject1/session0/<scan_filename>.tif'
46-
47-
loaded_scan = scanreader.read_scan(scan_filepath)
48-
49-
recording_time = scanimage_utils.get_scanimage_acq_time(loaded_scan)
50-
header = scanimage_utils.parse_scanimage_header(loaded_scan)
51-
```
52-
53-
+ Suite2p
54-
```python
55-
from element_interface import suite2p_loader
56-
57-
# Directory containing Suite2p output
58-
output_dir = '<imaging_root_data_dir>/subject1/session0/suite2p'
59-
60-
loaded_dataset = suite2p_loader.Suite2p(output_dir)
61-
```
62-
63-
+ Suite2p wrapper functions for triggering analysis
64-
65-
+ Functions to independently run Suite2p's motion correction, segmentation, and deconvolution steps. These functions currently work for single plane tiff files. If running all Suite2p pre-processing steps concurrently, these functions are not required and one can run `suite2p.run_s2p()`.
66-
67-
+ These wrapper functions were developed primarily because `run_s2p` cannot individually run deconvolution using the `spikedetect` flag ([Suite2p Issue #718](https://github.com/MouseLand/suite2p/issues/718)).
68-
69-
+ Requirements
70-
+ [ops dictionary](https://suite2p.readthedocs.io/en/latest/settings.html)
71-
+ [db dictionary](https://github.com/MouseLand/suite2p/blob/4b6c3a95b53e5581dbab1feb26d67878db866068/jupyter/run_pipeline_tiffs_or_batch.ipynb)
72-
73-
+ Note that the ops dictionary returned from the `motion_correction_suite2p` and `segmentation_suite2p` functions is only a subset of the keys generated with the `suite2p.default_ops()` function.
74-
75-
```python
76-
import element_interface
77-
import suite2p
78-
79-
ops = dict(suite2p.default_ops(), nonrigid=False, two_step_registration=False)
80-
81-
db = {
82-
'h5py': [], # single h5 file path
83-
'h5py_key': 'data',
84-
'look_one_level_down': False, # search for TIFFs in all subfolders
85-
'data_path': ['/test_data'], # list of folders with tiffs
86-
'subfolders': [], # choose subfolders of 'data_path'
87-
'fast-disk': '/test_data' # string path for storing binary file
88-
}
89-
90-
ops.update(do_registration=1, roidetect=False, spikedetect=False)
91-
motion_correction_ops = element_interface.suite2p_trigger.motion_correction_suite2p(ops, db)
92-
93-
motion_correction_ops.update(do_registration=0, roidetect=True, spikedetect=False)
94-
segmentation_ops = element_interface.suite2p_trigger.segmentation_suite2p(motion_correction_ops, db)
95-
96-
segmentation_ops.update(do_registration=0, roidetect=False, spikedetect=True)
97-
spikes = element_interface.suite2p_trigger.deconvolution_suite2p(segmentation_ops, db)
98-
```
99-
100-
101-
+ CaImAn
102-
```python
103-
from element_interface import caiman_loader
104-
105-
# Directory containing CaImAn output
106-
output_dir = '<imaging_root_data_dir>/subject1/session0/caiman'
107-
108-
loaded_dataset = caiman_loader.CaImAn(output_dir)
109-
```
10+
Installation and usage instructions can be found at the
11+
[Element documentation](https://datajoint.com/docs/elements/element-interface).

‎docs/.docker/Dockerfile‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
FROM datajoint/miniconda3:4.10.3-py3.9-alpine
2+
ARG PACKAGE
3+
WORKDIR /main
4+
COPY --chown=anaconda:anaconda ./docs/.docker/apk_requirements.txt ${APK_REQUIREMENTS}
5+
COPY --chown=anaconda:anaconda ./docs/.docker/pip_requirements.txt ${PIP_REQUIREMENTS}
6+
RUN \
7+
umask u+rwx,g+rwx,o-rwx && \
8+
/entrypoint.sh echo "Dependencies installed" && \
9+
rm ${APK_REQUIREMENTS} ${PIP_REQUIREMENTS} && \
10+
git config --global user.name "GitHub Action" && \
11+
git config --global user.email "action@github.com"&& \
12+
git config --global pull.rebase false && \
13+
git init
14+
COPY --chown=anaconda:anaconda ./${PACKAGE} /main/${PACKAGE}
15+
COPY --chown=anaconda:anaconda ./docs/mkdocs.yaml /main/docs/mkdocs.yaml
16+
COPY --chown=anaconda:anaconda ./docs/src /main/docs/src
17+
COPY --chown=anaconda:anaconda ./CHANGELOG.md /main/

‎docs/.docker/apk_requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
git

‎docs/.docker/pip_requirements.txt‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
mkdocs-material
2+
mkdocs-redirects
3+
mkdocstrings
4+
mkdocstrings-python
5+
mike
6+
mdx-truly-sane-lists
7+
mkdocs-gen-files
8+
mkdocs-literate-nav
9+
mkdocs-exclude-search
10+
mkdocs-markdownextradata-plugin

‎docs/mkdocs.yaml‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# ---------------------- PROJECT SPECIFIC ---------------------------
2+
3+
site_name: DataJoint Documentation
4+
site_url: http://localhost/docs/element/element-interface
5+
repo_url: https://github.com/datajoint/element-interface
6+
repo_name: datajoint/element-interface
7+
nav:
8+
- Element Interface: index.md
9+
- Concepts: concepts.md
10+
# - Tutorials: tutorials.md # Not needed for interface
11+
- Citation: citation.md
12+
- API: api/ # defer to gen-files + literate-nav
13+
- Changelog: changelog.md
14+
15+
# --------------------- NOTES TO CONTRIBUTORS -----------------------
16+
# Markdown in mkdocs
17+
# 01. Redering concatenates across single line breaks. This means...
18+
# A. We have to be careful to add extra line breaks around paragraphs,
19+
# including between the end of a pgf and the beginnign of bullets.
20+
# B. We can use hard wrapping to make github reviews easier to read.
21+
# VSCode Rewrap extension offers a keyboard shortcut for hard wrap
22+
# at the ruler, but don't add breaks in [multiword links](example.com)
23+
# 02. Instead of designating codeblocks with bash, use console. For example..
24+
# ```console
25+
# cd ../my_dir
26+
# ```
27+
# 03. Links across docs should ...
28+
# A. Not involve line breaks.
29+
# B. Use relative paths to docs in the same repo
30+
# C. Use lowercase and hyphens not spaces: [sub headings](./doc#sub-heading)
31+
#
32+
# Files
33+
# 01. Add a soft link to your changelog with the following
34+
# ```console
35+
# ln -s ../../CHANGELOG.md ./docs/src/changelog.md
36+
# ```
37+
#
38+
# Site rendering
39+
# 01. Deploy locally to localhost with the command
40+
# ```console
41+
# MODE="LIVE" PACKAGE=element_{ELEMENT} \
42+
# UPSTREAM_REPO=https://github.com/datajoint/element-{ELEMENT}.git \
43+
# HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
44+
# ```
45+
# 02. Site analytics depend on a local environment variable GOOGLE_ANALYTICS_KEY
46+
# You can find this in LastPass or declare with any string to suprress errors
47+
# 03. The API section will pull docstrings.
48+
# A. Follow google styleguide e.g.,
49+
# https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
50+
# With typing suggestions: https://docs.python.org/3/library/typing.html
51+
# B. To pull a specific workflow fork, change ./docs/src/api/make_pages.py#L19
52+
# 04. To see your fork of the workflow-{element} in this render, change the
53+
# URL in ./docs/src/api/make_pages.py#L19 to your fork.
54+
# 05. For redirecting options For redirect options, see 'redirects' below.
55+
# 06. To deploy this site on your fork,
56+
# A. declare a branch called gh-pages
57+
# B. go to the your fork > settings > pages
58+
# C. direct pages to render from the gh-pages branch at root
59+
# D. push a tag to your fork with the format test*.*.*
60+
#
61+
# ---------------------------- STANDARD -----------------------------
62+
edit_uri: ./edit/main/docs/src
63+
docs_dir: ./src
64+
theme:
65+
font:
66+
text: Roboto Slab
67+
code: Source Code Pro
68+
name: material
69+
custom_dir: src/.overrides
70+
icon:
71+
logo: main/project-logo-black
72+
favicon: assets/images/project-logo-color.png
73+
features:
74+
- toc.integrate
75+
- content.code.annotate
76+
palette:
77+
- media: "(prefers-color-scheme: light)"
78+
scheme: datajoint
79+
toggle:
80+
icon: material/brightness-7
81+
name: Switch to dark mode
82+
- media: "(prefers-color-scheme: dark)"
83+
scheme: slate
84+
toggle:
85+
icon: material/brightness-4
86+
name: Switch to light mode
87+
plugins:
88+
- markdownextradata: {}
89+
- search
90+
# - redirects: # OPTIONAL REDIRECTS
91+
# redirect_maps:
92+
# "index.md": "getting_started.md"
93+
- mkdocstrings:
94+
default_handler: python
95+
- gen-files:
96+
scripts:
97+
- ./src/api/make_pages.py
98+
- literate-nav:
99+
nav_file: navigation.md
100+
- exclude-search:
101+
exclude:
102+
- "*/navigation.md"
103+
markdown_extensions:
104+
- attr_list
105+
- toc:
106+
permalink: true
107+
- pymdownx.emoji:
108+
options:
109+
custom_icons:
110+
- .overrides/.icons
111+
- mdx_truly_sane_lists
112+
- pymdownx.superfences:
113+
custom_fences:
114+
- name: mermaid
115+
class: mermaid
116+
format: !!python/name:pymdownx.superfences.fence_code_format
117+
- pymdownx.tabbed:
118+
alternate_style: true
119+
- pymdownx.highlight:
120+
linenums: true
121+
- pymdownx.inlinehilite
122+
- pymdownx.snippets
123+
124+
extra:
125+
PATCH_VERSION: !ENV PATCH_VERSION
126+
generator: false # Disable watermark
127+
analytics:
128+
provider: google
129+
property: !ENV GOOGLE_ANALYTICS_KEY
130+
feedback:
131+
title: Was this page helpful?
132+
ratings:
133+
- icon: material/emoticon-happy-outline
134+
name: This page was helpful
135+
data: 1
136+
note: >-
137+
Thanks for your feedback!
138+
- icon: material/emoticon-sad-outline
139+
name: This page could be improved
140+
data: 0
141+
note: >-
142+
Thanks for your feedback!
143+
version:
144+
provider: mike
145+
social:
146+
- icon: main/company-logo
147+
link: https://www.datajoint.com/
148+
- icon: fontawesome/solid/ticket
149+
link: https://support.djneuro.io/portal/en/home
150+
- icon: fontawesome/brands/slack
151+
link: https://datajoint.slack.com
152+
- icon: fontawesome/brands/linkedin
153+
link: https://www.linkedin.com/company/datajoint
154+
- icon: fontawesome/brands/twitter
155+
link: https://twitter.com/DataJointIO
156+
- icon: fontawesome/brands/github
157+
link: https://github.com/datajoint
158+
- icon: fontawesome/brands/docker
159+
link: https://hub.docker.com/u/datajoint
160+
- icon: fontawesome/brands/python
161+
link: https://pypi.org/user/datajointbot
162+
- icon: fontawesome/brands/stack-overflow
163+
link: https://stackoverflow.com/questions/tagged/datajoint
164+
- icon: fontawesome/brands/youtube
165+
link: https://www.youtube.com/channel/UCdeCuFOTCXlVMRzh6Wk-lGg
166+
extra_css:
167+
- assets/stylesheets/extra.css
168+
169+
extra_javascript:
170+
- https://js-na1.hs-scripts.com/23133402.js # HubSpot chatbot

‎docs/src/.overrides/.icons/main/company-logo.svg‎

Lines changed: 21 additions & 0 deletions
Loading

‎docs/src/.overrides/.icons/main/project-logo-black.svg‎

Lines changed: 22 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)