Getting Started

Sam Foreman

Argonne National Laboratory

We provide below a brief introduction to the project and how to get started using Jupyter @ NERSC

Intro to Unix

• The Intro to Unix page from the Earth and Environmental Data Science book is an excellent resource for those just getting started or who are unfamiliar with the basics of Linux.

• Similarly for their reference on Intro to Git for Version Control

Our project directory can be found at:

/global/cfs/cdirs/m4388/Project2-ClimRR/

All of the data needed for this project has already been copied to the filesystem on NERSC.

In addition, we provide a pre-built (hpc-bootcamp) python kernel which we will use for running our code in Jupyter @ NERSC.

This hpc-bootcamp kernel has everything we will need for this project, including the ClimRR Python package.

Overview of Python

Reference

Material below modified from¹: Python Fundamentals

Invoking Python

There are three main ways to use Python:

1. Running / executing a Python file, e.g. python filename.py
   • this will launch python, execute (line by line) the contents of filename.py, and return
2. Interactively, either through:
   1. a console (e.g. the Python interpreter python or an IPython shell ipython)
   2. a notebook (e.g. Jupyter notebook)*

*we will (mostly) focus on using Jupyter notebooks for this project.

Modules and Packages in Python

As an illustrative example for how to use and work with Python, we’ve included a simple Python package (ClimRR) in our climate-analysis/ repo.

This Python package, CLimRR, is located in src/ClimRR/ and contains the following²:

• climate-analysis/
  • 📂 src/
    • 📂 ClimRR/
      • 🐍 __about__.py
      • 🐍 __init__.py
      • 🐍 data.py

In particular, the Python package³ that we will use for this project, ClimRR is located inside our src/ClimRR directory.

This is a simple example just to

• __init__.py: Any folder containing an __init__.py file is considered a Python library.

  Oftentimes they are empty⁴, but ours contains some (not terribly important) functions for specifying where our data lives, setting up logging, etc.

• __about__.py: A strictly informational (metadata!) file that can be used to (dynamically!) specify a package version. Again, this isn’t important for our purposes but incase you’re wondering what it does⁵.

• data.py: Contains some simple (but useful!) functions for loading our Shapefile, loading US County data, and loading ClimRR climate data from *.CSVs

Finding the data

The data needed for this project has already been copied to the NERSC systems and can be found at:

For those curious, the ClimRR data we will be working with looks something like:

$ tree /global/cfs/cdirs/m4388/Project2-ClimRR/data/ClimRR/
/global/cfs/cdirs/m4388/Project2-ClimRR/data/ClimRR/
├── AnnualTemperatureMaximum.csv
├── AnnualTemperatureMinimum.csv
├── ClimRR Metadata and Data Dictionary.pdf
├── ConsecutiveDayswithNoPrecipitation.csv
├── FireWeatherIndex_Wildfire.csv
├── GridCells2Shapefile.zip
├── GridCellsShapefile.zip
├── HeatingDegreeDays.csv
├── Precipitation_inches_AnnualTotal.csv
├── README.txt
├── SeasonalTemperatureMaximum.csv
├── SeasonalTemperatureMinimum.csv
└── WindSpeed.csv

the data is also available online and can be downloaded from ClimRR Data Download (ANL)

Setup

To get started, we will need to:

1. Create a symlink from the project directory, /global/cfs/cdirs/m4388/Project2-ClimRR/ into your $HOME directory

   ln -s /global/cfs/cdirs/m4388/Project2-ClimRR/ $HOME/Project2-ClimRR

2. Navigate into here and create your personal directory (where you will store and work on your project):

   cd $HOME/Project2-ClimRR/
   mkdir $USER
   cd $USER

3. Clone the GitHub repo

   git clone https://github.com/saforem2/climate-analysis

4. Navigate to jupyter.nersc.gov and login.

   • Jupyter for the New User to NERSC
   • Using Jupyter at NERSC

5. Navigate into your personal directory in our /global/cfs/cdirs/m4388/Project2-ClimRR/ project space:

   

   Figure 1: Screenshots of the Jupyter interface at NERSC

Footnotes

1. Which itself is modified from the official python tutorial

2. Recall, a Python module is an individual file .py containing some Python code. A Python library is then a collection of these modules, organized around some central idea or purpose.

3. Roughly, package \simeq library for our purposes

4. More information on __init__.py and Python packages can be found here

5. Additional information here. Again, understanding the details of python packaging is well beyond the scope of this project, but I’ve included some details here for those curious.

Citation

BibTeX citation:

@online{foreman2023,
  author = {Foreman, Sam},
  title = {Energy {Justice} {Analysis} of {Climate} {Data} with
    {ClimRR}},
  date = {2023-08-08},
  url = {https://saforem2.github.io/climate-analysis},
  langid = {en}
}

For attribution, please cite this work as:

Foreman, Sam. 2023. “Energy Justice Analysis of Climate Data with ClimRR.” Intro to HPC Bootcamp @ NERSC: ClimRR. August 8, 2023. https://saforem2.github.io/climate-analysis.