Location: Jupyter notebooks for teaching users how to use the DICOM classification package (specific notebook files and their locations in the repository).
Type of Documentation Issue
Enhancement
Issue Description
The Jupyter notebooks used to demonstrate how to run the DICOM classifier are outdated. This includes:
Use of older versions of the DICOM classification package, which may not be compatible with the latest updates.
A key issue where the current version of the package requires git lfs data, but running the notebooks in environments like Google Colab fails because git lfs does not know where the repository is located.
Suggested Changes
Update Notebooks:
Update the Jupyter notebooks to use the latest version of the package.
Ensure that all code examples reflect the latest API and functionality of the DICOM classifier package.
Handle git lfs in Google Colab:
Provide clear instructions or a link for users to download the necessary git lfs data directly, especially for environments like Google Colab where running git lfs fetch without specifying a repo causes issues.
Include a step-by-step guide for fetching the data using a direct link to the repository or a cloud-hosted version of the LFS data.
Alternatively, consider packaging smaller datasets directly in the notebook to avoid git lfs complications for basic examples.
Additional Context
This is critical for users running the notebooks in cloud-based environments like Google Colab, which do not always support git lfs as easily as local machines.
Ensuring that users can run the classification package smoothly without manually troubleshooting git lfs will improve the overall user experience and reduce confusion.
Proposed Solution
Update the package version in the notebooks to match the latest release.
Add documentation and code blocks that either:
Point users to a cloud-based version of the data needed (e.g., a link to download preprocessed data without using git lfs).
Upload a tar file with the needed data for running the notebook using GitHub actions along with a new GitHub release on PRs to main
Provide commands and example code to configure git lfs correctly in environments like Google Colab (e.g., by adding a direct repository URL for git lfs to fetch from).
Additional Comments
Consider running integration tests for the updated notebooks in cloud environments like Google Colab to ensure they work out-of-the-box.
It might also help to include a “Troubleshooting” section that addresses common issues like git lfs errors and how to resolve them in various environments (e.g., local, Colab, etc.).
Documentation Location
Type of Documentation Issue
Issue Description
git lfsdata, but running the notebooks in environments like Google Colab fails becausegit lfsdoes not know where the repository is located.Suggested Changes
Update Notebooks:
Handle
git lfsin Google Colab:git lfsdata directly, especially for environments like Google Colab where runninggit lfs fetchwithout specifying a repo causes issues.git lfscomplications for basic examples.Additional Context
git lfsas easily as local machines.git lfswill improve the overall user experience and reduce confusion.Proposed Solution
git lfs).git lfscorrectly in environments like Google Colab (e.g., by adding a direct repository URL forgit lfsto fetch from).Additional Comments
git lfserrors and how to resolve them in various environments (e.g., local, Colab, etc.).