Pull from upstream

.devcontainer/Dockerfile

@@ -37,6 +37,10 @@ RUN \
     rm -rf /tmp/element-facemap && \
     apt-get clean
 
+# Install Facemap
+RUN git clone https://github.com/kushalbakshi/facemap.git
+RUN pip install ./facemap[gui]
+
 ENV DJ_HOST fakeservices.datajoint.io
 ENV DJ_USER root
 ENV DJ_PASS simple

.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://docs.datajoint.com/about/contribute/
     about: Please make sure to review the DataJoint Contribution Guidelines

.github/workflows/devcontainer-build-publish-caller.yml

@@ -0,0 +1,10 @@
+name: devcontainer_build_publish
+on:
+  workflow_dispatch:
+
+jobs:
+  call_devcontainer_build_publish:
+    uses: datajoint/.github/.github/workflows/devcontainer-build-publish.yaml@main
+    secrets:
+      DOCKERHUB_USERNAME: ${{secrets.DOCKERHUB_USERNAME}}
+      DOCKERHUB_TOKEN: ${{secrets.DOCKERHUB_TOKEN_FOR_ELEMENTS}}

.github/workflows/mkdocs-release-caller.yml

@@ -0,0 +1,9 @@
+name: mkdocs-release
+on:
+  workflow_dispatch:
+
+jobs:
+  mkdocs_release:
+    uses: datajoint/.github/.github/workflows/mkdocs_release.yaml@main
+    permissions: 
+      contents: write

.github/workflows/release.yaml

@@ -4,24 +4,24 @@ on:
 jobs:
   make_github_release:
     uses: datajoint/.github/.github/workflows/make_github_release.yaml@main
-  pypi_release:
-    needs: make_github_release
-    uses: datajoint/.github/.github/workflows/pypi_release.yaml@main
-    secrets:
-      TWINE_USERNAME: ${{secrets.TWINE_USERNAME}}
-      TWINE_PASSWORD: ${{secrets.TWINE_PASSWORD}}
-    with:
-      UPLOAD_URL: ${{needs.make_github_release.outputs.release_upload_url}}
+  # pypi_release:
+  #   needs: make_github_release
+  #   uses: datajoint/.github/.github/workflows/pypi_release.yaml@main
+  #   secrets:
+  #     TWINE_USERNAME: ${{secrets.TWINE_USERNAME}}
+  #     TWINE_PASSWORD: ${{secrets.TWINE_PASSWORD}}
+  #   with:
+  #     UPLOAD_URL: ${{needs.make_github_release.outputs.release_upload_url}}
   mkdocs_release:
     uses: datajoint/.github/.github/workflows/mkdocs_release.yaml@main
-    permissions: 
+    permissions:
       contents: write
   devcontainer-build:
     uses: datajoint/.github/.github/workflows/devcontainer-build.yaml@main
   devcontainer-publish:
-    needs: 
+    needs:
       - devcontainer-build
     uses: datajoint/.github/.github/workflows/devcontainer-publish.yaml@main
     secrets:
       DOCKERHUB_USERNAME: ${{secrets.DOCKERHUB_USERNAME}}
-      DOCKERHUB_TOKEN: ${{secrets.DOCKERHUB_TOKEN_FOR_ELEMENTS}}
+      DOCKERHUB_TOKEN: ${{secrets.DOCKERHUB_TOKEN_FOR_ELEMENTS}}

.github/workflows/semantic-release-caller.yml

@@ -0,0 +1,10 @@
+name: semantic-release
+on:
+  workflow_dispatch:
+
+jobs:
+  call_semantic_release:
+    uses: datajoint/.github/.github/workflows/semantic-release.yaml@main
+    secrets:
+      APP_ID: ${{ secrets.ELEMENT_APP_ID }}
+      GET_TOKEN_KEY: ${{ secrets.ELEMENT_GET_TOKEN_KEY }}

.github/workflows/test.yaml

