The Carpentries project comprises the Software Carpentry, Data Carpentry, and
Library Carpentry communities of Instructors, Trainers, Maintainers,
helpers, and supporters who share a mission to teach foundational computational and data science
skills to researchers.
Want to learn more and stay engaged with The Carpentries? Carpentries Clippings is The Carpentries' biweekly newsletter, where we share community news, community job postings, and more.
Sign up to receive future editions and read our full archive: https://carpentries.org/newsletter/
Software Carpentry
aims to help researchers get their work done
in less time and with less pain
by teaching them basic research computing skills.
This hands-on workshop will cover basic concepts and tools,
including program design, version control, data management,
and task automation.
Participants will be encouraged to help one another
and to apply what they have learned to their own research problems.
Who:
The course is aimed at graduate students and other researchers.
You don't need to have any previous knowledge of the tools
that will be presented at the workshop.
Where:
Teaching room "Half-moon Bay",
Genentech Building 85,
601 Gateway Blvd,
South San Francisco, CA, 94080
.
Get directions with
OpenStreetMap
or
Google Maps.
What3Words location:
///cute.crush.train.
Requirements:
Participants must bring a laptop with a
Mac, Linux, or Windows operating system (not a tablet, Chromebook, etc.) that they have administrative privileges on.
They should have a few specific software packages installed (listed below).
Accessibility:
We are committed to making this workshop
accessible to everybody.
The workshop organizers have checked that:
The room is wheelchair / scooter accessible.
Accessible restrooms are available.
We are dedicated to providing a positive and accessible learning environment for all.
We do not require participants to provide documentation of disabilities or disclose any unnecessary personal information.
However, we do want to help create an inclusive, accessible experience for all participants.
We encourage you to share any information that would be helpful to make your Carpentries experience accessible.
To request an accommodation for this workshop, please fill out the
accommodation request form.
If you have questions or need assistance with the accommodation form please email us.
Glosario is a multilingual glossary
for computing and data science terms. The glossary helps
learners attend workshops and use our lessons to make sense of computational and programming jargon written in English by offering it
in their native language. Translating data science terms also provides a teaching tool for Carpentries Instructors to reduce barriers
for their learners.
Roles:
To learn more about the roles at the workshop (who will be doing what),
refer to our Workshop FAQ.
Code of Conduct
Everyone who participates in Carpentries activities is required to conform to the Code of Conduct. This document also outlines how to report an incident if needed.
Collaborative Notes
We will use this collaborative document for chatting, taking notes, and sharing URLs and bits of code.
Surveys
Please be sure to complete these surveys before and after the workshop.
To participate in a
Software Carpentry
workshop,
you will need access to software as described below.
In addition, you will need an up-to-date web browser.
Click on "Next" four times (two times if you've previously
installed Git). You don't need to change anything
in the Information, location, components, and start menu screens.
From the dropdown menu, "Choosing the default editor used by Git", select "Use the Nano editor by default" (NOTE: you will need to scroll up to find it) and click on "Next".
On the page that says "Adjusting the name of the initial branch in new repositories", ensure that
"Let Git decide" is selected. This will ensure the highest level of compatibility for our lessons.
Ensure that "Git from the command line and also from 3rd-party software" is selected and
click on "Next". (If you don't do this Git Bash will not work properly, requiring you to
remove the Git Bash installation, re-run the installer and to select the "Git from the
command line and also from 3rd-party software" option.)
Select "Use bundled OpenSSH".
Ensure that "Use the native Windows Secure Channel Library" is selected and click on "Next".
Ensure that "Checkout Windows-style, commit Unix-style line endings" is selected and click on "Next".
Ensure that "Use Windows' default console window" is selected and click on "Next".
Ensure that "Default (fast-forward or merge) is selected and click "Next"
Ensure that "Git Credential Manager" is selected and click on "Next".
Ensure that "Enable file system caching" is selected and click on "Next".
Click on "Install".
Click on "Finish" or "Next".
If your "HOME" environment variable is not set (or you don't know what this is):
Open command prompt (Open Start Menu then type cmd and press Enter)
Type the following line into the command prompt window exactly as shown:
setx HOME "%USERPROFILE%"
Press Enter, you should see SUCCESS: Specified value was saved.
Quit command prompt by typing exit then pressing Enter
This will provide you with both Git and Bash in the Git Bash program.
Video Tutorial
The default shell in Mac OS X Ventura and newer versions is Zsh, but
Bash is available in all versions, so no need to install anything.
You access Bash from the Terminal (found in
/Applications/Utilities).
See the Git installation video tutorial
for an example on how to open the Terminal.
You may want to keep Terminal in your dock for this workshop.
To see if your default shell is Bash type echo $SHELL
in Terminal and press the Return key. If the message
printed does not end with '/bash' then your default is something
else, you can change your current shell to Bash by typing
bash and then pressing Return. To check
your current shell type echo $0 and press Return.
To change your default shell to Bash type chsh -s /bin/bash and
press the Return key, then reboot for the change to take effect. To
change your default back to Zsh, type chsh -s /bin/zsh, press the
Return key and reboot. To check available shells, type
cat /etc/shells.
Video Tutorial
The default shell is usually Bash and there is usually no need to
install anything.
To see if your default shell is Bash type echo $SHELL
in Terminal and press the Return key. If the message
printed does not end with '/bash' then your default is something
else, you can change your current shell to Bash by typing
bash and then pressing Return. To check
your current shell type echo $0 and press Return.
To change your default shell to Bash type chsh -s /bin/bash and
press the Return key, then reboot for the change to take effect. To
change your default back to Zsh, type chsh -s /bin/zsh, press the
Return key and reboot. To check available shells, type
cat /etc/shells.
Git
Git is a version control system that lets you track who made changes
to what when and has options for easily updating a shared or public
version of your code
on github.com. You will need a
supported
web browser.
Please open the Terminal app, type git --version and press
Enter/Return. If it's not installed already,
follow the instructions to Install the "command line
developer tools". Do not click "Get Xcode", because that will
take too long and is not necessary for our Git lesson.
After installing these tools, there won't be anything in your /Applications
folder, as they and Git are command line programs.
For older versions of OS X (10.5-10.8) use the
most recent available installer labelled "snow-leopard"
available here.
(Note: this project is no longer maintained.)
Because this installer is not signed by the developer, you may have to
right click (control click) on the .pkg file, click Open, and click
Open in the pop-up dialog. You can watch
a video tutorial about this case.
Video Tutorial
If Git is not already available on your machine you can try to
install it via your distro's package manager. For Debian/Ubuntu run
sudo apt-get install git and for Fedora run
sudo dnf install git.
Text Editor
When you're writing code, it's nice to have a text editor that is
optimized for writing code, with features like automatic
color-coding of key words. The default text editor on macOS and
Linux is usually set to Vim, which is not famous for being
intuitive. If you accidentally find yourself stuck in it, hit
the Esc key, followed by :+Q+!
(colon, lower-case 'q', exclamation mark), then hitting Return to
return to the shell.
nano is a basic editor and the default that instructors use in the workshop.
It is installed along with Git.
nano is a basic editor and the default that instructors use in the workshop.
See the Git installation video tutorial
for an example on how to open nano.
It should be pre-installed.
Video Tutorial
nano is a basic editor and the default that instructors use in the workshop.
It should be pre-installed.
Python
Python is a popular language for
research computing, and great for general-purpose programming as
well. Installing all of its research packages individually can be
a bit difficult, so we recommend
Conda-forge,
an all-in-one installer.
Regardless of how you choose to install it,
please make sure you install Python version 3.10 or higher
(e.g., 3.10, 3.11, 3.12, or 3.13 is fine).
We do not recommend using an older version (e.g. 3.6),
but please let us know if you need to use an older version.
We will teach Python using the Jupyter Notebook,
a programming environment that runs in a web browser (Jupyter Notebook will be installed by Miniforge). For this to work you will need a reasonably
up-to-date browser. The current versions of the Chrome, Safari and
Firefox browsers are all
supported
(some older browsers, including Internet Explorer version 9
and below, are not).
Double click on the downloaded file (Something like, Minforge3-Windows-x86_64.exe)
If you get a "Windows protected your PC" pop-up from Microsoft Defender SmartScreen, click on "More info" and select "Run anyway"
Follow through the installer using all of the defaults for installation except make sure to check Add Miniforge3 to my PATH environment variable.
Download the environment file.
This file helps conda create an environment for you to use that
has all the packages you'll need, and makes sure that it comes from
the non-commercial "conda-forge" channel.
(The following steps requires using the shell. If you aren't
comfortable doing the installation yourself
stop here and request help at the workshop.)
Search for the application "Miniforge Prompt", open it and run:
conda env create -f .\Downloads\swc_environment.yaml
Download the appropriate Miniforge installer for macOS
(The following steps requires using the shell. If you aren't
comfortable doing the installation yourself
stop here and request help at the workshop.)
Open a terminal window and navigate to the directory where
the executable is downloaded (e.g., cd ~/Downloads).
Type
bash Miniforge3-
and then press
Tab to autocomplete the full file name. The name of
file you just downloaded should appear.
Press Enter
(or Return depending on your keyboard).
You will follow the text-only prompts.
To move through the text, press Spacebar.
Type yes and press enter to approve the license.
Press Enter (or Return)
to approve the default location
for the files.
Type yes and press
Enter (or Return)
to prepend Miniforge to your PATH
(this makes the Miniforge distribution the default Python).
Download the environment file.
This file helps conda create an environment for you to use that
has all the packages you'll need, and makes sure that it comes from
the non-commercial "conda-forge" channel.
On the terminal run: conda env create -f ~/Downloads/swc_environment.yaml
Download the appropriate Miniforge installer for Linux
(The following steps requires using the shell. If you aren't
comfortable doing the installation yourself
stop here and request help at the workshop.)
Open a terminal window and navigate to the directory where
the executable is downloaded (e.g., `cd ~/Downloads`).
Type
bash Miniforge3-
and then press
Tab to autocomplete the full file name. The name of
file you just downloaded should appear.
Press Enter
(or Return depending on your keyboard).
You will follow the text-only prompts.
To move through the text, press Spacebar.
Type yes and press enter to approve the license.
Press Enter (or Return)
to approve the default location
for the files.
Type yes and press
Enter (or Return)
to prepend Miniforge to your PATH
(this makes the Miniforge distribution the default Python).
Download the environment file.
This file helps conda create an environment for you to use that
has all the packages you'll need, and makes sure that it comes from
the non-commercial "conda-forge" channel.
Open a terminal window and run: conda env create -f ~/Downloads/swc_environment.yaml
Close the terminal window.
Troubleshooting common installation problems
Here’s some common problems that people have and how to get past them.
SSL errors
A common error people are seeing when they run the command
conda env create -f ~/Downloads/swc_environment.yaml
is that it printes error messages with text like
“CondaSSLError”,
“Exception: HTTPSConnectionPool”,
“SSL: CERTIFICATE_VERIFY_FAILED”.
If this looks familiar, you can do the following:
On that same “terminal” as you ran the command that starts with “conda”,
paste in the following command: conda config --set ssl_verify False
Press enter to run that.
Then, paste in and run (with enter) the command
conda env create -f ~/Downloads/swc_environment.yaml
You’ll know that it’s working if it says something like
“Collecting package metadata”. At this stage, it takes probably 5 minutes to
download and setup the environment.
By the way, if you put the swc_environment.yaml file somewhere else other
than in your Downloads folder, you’ll need to
specify that. But if it’s in your normal Downloads folder, you’re good to
use conda env create -f ~/Downloads/swc_environment.yaml .
'$' is not recognized...
This error message is because the “$” isn’t actually part of the command you
want to run.
A fast way to fix this is to:
Press up-arrow (which will “paste” the last command back up in the terminal).
Then you can use the arrow keys to go to the “$” and delete the “$”
with backspace.
Then press enter to run the command.
How do I open a bash terminal / window in MacOSX?
Run the “Terminal” app.
You should see a mostly white background window show
up with the txt. It might say “zsh” somewhere in the title of the window.
Congrats, you are now using a terminal!
How do I open a bash terminal / window in Windows?
Once you installed the “Git for Windows” installer (in the bash section above),
then
Press the “Windows” icon key to open up your Start menu.
Find the “Git Bash” application.
Depending on your version of Windows, you
might want to type “Git” into a searchbar, or browse through menus of
Programs until you find the “Git Bash” application under “G”.
Run the “Git Bash” application. You should see a window open up with text,
and if you type in ls and press enter, it should list off some files on
your system. Congrats, you are now using a terminal!
Files are failing to open in a “Brackets” application
In the instructions above, we’ve asked you to download and use some files.
For some of those files, if you have a program called “Brackets” installed
then if you try to open these files by clicking on them, then it may try
to run these files (and fail with an error window!).
Instead, just save them in the usual place (likely the Downloads folder),
then try using the terminal commands we provided above.
If I already have another version of Python installed, will that be a problem?
Very probably not!
We are using these “conda” tools to install and keep separate all the software
and libraries we are installing for the workshop (python, jupyter, pandas,
etc). This means that when you successfully “activate” the “swc-gapminder”
environment, it should be using the “swc-gapminder” version of python only.
If you don’t activate it, then it shouldn’t use this.
So you shouldn’t have any problems with other versions of Python.
Do I have to use nano as an editor?
nano is a great simple editor for use in the terminal and we recommend it.
If you know how to use a terminal-based text editor like emacs, vim,
or ed, those options also work.
If you don’t know about these, then we recommend just using nano.