From fdb05e2b362ef4a779ef3f2153af2494463d4385 Mon Sep 17 00:00:00 2001 From: e-belfer Date: Thu, 30 Jan 2025 10:43:58 -0500 Subject: [PATCH 1/3] Add git github and API keys --- learners/setup.md | 188 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 159 insertions(+), 29 deletions(-) diff --git a/learners/setup.md b/learners/setup.md index 4244a31..9fc1a11 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -2,53 +2,183 @@ title: Setup --- -FIXME: Setup instructions live in this document. Please specify the tools and -the data sets the Learner needs to have installed. +## Overview -## Data Sets +This lesson is designed to be run on a personal computer. +All of the software and data used in this lesson are freely available online, +and instructions on how to obtain them are provided below. - -Download the [data zip file](https://example.com/FIXME) and unzip it to your Desktop +## Obtain lesson materials -## Software Setup +TODO: Do we want people to fork the entire repo or just download the data? If the first, that should come after GH setup. + -### Details +## Accessing lesson data -Setup for different systems can be presented in dropdown menus via a `spoiler` -tag. They will join to this discussion block, so you can give a general overview -of the software used in this lesson here and fill out the individual operating -systems (and potentially add more, e.g. online setup) in the solutions blocks. +### Create an API key for accessing the EIA API +In episode 3 and 4, we'll be learning how to access the Application Programming Interface (API) +for the Energy Information Administration (EIA). To register for an EIA API key: -::::::::::::::::::::::::::::::::::::::::::::::::::: +1. Go to the [EIA API website](https://www.eia.gov/opendata/). +2. Click "Register" on the right-hand side and complete the form. +3. Log in to the email address you provided - you should have received an email from the +EIA with the subject line "EIA API Registration Key" that contains your API key. -:::::::::::::::: spoiler +### Create an API key for accessing the EPA API +In episode 3 and 4, we'll also be exploring the Environmental Protection Agency's (EPA) +Clean Air Markets API portal. To register for an EPA API key: -### Windows +1. Go to the [registration page](https://www.epa.gov/power-sector/cam-api-portal#/api-key-signup) and fill out the form. +2. Log in to the email address you provided. You should have received an email from the EPA +containing an API key for the Clean Air Markets API portal. -Use PuTTY +## Installing Git -:::::::::::::::::::::::: +Since many Carpentries lessons rely on Git, please see +[this section of the workshop template](https://carpentries.github.io/workshop-template/install_instructions/#git) for +instructions on installing Git for various operating systems. -:::::::::::::::: spoiler +- [Git installation on Windows](https://carpentries.github.io/workshop-template/install_instructions/#git) +- [Git installation on MacOS](https://carpentries.github.io/workshop-template/install_instructions/#git) +- [Git installation on Linux](https://carpentries.github.io/workshop-template/install_instructions/#git) -### MacOS +## Create an account on GitHub -Use Terminal.app +You will need an account for [GitHub](https://github.com) to follow episodes *(TODO!)* in this lesson. -:::::::::::::::::::::::: +1. Go to and follow the "Sign up" link at the top-right of the window. +2. Follow the instructions to create an account. +3. Verify your email address with GitHub. +4. Configure multifactor authentication (see below). +Basic GitHub accounts are free. As you set up your account,p lease consider what personal +information you'd like to reveal. For example, you may want to review these +[instructions for keeping your email address private]("https://help.github.com/articles/keeping-your-email-address-private/") provided at GitHub. -:::::::::::::::: spoiler +### Multi-factor Authentication -### Linux +In 2023, GitHub introduced a requirement for +all accounts to have +[multi-factor authentication (2FA)](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) +configured for extra security. +Several options exist for setting up 2FA, which are summarised here: -Use Terminal +1. If you already use an authenticator app, + like [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en&co=GENIE.Platform%3DiOS&oco=0) + or [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app) on your smartphone for example, + [add GitHub to that app](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-mobile-app). +2. If you have access to a smartphone but do not already use an authenticator app, install one and + [add GitHub to the app](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-mobile-app). +3. If you do not have access to a smartphone or do not want to install an authenticator app, you have two options: + 1. [set up 2FA via text message](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-text-messages) + ([list of countries where authentication by SMS is supported](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/countries-where-sms-authentication-is-supported)), or + 2. [use a hardware security key](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key) + like [YubiKey](https://www.yubico.com/products/yubikey-5-overview/) + or the [Google Titan key](https://store.google.com/us/product/titan_security_key?hl=en-US&pli=1). -:::::::::::::::::::::::: +The GitHub documentation provides [more details about configuring 2FA](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). +## Launch Python interface - TODO! + +To start working with Python, we need to launch a program that will interpret and execute our +Python commands. Below we list several options. If you don't have a preference, proceed with the +top option in the list that is available on your machine. Otherwise, you may use any interface +you like. + +## Option A: Jupyter Notebook + +A Jupyter Notebook provides a browser-based interface for working with Python. +If you installed Anaconda, you can launch a notebook in two ways: + +::::::::::::::::: spoiler + +## Anaconda Navigator + +1. Launch Anaconda Navigator. + It might ask you if you'd like to send anonymized usage information to Anaconda developers: + ![](fig/anaconda-navigator-first-launch.png){alt='Anaconda Navigator first launch'} + Make your choice and click "Ok, and don't show again" button. +2. Find the "Notebook" tab and click on the "Launch" button: + ![](fig/anaconda-navigator-notebook-launch.png){alt='Anaconda Navigator Notebook launch'} + Anaconda will open a new browser window or tab with a Notebook Dashboard showing you the + contents of your Home (or User) folder. +3. Navigate to the `data` directory by clicking on the directory names leading to it: + `Desktop`, `swc-python`, then `data`: + ![](fig/jupyter-notebook-data-directory.png){alt='Anaconda Navigator Notebook directory'} +4. Launch the notebook by clicking on the "New" button and then selecting "Python 3": + ![](fig/jupyter-notebook-launch-notebook.png){alt='Anaconda Navigator Notebook directory'} + +::::::::::::::::::::::::: + + +::::::::::::::::: spoiler + +## Command line (Terminal) + +1\. Navigate to the `data` directory: + +::::::::::::::::: spoiler + +## Unix shell + +If you're using a Unix shell application, such as Terminal app in macOS, Console or Terminal +in Linux, or [Git Bash][gitbash] on Windows, execute the following command: + +```bash +cd ~/Desktop/swc-python/data +``` + +::::::::::::::::::::::::: + +::::::::::::::::: spoiler + +## Command Prompt (Windows) + +On Windows, you can use its native Command Prompt program. The easiest way to start it up is +pressing Windows Logo Key\+R, entering `cmd`, and hitting +Return. In the Command Prompt, use the following command to navigate to +the `data` folder: + +```source +cd /D %userprofile%\Desktop\swc-python\data +``` + +::::::::::::::::::::::::: + +2\. Start Jupyter server + +::::::::::::::::: spoiler + +## Unix shell + +```bash +jupyter notebook +``` + +::::::::::::::::::::::::: + + +::::::::::::::::: spoiler + +## Command Prompt (Windows) + +```source +python -m notebook +``` + +::::::::::::::::::::::::: + +3\. Launch the notebook by clicking on the "New" button on the right and selecting "Python 3" +from the drop-down menu: +![](fig/jupyter-notebook-launch-notebook2.png){alt='Anaconda Navigator Notebook directory'} + +::::::::::::::::::::::::: + +  From 44f642823e657bdc798948a66d2386ac19cc07c0 Mon Sep 17 00:00:00 2001 From: e-belfer Date: Thu, 30 Jan 2025 11:21:53 -0500 Subject: [PATCH 2/3] Add prereqs, update GH, add git clone --- config.yaml | 1 + learners/setup.md | 77 +++++++++++++++++++++++++++++++++++------------ 2 files changed, 58 insertions(+), 20 deletions(-) diff --git a/config.yaml b/config.yaml index e8d8cf4..4b9d426 100644 --- a/config.yaml +++ b/config.yaml @@ -72,6 +72,7 @@ episodes: # Information for Learners learners: +- setup.md # Information for Instructors instructors: diff --git a/learners/setup.md b/learners/setup.md index 9fc1a11..7035ec3 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -2,7 +2,48 @@ title: Setup --- -## Overview +## Summary - TODO + +::: prereq + +### Prerequisite Python knowledge +This lesson assumes an introductory knowledge of Python and the `pandas` library. Participants should: + +* be comfortable reading CSV files into Pandas DataFrames +* be able to do basic data transformations in Pandas: for instance, renaming columns, merging two datasets on a shared column, or multiplying a column by a scalar value. +* be able to save transformed Pandas DataFrames locally (e.g., as a CSV) +* be able to create simple graphs in Python +* be able to write a simple function + +These skills are equivalent to the completion of the [Data Analysis and Visualization in +Python for Ecologists](https://datacarpentry.github.io/python-ecology-lesson/) lesson. If you +haven’t already completed this lesson and aren’t familiar with the skills listed above, please +review those materials before starting this lesson. + +### Prerequisite Git knowledge +This lesson assumes `git` is installed locally, and that participants have a basic +familiarity with the `git` version control command-line tool. Participants should be able to: +* create a local Git repository +* use commits to track changes in files +* push to and pull from a remote repository + +These skills are covered in the Software Carpentries' [Version Control with Git](https://swcarpentry.github.io/git-novice/) lesson. If you aren't familiar with the skills listed above, please review +those materials before starting this lesson. + +### Other prerequisite knowledge +Throughout this lesson, we'll be working with a variety of energy datasets. In order to +get the most out of this lesson, we expect that participants: +* have some domain knowledge about the energy sector (e.g., are studying energy systems +in university). +* have energy-relevant research questions that you want to answer using data + +Though these are not *mandatory* for participation in the lesson, we believe these skills +are critical to interpreting the data and applying the skills learned in these lessons +to your own work. + +::: + +## Setup: Overview This lesson is designed to be run on a personal computer. All of the software and data used in this lesson are freely available online, @@ -10,17 +51,23 @@ and instructions on how to obtain them are provided below. ## Obtain lesson materials -TODO: Do we want people to fork the entire repo or just download the data? If the first, that should come after GH setup. - +To clone the repository, you must have `git` installed and configured on your computer (one of +the prerequisites for this lesson). If you need additional guidance on `git` setup, see the Software Carpentries' [Version Control with Git](https://swcarpentry.github.io/git-novice/) lesson. -## Accessing lesson data +## Accessing remote lesson data + +In episodes 3 and 4 of this lesson, we'll learn how to efficiently access remote data. +To do so, we'll need to set up credentials to access these resources. ### Create an API key for accessing the EIA API In episode 3 and 4, we'll be learning how to access the Application Programming Interface (API) @@ -39,16 +86,6 @@ Clean Air Markets API portal. To register for an EPA API key: 2. Log in to the email address you provided. You should have received an email from the EPA containing an API key for the Clean Air Markets API portal. -## Installing Git - -Since many Carpentries lessons rely on Git, please see -[this section of the workshop template](https://carpentries.github.io/workshop-template/install_instructions/#git) for -instructions on installing Git for various operating systems. - -- [Git installation on Windows](https://carpentries.github.io/workshop-template/install_instructions/#git) -- [Git installation on MacOS](https://carpentries.github.io/workshop-template/install_instructions/#git) -- [Git installation on Linux](https://carpentries.github.io/workshop-template/install_instructions/#git) - ## Create an account on GitHub You will need an account for [GitHub](https://github.com) to follow episodes *(TODO!)* in this lesson. From 8a38ef34feab04f2f22e16811a312d83b00cf057 Mon Sep 17 00:00:00 2001 From: e-belfer Date: Thu, 30 Jan 2025 11:42:36 -0500 Subject: [PATCH 3/3] Add WIP uv instructions --- learners/setup.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/learners/setup.md b/learners/setup.md index 7035ec3..1aa3955 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -64,6 +64,25 @@ all lesson materials. To clone the repository, you must have `git` installed and configured on your computer (one of the prerequisites for this lesson). If you need additional guidance on `git` setup, see the Software Carpentries' [Version Control with Git](https://swcarpentry.github.io/git-novice/) lesson. +## Setting up the `uv` package manager + +We use `uv` to manage the installation of Python packages needed for this lesson. `uv` is +a package manager + +### Installing `uv` + +1. Follow the [installation instructions](https://docs.astral.sh/uv/getting-started/installation/) provided for `uv`. +2. Run the command `uv` in your terminal to verify that the installation has succeeded. + +### Setting up the lesson environment +Once we've installed `uv`, we can use it to create a virtual environment. We'll cover +virtual environments in lesson *(TODO)*, but in short these are virtual, disposable Python +software environments that contain only the packages you want to use for a particular project +or task. If you don't have a working copy of Python locally, `uv` will install it as part +of the environment set-up step. + +__TODO__: Write `uv` set-up instructions from `pyproject.toml` file. + ## Accessing remote lesson data In episodes 3 and 4 of this lesson, we'll learn how to efficiently access remote data. @@ -95,7 +114,7 @@ You will need an account for [GitHub](https://github.com) to follow episodes *(T 3. Verify your email address with GitHub. 4. Configure multifactor authentication (see below). -Basic GitHub accounts are free. As you set up your account,p lease consider what personal +Basic GitHub accounts are free. As you set up your account, please consider what personal information you'd like to reveal. For example, you may want to review these [instructions for keeping your email address private]("https://help.github.com/articles/keeping-your-email-address-private/") provided at GitHub.