@@ -1,24 +1,19 @@
 name: Test
 on:
   push:
+    branches:
+      - main
   pull_request:
+    branches:
+      - main
   workflow_dispatch:
-  schedule:
-    - cron: "0 8 * * 1"
 jobs:
-  devcontainer-build:
-    uses: datajoint/.github/.github/workflows/devcontainer-build.yaml@main
   tests:
     runs-on: ubuntu-latest
     strategy:
       matrix:
         py_ver: ["3.9", "3.10"]
-        mysql_ver: ["8.0", "5.7"]
-        include:
-          - py_ver: "3.8"
-            mysql_ver: "5.7"
-          - py_ver: "3.7"
-            mysql_ver: "5.7"
+        mysql_ver: ["8.0"]
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python ${{matrix.py_ver}}

CHANGELOG.md

@@ -3,12 +3,26 @@
 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.3.0] - 2024-08-20
+
++ Update - Attribute names in `FacialSignal` table
++ Update - FacemapSVD handles all ROIs and FullSVD analysis
+
+## [0.2.2] - 2024-05-12
+
++ Fix - Fix docs by updating `mkdocs`
++ Update - Remove the `pypi_release` from `release.yaml`
+
+## [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`
 + Add - DevContainer for codespaces
 + Add - `tutorial_pipeline.py`
-+ Add - 60 min tutorial using Jupyter Notebooks
++ Add - 60 min tutorial for `facemap_inference` using Jupyter Notebooks
 + Update - General improvements to increase consistency with other DataJoint Elements
 
 ## [0.1.7] - 2023-10-18

CONTRIBUTING.md

@@ -1,5 +1,5 @@
 # Contribution Guidelines
 
 This project follows the
