SPRAS tutorial 2025-10-13 notes

[agitter]

Takeaways from the demo of the SPRAS tutorial

• Link to readthedocs at the top of the readme as a badge to make it easier to find
• Docker may not launch on macOS unless you restart your computer, may it may be running in the background. We may want to provide a way to check from the command line if docker is running in the background even if Docker Desktop will not launch. This was an error for one participant who thought Docker was running and then hit an error at the first SPRAS test because it was not.
• Do we need to show the audience how to clone a GitHub repository? May not want to assume everyone can do this.
• Confusion about why Docker is followed by conda. Need to explain the interaction between these pieces.
• People may want to know about how many Docker images we are pulling, how much disk space is needed to run this tutorial.
• There are one time setup steps (create env, pip install) and also every time steps (activate environment)
• Show the steps in a terminal (conda activate, python -c...)
• Have to move the yaml config file to the correct location in the spras repo
• Should we leave the tutorial files in the spras repos so there aren't any separate downloads?
• Explain basics a yaml file as a markup language stored in plain text, don't assume too much of the audience
• In general we want to be actively explaining things the entire time
• How do we know when people are ready to proceed? Red/green sign?
• Okay to explain some of the next step (what the config file contains) while participants are completing the former step (moving the beginner config file).
• Questions about the config file options and where they are documented, for example, parameters in the post-processing. config.yaml is the best source of information so far.
• Make sure the output from beginner.yaml is not already present when showing the first command.
• What happens when you run snakemake? Can you run more with than one cores? It analyzes the work to be done and what parts can be parallelized.
• Show the output files after the first run?
• Are we cleaning up Docker caches from containers that SPRAS uses? We have a finite but order 10 number of images. Gets back to warnings about how much storage is used and how to clean up after the tutorial. We are left with containers after each SPRS run (docker ps -a).
• Should we provide a bash command to display the directory structure? Can get it a combination of ls, grep, sed.
• Had some auto-indent problems with run2 parameters in yaml file. May be due to the linter.
• macOS user ran into a Docker problem related to https://stackoverflow.com/questions/67642620/docker-credential-desktop-not-installed-or-not-available-in-path. That fix made a credential store error go away.
• Then hit a Docker file permission error. Had to give permissions on Docker desktop to share certain paths. APIErrror was displayed in SPRAS run. Solution is to take the file path and go in Docker Desktop -> Resources -> File sharing, list the path in "Virtual file shares".
• May need a Docker troubleshooting section for the tutorial.

[tristan-f-r]

For the following bullet points:

Do we need to show the audience how to clone a GitHub repository? May not want to assume everyone can do this.
Confusion about why Docker is followed by conda. Need to explain the interaction between these pieces.
There are one time setup steps (create env, pip install) and also every time steps (activate environment)
Have to move the yaml config file to the correct location in the spras repo
Should we leave the tutorial files in the spras repos so there aren't any separate downloads?

If there is time before the COMBINE25 tutorial, we can take away all of the conda/file confusion by providing a ZIP file of the datasets the tutorial needs, and releasing SPRAS on pip (via #332) instead of forcing users to clone the SPRAS repository, which gets rid of the need to use conda for SPRAS users.

[ntalluri]

We don't have time, the tutorial is being presented on October 22nd.

[agitter]

Yes, I agree that the cli would simplify a lot of setup. However, there is a lot that can go into the cli and therefore some big picture questions I have that I haven't asked yet because I haven't reviewed it fully yet.