Computational environment check

Many of the tools, including this protocols website, depend on Python. Contributing to analysis code and to protocols also requires that your git install is working as expected.

There is a repository at https://github.com/GallowayLabMIT/environment-check that contains a Python script that checks for installation problems by checking that simple commands can succeed.

This page does not give specific, copy-and-pastable instructions, as these will slightly differ. See Day 0: Software and training setup for instructions on installing both Python and Git, and An introduction to Git for git help.

Initial environment check

Note

This section of the setup is meant to be a minimal test of basic functionality. It mimics some of the steps you may want to do when working with a computational repository. See the Startup checklist when working with repositories for common “startup tasks” that normally need to be done when starting a new repository / downloading someone else’s.

When working with the protocol repository, you will have to repeat the virtual environment step, for example!

If you run into errors, ask someone who has their environment fully setup! All of the following steps should be done inside a local copy of the environment-check repository.

  1. Clone the environment-check repository at https://github.com/GallowayLabMIT/environment-check. You can put this repository wherever you like. This is intentionally a private repository, which means that you will have to be in the GallowayLabMIT Github organization and have your local Github credentials working.

Note

A common pattern is to put all of your git repositories in a repo folder in your home directory. Importantly, don’t put git repositories inside OneDrive or another cloud-synced folder; in addition to duplicated effort , git tracks lots of small files internally which means a lot of syncing effort.

  1. Create a virtual environment within the environment-check repository; see Python/Sphinx setup for help creating this environment. Remember to add your virtual environment folder to the .gitignore so it is not tracked by git! [KEG: This just involves adding the file ‘env’ to the “.gitignore’ file]

  2. Activate the virtual environment, and install the listed dependencies with pip install -r requirements.txt. [Note: “requirements.txt” can be found in the protocol repo]

  3. Create and switch to another branch (for example, cjohnsto). [KEG: I found the easiest way to do this is via Github Desktop. Branch > New branch]

  4. Install rushd, a package for sane data management, using pip install rushd. Because you added new packages, update the requirements file by using pip freeze > requirements.txt so someone else could use the same package versions.

  5. Create a datadir.txt file that contains the path to your locally-synced OneDrive. [KEG: Just make a text file and copy the path to your OneDrive (aka SharePoint) folder for the Galloway lab so you can link directly to your data using “rushd”.] For example, the datadir.txt file might look like this (on MacOS):

    /Users/username/Library/CloudStorage/OneDrive-SharedLibraries-MassachusettsInstituteofTechnology/GallowayLab - Documents

    You don’t need any quotes or other characters around the path.

Note

The environment-check script expects that you point the data directory at the root of the OneDrive, e.g. the folder with subdirectories like projects, instruments, etc.

In your own code, you can point the datadir wherever you want, but the root is a typical choice because it lets you access both the raw data in instruments, project folders, and more. You can also always create a “local folder” variable in Python, e.g:

flow_datadir = rd.datadir/'instruments'/'attune'/'chris'
# later in your code
# the following argument resolves to
# OneDrive/instruments/attune/chris/2022.06.21
some_flow_function(flow_datadir/'2022.06.21')

  1. Commit your changed files and push your new branch to Github. [KEG: Stage changes by clicking on the ‘+’ in the ‘Changes’ tab. Then types some message on what you will commit into the space for ‘Source Control’. By clicking ont the check mark, you will commit changes.]

  2. Run python check.py or python3 check.py (MacOS) to see if you get all green checks! [KEG: This only works if you are in the ‘environment-check’ folder]

Note

Some tips from Katie on getting going.

  1. Your virtual environment is basically a container for projects that will help you track packages, versions, ectera. So you need one for spaces you’ll be running python ( for instance in /protocols )

  2. Don’t have permissions to run scripts, see here: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.2

  3. If something isn’t working, try restarting VS Code. Sometimes it just needs to restart.

  4. To install reStructuredText, click here: https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext

  5. Are you sure you installed Sphinx? https://pypi.org/project/Sphinx/

  6. Visually confirming the protocols’ preview is working is encouraging. Try ‘Ctrl+Shift+P’ or ‘Ctrl+Shift+R’

  7. If you get stuck, ask for help!

Protocols check

After getting all green checks, clone the protocols repo (https://github.com/GallowayLabMIT/protocols) and edit this file (docs/bootcamp/iap/environment_check.rst), adding your name to the completion list. Commit and push those changes and you are done! [KEG: To save, “Ctrl+S”].

Completion date

  • Christopher Johnstone (2022-06-01)

  • Katie Galloway (2022-06-13)

  • Emma Peterman (2022-06-13)

  • Kasey Love (2022-06-17)

  • Nathan Wang (2022-06-17)

  • Christian Otero (2022-06-17)

  • Brittany Lende (2022-06-17)

  • Conrad Oakes (2022-06-20)

  • Kei Takahashi (2022-06-20)

  • Adam Beitz (2022-06-21)

  • Patrick Han (2022-06-21)

  • Sneha Kabaria (2022-06-21)

  • Joji Teves (2023-02-24)

  • Deon Ploessl (2023-06-27)