-[DataJoint Contribution Guidelines](https://datajoint.com/docs/about/contribute/).
+[DataJoint Contribution Guidelines](https://docs.datajoint.com/about/contribute/).
 Please reference the link for more full details.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 DataJoint
+Copyright (c) 2024 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

README.md

@@ -1,13 +1,76 @@
-# DataJoint Element - Facemap
+# DataJoint Element for orofacial motion tracking with Facemap
 
-DataJoint Element for tracking facial movements of a mouse with
-[Facemap](https://github.com/MouseLand/facemap). 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.
+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. 
 
-Installation and usage instructions can be found at the
-[Element documentation](https://datajoint.com/docs/elements/element-facemap).
+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.
 
-![diagram](https://raw.githubusercontent.com/datajoint/element-facemap/main/images/diagram_flowchart.svg)
+## Experiment Flowchart
+
+![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/pipeline_facemap_inference.svg)
+
++ 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://docs.datajoint.com/elements/element-facemap/latest/pipeline/)
+
+## Getting Started
+
++ Please fork this repository.
+
++ Clone the repository to your computer
+
+    ```bash
+    git clone https://github.com/<enter_github_username>/element-facemap.git
+    ```
+
++ Install with `pip`
+
+    ```bash
+    pip install -e .
+    ```
+
++ [Interactive tutorial on GitHub Codespaces](https://github.com/datajoint/element-facemap#interactive-tutorial)
+
++ [Documentation](https://docs.datajoint.com/elements/element-facemap/)
+
+## Support
+
++ If you need help getting started or run into any errors, please open a GitHub Issue or contact our team by email at support@datajoint.com.
+
+## Interactive Tutorial
+
++ The easiest way to learn about DataJoint Elements is to use the tutorial notebooks within the included interactive environment configured using [Dev Container](https://containers.dev/).
+
+### Launch Environment
+
+Here are some options that provide a great experience:
+
++ (*recommended*) Cloud-based Environment
+  + Launch using [GitHub Codespaces](https://github.com/features/codespaces) using the `+` option which will `Create codespace on main` in the codebase repository on your fork with default options. For more control, see the `...` where you may create `New with options...`.
+  + Build time for a codespace is a few minutes. This is done infrequently and cached for convenience.
+  + Start time for a codespace is less than 1 minute. This will pull the built codespace from cache when you need it.
+  + *Tip*: Each month, GitHub renews a [free-tier](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#monthly-included-storage-and-core-hours-for-personal-accounts) quota of compute and storage. Typically we run into the storage limits before anything else since Codespaces consume storage while stopped. It is best to delete Codespaces when not actively in use and recreate when needed. We'll soon be creating prebuilds to avoid larger build times. Once any portion of your quota is reached, you will need to wait for it to be reset at the end of your cycle or add billing info to your GitHub account to handle overages.
+  + *Tip*: GitHub auto names the codespace but you can rename the codespace so that it is easier to identify later.
+
++ Local Environment
+  > *Note: Access to example data is currently limited to MacOS and Linux due to the s3fs utility. Windows users are recommended to use the above environment.*
+  + Install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+  + Install [Docker](https://docs.docker.com/get-docker/)
+  + Install [VSCode](https://code.visualstudio.com/)
+  + Install the VSCode [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+  + `git clone` the codebase repository and open it in VSCode
+  + Use the `Dev Containers extension` to `Reopen in Container` (More info is in the `Getting started` included with the extension.)
+
+You will know your environment has finished loading once you either see a terminal open related to `Running postStartCommand` with a final message of `Done` or the `README.md` is opened in `Preview`.
+
+Once the environment has launched, please run the following command in the terminal:
+```
+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 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.

docs/docker-compose.yaml

@@ -1,6 +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
-#
-# navigate to http://localhost/
+# 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:
@@ -14,6 +12,8 @@ services:
       - PACKAGE
       - UPSTREAM_REPO
       - MODE
+      - PATCH_VERSION
+      - JUPYTER_PLATFORM_DIRS=1
     volumes:
       - ../docs:/main/docs
       - ../${PACKAGE}:/main/${PACKAGE}
@@ -28,6 +28,12 @@ services:
         set -e
         export ELEMENT_NAME=$$(echo $${PACKAGE} | sed 's/element_//g')
         export PATCH_VERSION=$$(cat /main/$${PACKAGE}/version.py | grep -oE '\d+\.\d+\.[a-z0-9]+')
+        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
@@ -47,4 +53,4 @@ services:
         else
             echo "Unexpected mode..."
             exit 1
-        fi
+        fi

docs/mkdocs.yaml

@@ -1,13 +1,18 @@
 # ---------------------- PROJECT SPECIFIC ---------------------------
 
 site_name: DataJoint Documentation
-site_url: http://localhost/docs/element/element-facemap
+site_url: https://docs.datajoint.com/elements/element-facemap/
 repo_url: https://github.com/datajoint/element-facemap
 repo_name: datajoint/element-facemap
 nav:
   - Element Facemap: index.md
+  - Data Pipeline: pipeline.md
+  - Tutorials:
+      - tutorials/index.md
+      - Tutorial Notebook: tutorials/inference_tutorial.ipynb
   - Concepts: concepts.md
-  - Tutorials: tutorials.md
+  - Key Partnerships: partnerships.md
+  - Roadmap: roadmap.md
   - Citation: citation.md
   - API: api/ # defer to gen-files + literate-nav
   - Changelog: changelog.md
@@ -23,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
@@ -43,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*.*.*
 #
@@ -88,13 +93,14 @@ plugins:
       default_handler: python
       handlers:
         python:
+          paths: [../]
           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:
@@ -130,9 +136,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
@@ -168,7 +174,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/.overrides/partials/nav.html

@@ -14,7 +14,7 @@
         {#-
         Add DataJoint home link to navigation header, otherwise unchanged
         -#}
-        <a href="https://datajoint.com/docs/elements/" title="DataJoint Elements">
+        <a href="https://docs.datajoint.com/elements/" title="DataJoint Elements">
             ⬅ Home
         </a>
     </label>

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(