README.md

Workshop: Python Basics

UC Davis DataLab
Fall 2024
Instructors: Elise Hellwig, Nick Ulle
Authors: Arthur Koehl, Tyler Shoemaker, Nick Ulle
Maintainer: Nick Ulle <[email protected]>

• Reader

This 4-part workshop series provides an introduction to using the Python programming language for reproducible data analysis and scientific computing. Topics include programming basics, how to work with tabular data, how to break down programming problems, and how to organize code for clarity and reproducibility.

Learning Objectives

After this workshop, learners should be able to:

• Load tabular data sets into Python
• Compute simple summaries and visualizations
• Do common data-tidying tasks
• Write reusable functions
• Identify where to go to learn more

Prerequisites

No prior programming experience is necessary.

Contributing

The course reader is a live webpage, hosted through GitHub, where you can enter curriculum content and post it to a public-facing site for learners.

To make alterations to the reader:

1. Run git pull, or if it's your first time contributing, see the Setup section of this document.

2. Edit an existing chapter file or create a new one. Chapter files are Markdown files (.md) in the chapters/ directory. Enter your text, code, and other information directly into the file. Make sure your file:

   • Follows the naming scheme ##_topic-of-chapter.md (the only exception is index.md, which contains the reader's front page).
   • Begins with a first-level header (like # This). This will be the title of your chapter. Subsequent section headers should be second-level headers (like ## This) or below.

   Put any supporting resources in data/ or img/. Large files should not be committed. Instead, store them on Google Drive or Box and document that they are necessary. You do not need to add resources generated by your code (such as plots). The next step saves these in docs/ automatically.

3. Run the command jupyter-book build . in a shell at the top level of the repo to regenerate the HTML files in the _build/.

4. When you're finished, git add:

   • Any files you edited directly
   • Any supporting media you added to img/
   • The .gitignore and .gitattributes files

   Then git commit and git push. This updates the main branch of the repo, which contains source materials for the web page (but not the web page itself).

5. Run the command ghp-import -n -p -f _build/html in a shell at the top level of the repo to update the gh-pages branch of the repo. This uses the ghp-import Python package. The live web page will update automatically after 1-10 minutes.

Setup

We strongly recommend using pixi, a fast package manager based on the conda ecosystem, to install the packages required to build this reader. To install pixi, follow the official instructions. If you prefer not to use pixi, it's also possible to manually install the packages using conda or mamba.

The pixi.toml file in this repo lists required packages, while the pixi.lock file lists package versions for each platform. When the lock file is present, pixi will attempt to install the exact versions listed. Deleting the lock file allows pixi to install other versions, which might help if installation fails (but beware of inconsistencies between package versions).

To install the required packages, open a terminal and navigate to this repo's directory. Then run:

pixi install

This will automatically create a virtual environment and install the packages.

To open a shell in the virtual environment, run:

pixi shell

You can run the pixi shell command from the repo directory or any of its subdirectories. Use the virtual environment to run any commands related to building the reader. When you're finished using the virtual environment, you can use the exit command to exit the shell.

Note

If you're using Windows and Git Bash, the pixi shell command is not yet supported. Instead, you can use the pixi run command to run commands in the virtual environment. See the pixi documentation for examples of how to use pixi run.