Merge pull request #35 from MilagrosMarin/main

update: fix links in README and udpate `docs`

Author: dimitri-yatsenko

CHANGELOG.md

@@ -3,6 +3,10 @@
 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.2.1] - 2024-05-12
++ Fix - Links in README
++ Update - README and docs
+
 ## [0.2.0] - 2023-11-29
 
 + Add - Inference module as `facemap_inference.py`

README.md

@@ -1,20 +1,23 @@
-# DataJoint Element - Facemap
+# DataJoint Element for orofacial motion tracking with Facemap
 
-DataJoint Element for modeling neural activity based on orofacial tracking using [Facemap](https://github.com/MouseLand/facemap). This Element supports facemap analysis using distinct keypoints on the mouse face, and computing the singular value decomposition and pupil tracking. 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. This repository also provides a tutorial environment and notebooks to learn the pipeline.
+DataJoint Element for modeling neural activity based on orofacial tracking using [Facemap](https://github.com/MouseLand/facemap). This Element supports facemap analysis using distinct keypoints on the mouse face, and computing the singular value decomposition and pupil tracking. 
+
+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. This repository also provides a tutorial environment and notebooks to learn the pipeline.
 
 ## Experiment Flowchart
 
-![flowchart](https://raw.githubusercontent.com/datajoint/element-facemap/main/images/diagram_flowchart.svg)
+![flowchart](https://raw.githubusercontent.com/datajoint/element-facemap/main/images/flowchart.svg)
 
 ## Data Pipeline Diagram
 
-![pipeline](https://raw.githubusercontent.com/datajoint/element-facemap/main/images/pipline_facemap_inference.svg)
+![pipeline](https://raw.githubusercontent.com/datajoint/element-facemap/main/images/pipeline_facemap_inference.svg)
 
-+ We have designed two variations of the pipline for different use cases. Displayed above is the pipeline for the `facemap_inference` schema. Details on the pipeline for `facial_behavior_estimation` can be found in the [Data Pipeline](https://datajoint.com/docs/elements/element-facemap/latest/pipeline/)
++ We have designed two variations of the pipeline for different use cases. Displayed above is the pipeline for the `facemap_inference` schema. Details on the pipeline for `facial_behavior_estimation` can be found in the [Data Pipeline](https://datajoint.com/docs/elements/element-facemap/latest/pipeline/)
 
 ## Getting Started
 
 + Please fork this repository.
+
 + Clone the repository to your computer
 
     ```bash
@@ -27,7 +30,8 @@ DataJoint Element for modeling neural activity based on orofacial tracking using
     pip install -e .
     ```
 
-+ [Interactive tutorial on GitHub Codespaces](#interactive-tutorial)
++ [Interactive tutorial on GitHub Codespaces](https://github.com/datajoint/element-facemap#interactive-tutorial)
+
 + [Documentation](https://datajoint.com/docs/elements/element-facemap)
 
 ## Support
@@ -67,6 +71,6 @@ MYSQL_VER=8.0 docker compose -f docker-compose-db.yaml up --build -d
 
 ### Instructions
 
-1. We recommend you start by navigating to the `notebooks` directory on the left panel and go through the `tutorial.ipynb` Jupyter notebook. Execute the cells in the notebook to begin your walk through of the tutorial.
+1. We recommend you start by navigating to the `notebooks` directory on the left panel and go through the `tutorial.ipynb` Jupyter notebook. Execute the cells in the notebook to begin your walkthrough of the tutorial.
 
-2. Once you are done, see the options available to you in the menu in the bottom-left corner. For example, in Codespace you will have an option to `Stop Current Codespace` but when running Dev Container on your own machine the equivalent option is `Reopen folder locally`. By default, GitHub will also automatically stop the Codespace after 30 minutes of inactivity.  Once the Codespace is no longer being used, we recommend deleting the Codespace.
+2. Once you are done, see the options available to you in the menu in the bottom-left corner. For example, in Codespace you will have an option to `Stop Current Codespace` but when running Dev Container on your own machine the equivalent option is `Reopen folder locally`. By default, GitHub will also automatically stop the Codespace after 30 minutes of inactivity.  Once the Codespace is no longer being used, we recommend deleting the Codespace.

docs/docker-compose.yaml

@@ -1,4 +1,4 @@
-# MODE="LIVE|QA|BUILD" PACKAGE=element_facemap UPSTREAM_REPO=https://github.com/datajoint/element-facemap.git HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
+# MODE="LIVE|QA|PUSH" PACKAGE=element_facemap UPSTREAM_REPO=https://github.com/datajoint/element-facemap.git HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
 version: "2.4"
 services:
   docs:
@@ -13,10 +13,10 @@ services:
       - UPSTREAM_REPO
       - MODE
       - PATCH_VERSION
+      - JUPYTER_PLATFORM_DIRS=1
     volumes:
       - ../docs:/main/docs
       - ../${PACKAGE}:/main/${PACKAGE}
-      - ../notebooks:/main/notebooks
     user: ${HOST_UID}:anaconda
     ports:
       - 80:80
@@ -26,12 +26,14 @@ services:
       - |
         git config --global --add safe.directory /main
         set -e
-        export ELEMENT_UNDERSCORE=$$(echo $${PACKAGE} | sed 's/element_//g')
-        export ELEMENT_HYPHEN=$$(echo $${ELEMENT_UNDERSCORE} | sed 's/_/-/g')        
+        export ELEMENT_NAME=$$(echo $${PACKAGE} | sed 's/element_//g')
         export PATCH_VERSION=$$(cat /main/$${PACKAGE}/version.py | grep -oE '\d+\.\d+\.[a-z0-9]+')
-        
-        cp /main/notebooks/inference_tutorial.ipynb /main/docs/src/tutorials/
-        
+        git clone https://github.com/datajoint/workflow-$${ELEMENT_NAME}.git /main/delete || true
+        if [ -d /main/delete/ ]; then
+          mv /main/delete/workflow_$${ELEMENT_NAME} /main/
+          mv /main/delete/notebooks/*ipynb /main/docs/src/tutorials/
+          rm -fR /main/delete
+        fi
         if echo "$${MODE}" | grep -i live &>/dev/null; then
             mkdocs serve --config-file ./docs/mkdocs.yaml -a 0.0.0.0:80
         elif echo "$${MODE}" | grep -iE "qa|push" &>/dev/null; then
@@ -51,4 +53,4 @@ services:
         else
             echo "Unexpected mode..."
             exit 1
-        fi
+        fi

docs/mkdocs.yaml

@@ -28,7 +28,7 @@ nav:
 # 02. Instead of designating codeblocks with bash, use console. For example..
 #     ```console
 #     cd ../my_dir
-#     ``` 
+#     ```
 # 03. Links across docs should ...
 #     A. Not involve line breaks.
 #     B. Use relative paths to docs in the same repo
@@ -48,15 +48,15 @@ nav:
 #     HOST_UID=$(id -u) docker compose -f docs/docker-compose.yaml up --build
 #     ```
 # 02. The API section will pull docstrings.
-#     A. Follow google styleguide e.g., 
+#     A. Follow google styleguide 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
 # 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.
-# 04. 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 
+#     B. go to the your fork > settings > pages
 #     C. direct pages to render from the gh-pages branch at root
 #     D. push a tag to your fork with the format test*.*.*
 #
@@ -94,12 +94,12 @@ plugins:
       handlers:
         python:
           options:
-            members_order: source      
+            members_order: source
             group_by_category: false
             line_length: 88
   - gen-files:
       scripts:
-      - ./src/api/make_pages.py
+        - ./src/api/make_pages.py
   - literate-nav:
       nav_file: navigation.md
   - exclude-search:
@@ -135,9 +135,9 @@ markdown_extensions:
       generic: true
   - pymdownx.magiclink # Displays bare URLs as links
   - pymdownx.tasklist: # Renders check boxes in tasks lists
-      custom_checkbox: true  
+      custom_checkbox: true
 extra:
-  PATCH_VERSION: !ENV PATCH_VERSION 
+  PATCH_VERSION: !ENV PATCH_VERSION
   generator: false # Disable watermark
   version:
     provider: mike
@@ -173,7 +173,7 @@ extra_css:
   - assets/stylesheets/extra.css
 
 extra_javascript:
-  - https://js-na1.hs-scripts.com/23133402.js  # HubSpot chatbot
+  - https://js-na1.hs-scripts.com/23133402.js # HubSpot chatbot
   - javascripts/mathjax.js
   - https://polyfill.io/v3/polyfill.min.js?features=es6
   - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

docs/src/api/make_pages.py

@@ -13,10 +13,8 @@
 element = package.split("_", 1)[1]
 
 nav = mkdocs_gen_files.Nav()
-for path in sorted(Path(package).glob("**/*.py")) + sorted(
-    Path(f"workflow_{element}").glob("**/*.py")
-):
-    if path.stem == "__init__":
+for path in sorted(Path(package).glob("**/*.py")):
+    if path.stem == "__init__" or path.stem == "version":
         continue
     with mkdocs_gen_files.open(f"api/{path.with_suffix('')}.md", "w") as f:
         module_path = ".".join(

docs/src/concepts.md

@@ -9,6 +9,7 @@ In its initial versions, Facemap empowered researchers to identify regions of in
 The latest iteration of Facemap introduces the ability to track keypoints across the animal's face. This feature marks a departure from solely relying on predefined ROIs, allowing for more dynamic and precise analysis of facial expressions and movements.[^3]
 
 + **KeyPoints Detection**: Facemap now employs cutting-edge machine learning algorithms to automatically detect and track specific facial landmarks, such as the tips of whiskers, the corners of the eyes, and the edges of the mouth. This approach enables a finer-grained analysis of facial expressions, enhancing the software's utility in behavioral neuroscience research.
+
 + **Dynamic Tracking**: Unlike the static ROIs, keypoints move with the subject across frames. This dynamic tracking ensures that more subtle facial movements are captured, providing richer datasets for analysis.
 
 [^1]: Dolensek, N., Gehrlach, D. A., Klein, A. S., & Gogolla, N. (2020). Facial
@@ -29,5 +30,4 @@ Major features include:
 - Ingestion and storage of input video metadata.
 - Queueing and triggering of Facemap analysis on multiple sessions.
 - Ingestion of analysis outcomes as motion and video principle components.
-- Ingestion of analysis outcomes from inference of facial keypoints.
-
+- Ingestion of analysis outcomes from inference of facial keypoints.

docs/src/index.md

@@ -18,15 +18,15 @@ DataJoint Element for modeling neural activity based on orofacial tracking using
 
 + Clone the repository to your computer
 
-  ```bash
-  git clone https://github.com/<enter_github_username>/element-facemap
-  ```
+    ```bash
+    git clone https://github.com/<enter_github_username>/element-facemap.git
+    ```
 
 + Install with `pip`
-
-  ```bash
-  pip install -e .
-  ```
+    
+    ```bash
+    pip install -e .
+    ```
 
 + [Data Pipeline](./pipeline.md) - Pipeline and table descriptions
 

docs/src/partnerships.md

@@ -4,4 +4,4 @@ Element Facemap was developed in collaboration with Hui Chen Lu's Lab at Indiana
 University Bloomington. 
 
 Our team also works with the [Facemap developers](https://github.com/MouseLand/facemap) to promote
-integration and interoperability between Facemap and the DataJoint Element Facemap.
+integration and interoperability between Facemap and the DataJoint Element Facemap.

element_facemap/version.py

@@ -1,3 +1,3 @@
 """Package metadata."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"