chore/issue1/update-metadata #30
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,79 @@ | ||
| name: Publish to PyPI | ||
|
|
||
| permissions: | ||
| id-token: write # Required for trusted publishing | ||
| contents: read # Required to checkout code | ||
| actions: write # Required to cancel runs | ||
|
|
||
| on: | ||
| workflow_run: | ||
| workflows: [Python Tests] | ||
| types: | ||
| - completed | ||
| branches: | ||
| - main | ||
|
|
||
| jobs: | ||
| pypi-release: | ||
| name: PyPI Release | ||
| runs-on: ubuntu-latest | ||
| if: ${{ github.event.workflow_run.conclusion == 'success' }} | ||
| environment: | ||
| name: pypi | ||
| url: https://pypi.org/project/graphomotor/ | ||
|
|
||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| with: | ||
| fetch-depth: 2 # Need 2 commits to compare for version changes | ||
|
|
||
| - uses: actions/setup-python@v5 | ||
| with: | ||
| python-version-file: pyproject.toml | ||
|
|
||
| - name: Install uv | ||
| uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba # v6.3.1 | ||
| with: | ||
| enable-cache: true | ||
|
|
||
| - name: Check if version changed | ||
| id: version-check | ||
| run: | | ||
| if git diff HEAD^1 HEAD --name-only | grep -q "pyproject.toml"; then | ||
| version_change=$(git diff HEAD^1 HEAD pyproject.toml | grep -E "^(\+|-)version =") | ||
| if [[ -n "$version_change" ]]; then | ||
| echo "version_changed=true" >> $GITHUB_OUTPUT | ||
| echo "Version changed detected:" | ||
| echo "$version_change" | ||
| else | ||
| echo "version_changed=false" >> $GITHUB_OUTPUT | ||
| echo "pyproject.toml changed but version did not change" | ||
| fi | ||
| else | ||
| echo "version_changed=false" >> $GITHUB_OUTPUT | ||
| echo "pyproject.toml did not change" | ||
| fi | ||
|
|
||
| - name: Skip release if version unchanged | ||
| if: steps.version-check.outputs.version_changed == 'false' | ||
| run: | | ||
| echo "No version change detected, skipping release" | ||
| gh run cancel ${{ github.run_id }} | ||
| env: | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
|
|
||
| - name: Build package | ||
| if: steps.version-check.outputs.version_changed == 'true' | ||
| run: uv build | ||
|
|
||
| - name: Verify build artifacts | ||
| if: steps.version-check.outputs.version_changed == 'true' | ||
| run: | | ||
| ls -la dist/ | ||
| python -c "import tarfile; tarfile.open('dist/*.tar.gz').getnames()" || true | ||
|
|
||
| - name: Publish to PyPI | ||
|
Collaborator
There was a problem hiding this comment. will this job work without the PYPI token?
Collaborator
Author
There was a problem hiding this comment. apparently it is more secure without the tokens using this OpenID Connect method. we'll see if it works lol |
||
| if: steps.version-check.outputs.version_changed == 'true' | ||
| uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4 | ||
| # Alternative: use uv publish with trusted publishing | ||
| # run: uv publish --token ${{ secrets.PYPI_API_TOKEN }} | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,9 @@ | ||
| # data | ||
| data/ | ||
|
|
||
| # scripts | ||
| scripts/ | ||
|
|
||
| # experiments | ||
| experiments/ | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,32 +1,132 @@ | ||
| # Graphomotor Study Toolkit | ||
|
|
||
| A Python toolkit for analysis of graphomotor data collected via Curious. | ||
|
|
||
| [](https://doi.org/10.5281/zenodo.15800191) | ||
|
|
||
| [](https://github.com/childmindresearch/graphomotor/actions/workflows/test.yaml?query=branch%3Amain) | ||
| [](https://codecov.io/gh/childmindresearch/graphomotor) | ||
| [](https://github.com/astral-sh/ruff) | ||
|  | ||
| [](https://github.com/childmindresearch/graphomotor/blob/main/LICENSE) | ||
| [](https://childmindresearch.github.io/graphomotor) | ||
|
|
||
| Welcome to `graphomotor`, a specialized Python library for analyzing graphomotor data collected via [Curious](https://www.gettingcurious.com/). This toolkit provides comprehensive tools for processing, analyzing, and visualizing data from various graphomotor assessment tasks including spiral drawing, trails making, alphabetic writing, digit symbol substitution, and the Rey-Osterrieth Complex Figure Test. | ||
|
alperkent marked this conversation as resolved.
|
||
|
|
||
| ## Development Progress | ||
|
|
||
| ⚠️ **This package is under active development.** Currently, the focus is on the Spiral task. After finalizing feature extraction, the next steps will involve implementing both preprocessing and visualization for this task. Once these parts are in place, we plan to extend support to other tasks. | ||
|
|
||
| | Task | Preprocessing | Feature Extraction | Visualization | | ||
| | :--- | :---: | :---: | :---: | | ||
| | Spiral |  |  |  | | ||
| | Rey-Osterrieth Complex Figure |  |  |  | | ||
| | Alphabetic Writing |  |  |  | | ||
| | Digit Symbol Substitution |  |  |  | | ||
| | Trails Making |  |  |  | | ||
|
|
||
| ## Data Format Requirements | ||
|
|
||
| ⚠️ **This implementation requires data to adhere to a specific format matching the standard output from [Curious drawing responses](https://mindlogger.atlassian.net/servicedesk/customer/portal/3/article/859242501).** | ||
|
|
||
| When exporting drawing data from Curious, you typically receive the following files: | ||
|
|
||
| - **report.csv**: Contains the participants' actual responses. | ||
| - **activity_user_journey.csv**: Logs the entire journey through the activity, including button actions like "Next", "Skip", "Back", and "Undo", regardless of whether a response was provided. | ||
| - **drawing-responses-{date}.zip**: A ZIP archive with raw drawing response CSV files for each participant (e.g., `drawing-responses-Mon May 29 2023.zip`). | ||
| - **media-responses-{date}.zip**: A ZIP archive containing SVG files for the drawing responses (e.g., `media-responses-Mon May 29 2023.zip`). | ||
| - **trails-responses-{date}.zip**: A ZIP archive with raw trail making response CSV files (if there are any) for each participant (e.g., `trails-responses-Mon May 29 2023.zip`). | ||
|
|
||
| For Spiral tasks, the toolkit uses only the CSV files from the drawing responses ZIP. Support for additional tasks will be added in future releases. | ||
|
|
||
| ### File Naming Convention | ||
|
|
||
| Your spiral data files must follow this naming convention: | ||
|
|
||
| ```text | ||
| [5123456]a7f3b2e9-d4c8-f1a6-e5b9-c2d7f8a3e6b4-spiral_trace1_Dom.csv | ||
| ``` | ||
|
|
||
| Where: | ||
|
|
||
| - **Participant ID**: Must be enclosed in brackets `[]` and be a 7-digit number starting with `5` (e.g., `[5123456]`) that matches the `target_secret_id` column in the **report.csv** file. | ||
| - **Activity Submission ID**: Must be a 32-character hexadecimal string (e.g., `18f2-45ea-a1e4-2334e07cc706`) that matches the `id` column in the **report.csv** file. | ||
| - **Task**: Must be one of the following that matches the `item` column in the **report.csv** file: | ||
| - `spiral_trace1_Dom` through `spiral_trace5_Dom` (dominant hand tracing tasks) | ||
| - `spiral_trace1_NonDom` through `spiral_trace5_NonDom` (non-dominant hand tracing tasks) | ||
| - `spiral_recall1_Dom` through `spiral_recall3_Dom` (dominant hand recall tasks) | ||
| - `spiral_recall1_NonDom` through `spiral_recall3_NonDom` (non-dominant hand recall tasks) | ||
|
|
||
| ### Data Format | ||
|
|
||
| Your spiral data CSV file must contain the following columns: | ||
|
|
||
| ```text | ||
| line_number, x, y, UTC_Timestamp, seconds, epoch_time_in_seconds_start | ||
| ``` | ||
|
|
||
| This format represents the standard output from [Curious drawing responses data dictionary](https://mindlogger.atlassian.net/servicedesk/customer/portal/3/article/596082739). | ||
|
|
||
| ## Feature Extraction Capabilities | ||
|
|
||
| The toolkit extracts clinically relevant metrics from digitized drawing data. Currently implemented features include: | ||
|
|
||
| - **Temporal Features**: Task completion duration. | ||
| - **Velocity Features**: Velocity analysis including linear, radial, and angular velocity components with statistical measures (sum, median, variation, skewness, kurtosis). | ||
| - **Distance Features**: Spatial accuracy measurements using Hausdorff distance metrics with temporal normalizations and segment-specific analysis. | ||
| - **Drawing Error Features**: Area under the curve (AUC) calculations between drawn paths and ideal reference trajectories to quantify spatial accuracy. | ||
|
|
||
| ## Installation | ||
|
|
||
| Install the graphomotor package from PyPI: | ||
|
|
||
| ```sh | ||
| pip install graphomotor | ||
|
alperkent marked this conversation as resolved.
|
||
| ``` | ||
|
|
||
| Or install the latest development version directly from GitHub: | ||
|
|
||
| ```sh | ||
| pip install git+https://github.com/childmindresearch/graphomotor | ||
| ``` | ||
|
|
||
| ## Quick Start | ||
|
|
||
| Currently, `graphomotor` is available as an importable Python library. CLI functionality is planned for future releases. | ||
|
|
||
| ### Extracting Features from Spiral Drawing Data | ||
|
|
||
| ```python | ||
| from graphomotor.core import orchestrator | ||
|
|
||
| # Path to your spiral drawing data file | ||
| input_file = "path/to/your/spiral_data.csv" | ||
|
alperkent marked this conversation as resolved.
|
||
|
|
||
| # Directory where extracted features will be saved | ||
| output_dir = "path/to/output/directory" | ||
|
|
||
| # Run the analysis pipeline | ||
| features = orchestrator.run_pipeline( | ||
| input_path=input_file, | ||
| output_path=output_dir | ||
| ) | ||
|
|
||
| # Features are returned as a dictionary and saved as CSV | ||
| print(f"Successfully extracted {len(features)} feature categories") | ||
| ``` | ||
|
|
||
| For detailed configuration options and additional parameters, refer to the [`run_pipeline` documentation](https://childmindresearch.github.io/graphomotor/graphomotor/core/orchestrator.html#run_pipeline). | ||
|
|
||
| > **Note:** Currently, only single file processing is supported, with batch processing planned for future releases. | ||
|
|
||
| ## Future Directions | ||
|
|
||
| The Graphomotor Study Toolkit is under active development. For more detailed information about upcoming features and development plans, please refer to our [GitHub Issues](https://github.com/childmindresearch/graphomotor/issues) page. | ||
|
|
||
| ## Contributing | ||
|
|
||
| We welcome contributions from the community! If you're interested in contributing, please review our [Contributing Guidelines](CONTRIBUTING.md) for information on how to get started, coding standards, and the pull request process. | ||
|
|
||
| ## References | ||
|
|
||
| 1. Messan, K. S., Kia, S. M., Narayan, V. A., Redmond, S. J., Kogan, A., Hussain, M. A., McKhann, G. M. II, & Vahdat, S. (2022). Assessment of Smartphone-Based Spiral Tracing in Multiple Sclerosis Reveals Intra-Individual Reproducibility as a Major Determinant of the Clinical Utility of the Digital Test. Frontiers in Medical Technology, 3, 714682. [https://doi.org/10.3389/fmedt.2021.714682](https://doi.org/10.3389/fmedt.2021.714682) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,22 +1,13 @@ | ||
| # Security | ||
|
|
||
| Child Mind Institute values the security of our users, data, and servers. We take the security of our systems seriously and encourage users to report any suspected security vulnerabilities promptly. | ||
|
|
||
| ## Supported Versions | ||
|
|
||
| Only the latest minor version will receive security updates. All older minor versions should be considered unmaintained. | ||
|
|
||
| ## Reporting Vulnerabilities | ||
|
|
||
| To report security vulnerabilities, please do NOT use our issues page. Instead, kindly email us at <mobi@childmind.org>. Please refrain from using other communication channels. | ||
|
|
||
| For non-security-related issues, we welcome your input and feedback on our issues page. Feel free to share your ideas and suggestions to help us improve our services. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
what's this job needed for?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
it's basically a sanity check that makes sure that the distribution artifacts exist and can be opened before attempting to upload them to PyPI. i wanted to try and see, if it adds too much overhead i'll remove it.