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.
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.
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 bygit
! [KEG: This just involves adding the file ‘env’ to the “.gitignore’ file]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]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]Install
rushd
, a package for sane data management, usingpip install rushd
. Because you added new packages, update the requirements file by usingpip freeze > requirements.txt
so someone else could use the same package versions.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')
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.]
Run
python check.py
orpython3 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.
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 )
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
If something isn’t working, try restarting VS Code. Sometimes it just needs to restart.
To install reStructuredText, click here: https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext
Are you sure you installed Sphinx? https://pypi.org/project/Sphinx/
Visually confirming the protocols’ preview is working is encouraging. Try ‘Ctrl+Shift+P’ or ‘Ctrl+Shift+R’
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)
Mary Ehmann (2024-01-15)
Diya Godavarti (2024-06-03)
Eliska Liang (2024-06-24)
Yunbeen Bae (2024-08-08)