-
-
-
diff --git a/tutorial/CAP_Exercises.md b/tutorial/CAP_Exercises.md
deleted file mode 100644
index 4097e5e4..00000000
--- a/tutorial/CAP_Exercises.md
+++ /dev/null
@@ -1,947 +0,0 @@
-
-
-# Practice Exercises - Community Analysis Pipeline (CAP)
-
-
-
-CAP is a Python toolkit designed to simplify post-processing and plotting MGCM output. CAP consists of five Python executables:
-
-1. `MarsPull.py` → accessing MGCM output
-2. `MarsFiles.py` → reducing the files
-3. `MarsVars.py` → performing variable operations
-4. `MarsInterp.py` → interpolating the vertical grid
-5. `MarsPlot.py` → plotting MGCM output
-
-The following exercises are organized into two parts by function. We will go through **Part I on Monday Nov. 13** and **Part II on Tuesday Nov. 14**.
-
-**[Part I: File Manipulations](#part-i-file-manipulations) → `MarsFiles.py`, `MarsVars.py`, & `MarsInterp.py`**
-
-**[Part II: Plotting with CAP](#part-ii-plotting-with-cap) → `MarsPlot.py`**
-
-> We will not be going over `MarsPull.py` because it is specifically for retrieving MGCM data from the online MGCM data repository. Instructions for `MarsPull.py` was covered in the [2021 Legacy Version Tutorial](https://github.com/NASA-Planetary-Science/AmesCAP/blob/master/tutorial/CAP_Install.md).
-
-***
-
-## Table of Contents
-
-- [Practice Exercises - Community Analysis Pipeline (CAP)](#practice-exercises---community-analysis-pipeline-cap)
- - [Table of Contents](#table-of-contents)
- - [Activating CAP](#activating-cap)
- - [Following Along with the Tutorial](#following-along-with-the-tutorial)
-- [Part I: File Manipulations](#part-i-file-manipulations)
- - [1. MarsPlot's `--inspect` Function](#1-marsplots---inspect-function)
- - [2. Editing Variable Names and Attributes](#2-editing-variable-names-and-attributes)
- - [3. Splitting Files in Time](#3-splitting-files-in-time)
- - [4. Deriving Secondary Variables](#4-deriving-secondary-variables)
- - [5. Time-Shifting `Diurn` Files](#5-time-shifting-diurn-files)
- - [6. Pressure-Interpolating the Vertical Axis](#6-pressure-interpolating-the-vertical-axis)
-- [Optional: Use the Answer Key for Part I](#optional-use-the-answer-key-for-part-i)
-- [CAP Practical Day 2](#cap-practical-day-2)
-- [Part II: Plotting with CAP](#part-ii-plotting-with-cap)
- - [Step 1: Creating the Template (`Custom.in`)](#step-1-creating-the-template-customin)
- - [Step 2: Editing `Custom.in`](#step-2-editing-customin)
- - [Step 3: Generating the Plots](#step-3-generating-the-plots)
-- [Custom Set 1 of 4: Zonal Mean Surface Plots Over Time](#custom-set-1-of-4-zonal-mean-surface-plots-over-time)
-- [Custom Set 2 of 4: Global Mean Column-Integrated Dust Optical Depth Over Time](#custom-set-2-of-4-global-mean-column-integrated-dust-optical-depth-over-time)
-- [Custom Set 3 of 4: 50 Pa Temperatures at 3 AM and 3 PM](#custom-set-3-of-4-50-pa-temperatures-at-3-am-and-3-pm)
-- [Custom Set 4 of 4: Zonal Mean Circulation Cross-Sections](#custom-set-4-of-4-zonal-mean-circulation-cross-sections)
-
-***
-
-## Activating CAP
-
-Activate the `amesCAP` virtual environment to use CAP:
-
-```bash
-(cloud)~$ source ~/amesCAP/bin/activate
-(amesCAP)~$
-```
-
-Confirm that CAP's executables are accessible by typing:
-
-```bash
-(amesCAP)~$ MarsVars.py -h
-```
-
-The `--help [-h]` argument prints documentation for the executable to the terminal. Now that we know CAP is configured, make a copy of the file `amescap_profile` in your home directory, and make it a hidden file:
-
-```bash
-(amesCAP)~$ cp ~/amesCAP/mars_templates/amescap_profile ~/.amescap_profile
-```
-
-CAP stores useful settings in `amescap_profile`. Copying it to our home directory ensures it is not overwritten if CAP is updated or reinstalled.
-
-### Following Along with the Tutorial
-
-**Part I covers file manipulations**. Some exercises build off of previous exercises so *it is important to complete them in order*. If you make a mistake or get behind in the process, you can go back and catch up during a break or use the provided answer key before continuing on to Part II.
-
-**Part II demonstrates CAP's plotting routine**. There is more flexibility in this part of the exercise.
-
-**We will perform every exercise together.**
-
-> *Feel free to **put questions in the chat** throughout the tutorial. Another MGCM member can help you as we go.*
->
-*[Return to Top](#table-of-contents)*
-
-# Part I: File Manipulations
-
-CAP has dozens of post-processing capabilities. We will go over a few of the most commonly used functions in this tutorial. We will cover:
-
-- **Interpolating** data to different vertical coordinate systems (`MarsInterp.py`)
-- **Adding derived variables** to the files (`MarsVars.py`)
-- **Time-shifting** data to target local times (`MarsFiles.py`)
-- **Trimming** a file to reduce its size (`MarsFiles.py`).
-
-The required MGCM output files are already loaded in the cloud environment under `tutorial_files/cap_exercises/`. Change to that directory and look at the contents:
-
-```bash
-(amesCAP)~$ cd tutorial_files/cap_exercises
-(amesCAP)~$ ls
-03340.atmos_average.nc 03340.backup.zip part_1_key.sh
-03340.atmos_diurn.nc 03340.fixed.nc part_2_plots.in
-```
-
-The three MGCM output files have a 5-digit sol number appended to the front of the file name. The sol number indicates the day that a file's record begins. These contain output from the sixth year of a simulation. The zipped file is an archive of these three output files in case you need it.
-
-The other two files, `part_1_key.sh` and `part_2_plots.sh` are discussed later. We can ignore them for now.
-
-> *The output files we manipulate in Part I will be used to generating plots in Part II so do **not** delete any file you create!*
-
-Let's begin the tutorial.
-
-## 1. MarsPlot's `--inspect` Function
-
-The inspect function is part of `MarsPlot.py` and it prints netCDF file contents to the screen.
-
-To use it on the `average` file, `03340.atmos_average.nc`, type the following in the terminal:
-
-```bash
-(amesCAP)~$ MarsPlot.py -i 03340.atmos_average.nc
-```
-
-> This is a good time to remind you that if you are unsure how to use a function, invoke the `--help [-h]` argument with any executable to see its documentation (e.g., `MarsPlot.py -h`).
-
-*[Return to Part I](#part-i-file-manipulations)*
-
-***
-
-## 2. Editing Variable Names and Attributes
-
-In the previous exercise, `--inspect [-i]` revealed a variable called `opac` in `03340.atmos_average.nc`. `opac` is dust opacity per pascal and it is similar to another variable in the file, `dustref`, which is opacity per (model) level. Let's rename `opac` to `dustref_per_pa` to better indicate the relationship between these variables.
-
-We can modify variable names, units, longnames, and even scale variables using the `-edit` function in `MarsVars.py`. The syntax for editing the variable name is:
-
-```bash
-(amesCAP)~$ MarsVars.py 03340.atmos_average.nc -edit opac -rename dustref_per_pa
-03340.atmos_average_tmp.nc was created
-03340.atmos_average.nc was updated
-```
-
-We can use `--inspect [-i]` again to confirm that `opac` was renamed `dustref_per_pa`:
-
-```bash
-(amesCAP)~$ MarsPlot.py -i 03340.atmos_average.nc
-```
-
-The `--inspect [-i]` function can also **print a summary of the values** of a variable to the screen. For example:
-
-```bash
-(amesCAP)~$ MarsPlot.py -i 03340.atmos_average.nc -stat dustref_per_pa
-_________________________________________________________
- VAR | MIN | MEAN | MAX |
-________________|___________|_____________|_____________|
- dustref_per_pa| 0| 0.000384902| 0.0017573|
-________________|___________|_____________|_____________|
-```
-
-Finally, `--inspect [-i]` can **print the values** of a variable to the screen. For example:
-
-```bash
-(amesCAP)~$ MarsPlot.py -i 03340.atmos_average.nc -dump lat
-lat=
-[-89. -87. -85. -83. -81. -79. -77. -75. -73. -71. -69. -67. -65. -63.
- -61. -59. -57. -55. -53. -51. -49. -47. -45. -43. -41. -39. -37. -35.
- -33. -31. -29. -27. -25. -23. -21. -19. -17. -15. -13. -11. -9. -7.
- -5. -3. -1. 1. 3. 5. 7. 9. 11. 13. 15. 17. 19. 21.
- 1. 25. 27. 29. 31. 33. 35. 37. 39. 41. 43. 45. 47. 49.
- 2. 53. 55. 57. 59. 61. 63. 65. 67. 69. 71. 73. 75. 77.
- 3. 81. 83. 85. 87. 89.]
-```
-
-*[Return to Part I](#part-i-file-manipulations)*
-
-***
-
-## 3. Splitting Files in Time
-
-Next we're going to trim the `diurn` and `average` files by L$_s$. We'll create files that only contain data around southern summer solstice, L$_s$=270. This greatly reduces the file size to make our next post-processing steps more efficient.
-
-Syntax for trimming files by L$_s$ is:
-
-```bash
-(amesCAP)~$ MarsFiles.py 03340.atmos_diurn.nc -split 265 275
-...
-/home/centos/tutorial_files/cap_exercises/03847.atmos_diurn_Ls265_275.nc was created
-```
-
-```bash
-(amesCAP)~$ MarsFiles.py 03340.atmos_average.nc -split 265 275
-...
-/home/centos/tutorial_files/cap_exercises/03847.atmos_average_Ls265_275.nc was created
-```
-
-The trimmed files have the appendix `_Ls265_275.nc` and the simulation day has changed from `03340` to `03847` to reflect that the first day in the file has changed.
-
-For future steps, we need a `fixed` file with the same simulation day number as the files we just created, so make a copy of the `fixed` file and rename it:
-
-```bash
-(amesCAP)~$ cp 03340.fixed.nc 03847.fixed.nc
-```
-
-*[Return to Part I](#part-i-file-manipulations)*
-
-***
-
-## Break
-
-**Take 15 minutes** to stretch, ask questions, or let us know your thoughts on CAP so far!
-
-***
-
-## 4. Deriving Secondary Variables
-
-The `--add` function in `MarsVars.py` derives and adds secondary variables to MGCM output files provided that the variable(s) required for the derivation are already in the file. We will add the meridional mass streamfunction (`msf`) to the trimmed `average` file. To figure out what we need in order to do this, use the `--help [-h]` function on `MarsVars.py`:
-
-```bash
-(amesCAP)~$ MarsVars.py -h
-```
-
-The help function shows that streamfunction (`msf`) requires two things: that the meridional wind (`vcomp`) is in the `average` file, and that the `average` file is ***pressure-interpolated***.
-
-First, confirm that `vcomp` is in `03847.atmos_average_Ls265_275.nc` using `--inspect [-i]`:
-
-```python
-(amesCAP)~$ MarsPlot.py -i 03847.atmos_average_Ls265_275.nc
-...
-vcomp : ('time', 'pfull', 'lat', 'lon')= (3, 56, 90, 180), meridional wind [m/sec]
-```
-
-Second, pressure-interpolate the average file using `MarsInterp.py`. The call to `MarsInterp.py` requires:
-
-- The interpolation type (`--type [-t]`), we will use standard pressure coorindates (`pstd`)
-- The grid to interpolate to (`--level [-l]`), we will use the default pressure grid (`pstd_default`)
-
-> All interpolation types are listed in the `--help [-h]` documentation for `MarsInterp.py`. Additional grids are listed in `~/.amescap_profile`, which accepts user-input grids as well.
-
-We will also specify that only temperature (`temp`), winds (`ucomp` and `vcomp`), and surface pressure (`ps`) are to be included in this new file using `-include`. This will reduce the interpolated file size.
-
-Finally, add the `--grid [-g]` flag at the end of prompt to print out the standard pressure grid levels that we are interpolating to:
-
-```bash
-(amesCAP)~$ MarsInterp.py 03847.atmos_average_Ls265_275.nc -t pstd -l pstd_default -include temp ucomp vcomp ps -g
-1100.0 1050.0 1000.0 950.0 900.0 850.0 800.0 750.0 700.0 650.0 600.0 550.0 500.0 450.0 400.0 350.0 300.0 250.0 200.0 150.0 100.0 70.0 50.0 30.0 20.0 10.0 7.0 5.0 3.0 2.0 1.0 0.5 0.3 0.2 0.1 0.05
-```
-
-To perform the interpolation, simply omit the `--grid [-g]` flag:
-
-```bash
-(amesCAP)~$ MarsInterp.py 03847.atmos_average_Ls265_275.nc -t pstd -l pstd_default -include temp ucomp vcomp ps
-...
-/home/centos/tutorial_files/cap_exercises/03847.atmos_average_Ls265_275_pstd.nc was created
-```
-
-Now we have a pressure-interpolated `average` file with `vcomp` in it. We can derive and add `msf` to it using `MarsVars.py`:
-
-```bash
-(amesCAP)~$ MarsVars.py 03847.atmos_average_Ls265_275_pstd.nc -add msf
-Processing: msf...
-msf: Done
-```
-
-*[Return to Part I](#part-i-file-manipulations)*
-
-***
-
-## 5. Time-Shifting `Diurn` Files
-
-The `diurn` file is organized by time-of-day assuming ***universal*** time starting at the Martian prime meridian. The time-shift `--tshift [-t]` function interpolates the `diurn` file to ***uniform local*** time. This is especially useful when comparing MGCM output to satellite observations in fixed local time orbit.
-
-Time-shifting can only be done on files with a local time dimension (`time_of_day_24`, i.e. `diurn` files). By default, `MarsFiles.py` time shifts all of the data in the file to 24 uniform local times and this generates very large files. To reduce file size and processing time, we will time-shift the data only to the local times we are interested in: 3 AM and 3 PM.
-
-Time-shift the temperature (`temp`) and surface pressure (`ps`) in the trimmed `diurn` file to 3 AM / 3 PM local time like so:
-
-```bash
-(amesCAP)~$ MarsFiles.py 03847.atmos_diurn_Ls265_275.nc -t '3. 15.' -include temp ps
-...
-/home/centos/tutorial_files/cap_exercises/03847.atmos_diurn_Ls265_275_T.nc was created
-```
-
-A new `diurn` file called `03847.atmos_diurn_Ls265_275_T.nc` is created. Use `--inspect [-i]` to confirm that only `ps` and `temp` (and their dimensions) are in the file and that the `time_of_day` dimension has a length of 2:
-
-```python
-(amesCAP)~$ MarsPlot.py -i 03847.atmos_diurn_Ls265_275_T.nc
-...
-====================CONTENT==========================
-time : ('time',)= (3,), sol number [days since 0000-00-00 00:00:00]
-time_of_day_02 : ('time_of_day_02',)= (2,), time of day [[hours since 0000-00-00 00:00:00]]
-pfull : ('pfull',)= (56,), ref full pressure level [mb]
-scalar_axis : ('scalar_axis',)= (1,), none [none]
-lon : ('lon',)= (180,), longitude [degrees_E]
-lat : ('lat',)= (90,), latitude [degrees_N]
-areo : ('time', 'time_of_day_02', 'scalar_axis')= (3, 2, 1), areo [degrees]
-ps : ('time', 'time_of_day_02', 'lat', 'lon')= (3, 2, 90, 180), surface pressure [Pa]
-temp : ('time', 'time_of_day_02', 'pfull', 'lat', 'lon')= (3, 2, 56, 90, 180), temperature [K]
-=====================================================
-```
-
-*[Return to Part I](#part-i-file-manipulations)*
-
-***
-
-## 6. Pressure-Interpolating the Vertical Axis
-
-Now we can efficiently interpolate the `diurn` file to the standard pressure grid. Recall that interpolation is part of `MarsInterp.py` and requires:
-
-1. Interpolation type (`--type [-t]`), and
-2. Grid (`--level [-l]`)
-
-As before, we will interpolate to standard pressure (`pstd`) using the default pressure grid in `.amesgcm_profile` (`pstd_default`):
-
-```bash
-(amesCAP)~$ MarsInterp.py 03847.atmos_diurn_Ls265_275_T.nc -t pstd -l pstd_default
-...
-/home/centos/tutorial_files/cap_exercises/03847.atmos_diurn_Ls265_275_T_pstd.nc was created
-```
-
-> **Note:** Interpolation could be done before or after time-shifting, the order does not matter.
-
-We now have four different `diurn` files in our directory:
-
-```bash
-03340.atmos_diurn.nc # Original MGCM file
-03847.atmos_diurn_Ls265_275.nc # + Trimmed to Ls=265-275
-03847.atmos_diurn_Ls265_275_T.nc # + Time-shifted; `ps` and `temp` only
-03847.atmos_diurn_Ls265_275_T_pstd.nc # + Pressure-interpolated
-```
-
-CAP always adds an appendix to the name of any new file it creates. This helps users keep track of what was done and in what order. The last file we created was trimmed, time-shifted, then pressure-interpolated. However, the same file could be generated by performing the three functions in any order.
-
-*[Return to Part I](#part-i-file-manipulations)*
-
-# Optional: Use the Answer Key for Part I
-
-This concludes Part I of the tutorial! If you messed up one of the exercises somewhere, you can run the `part_1_key.sh` script in this directory. It will delete the files you've made and performs all 6 Exercises in Part I for you. To do this, follow the steps below.
-
-1. Source the `amesCAP` virtual environment
-2. Change to the `tutorial_files/cap_exercises/` directory
-3. Run the executable:
-
-```bash
-(amesCAP)~$ ./part_1_key.sh
-```
-
-The script will do all of Part I for you. This ensures you can follow along with the plotting routines in Part II.
-
-*[Return to Part I](#part-i-file-manipulations)*
-
-# CAP Practical Day 2
-
-This part of the CAP Practical covers how to generate plots with CAP. We will take a learn-by-doing approach, creating five sets of plots that demonstrate some of CAP's most often used plotting capabilities:
-
-1. [Custom Set 1 of 4: Zonal Mean Surface Plots Over Time](#custom-set-1-of-4-zonal-mean-surface-plots-over-time)
-2. [Custom Set 2 of 4: Global Mean Column-Integrated Dust Optical Depth Over Time](#custom-set-2-of-4-global-mean-column-integrated-dust-optical-depth-over-time)
-3. [Custom Set 3 of 4: 50 Pa Temperatures at 3 AM and 3 PM](#custom-set-3-of-4-50-pa-temperatures-at-3-am-and-3-pm)
-4. [Custom Set 4 of 4: Zonal Mean Circulation Cross-Sections](#custom-set-4-of-4-zonal-mean-circulation-cross-sections)
-
-Plotting with CAP is done in 3 steps:
-
-[Step 1: Creating the Template (`Custom.in`)](#step-1-creating-the-template-customin)
-
-[Step 2: Editing `Custom.in`](#step-2-editing-customin)
-
-[Step 3: Generating the Plots](#step-3-generating-the-plots)
-
-As in Part I, we will go through these steps together.
-
-# Part II: Plotting with CAP
-
-CAP's plotting routine is `MarsPlot.py`. It works by generating a `Custom.in` file containing seven different plot templates that users can modify, then reading the `Custom.in` file to make the plots.
-
-The plot templates in `Custom.in` include:
-
-| Plot Type | X, Y Dimensions | Name in `Custom.in`|
-| :--- | :--- |:--- |
-| Map | Longitude, Latitude |`Plot 2D lon x lat` |
-| Time-varying | Time, Latitude |`Plot 2D time x lat`|
-| Time-varying | Time, level |`Plot 2D time x lev`|
-| Time-varying | Longitude, Time |`Plot 2D lon x time`|
-| Cross-section | Longitude, Level |`Plot 2D lon x lev` |
-| Cross-section | Latitude, Level |`Plot 2D lat x lev` |
-| Line plot (1D)| Dimension*, Variable|`Plot 1D` |
-
-> *Dimension is user-indicated and could be time (`time`), latitude (`lat`), longitude `lon`, or level (`pfull`, `pstd`, `zstd`, `zagl`).
-
-Additionally, `MarsPlot.py` supports:
-
-- PDF & image format
-- Landscape & portrait mode
-- Multi-panel plots
-- Overplotting
-- Customizable axes dimensions and contour intervals
-- Adjustable colormaps and map projections
-
-and so much more. You will learn to plot with `MarsPlot.py` by following along with the demonstration. We will generate the `Custom.in` template file, customize it, and pass it back into `MarsPlot.py` to create plots.
-
-*[Return to Part II](#cap-practical-day-2)*
-
-***
-
-## Step 1: Creating the Template (`Custom.in`)
-
-Generate the template file, `Custom.in`:
-
-```bash
-(amesCAP)~$ MarsPlot.py -template
-/home/centos/tutorial_files/cap_exercises/Custom.in was created
-```
-
-A new file called `Custom.in` is created in your current working directory.
-
-***
-
-## Step 2: Editing `Custom.in`
-
-Open `Custom.in` using `vim`:
-
-```bash
-(amesCAP)~$ vim Custom.in
-```
-
-Scroll down until you see the first two templates shown in the image below:
-
-
-
-Since all of the templates have a similar structure, we can broadly describe how `Custom.in` works by going through the templates line-by-line.
-
-### Line 1
-
-``` python
-# Line 1 ┌ plot type ┌ whether to create the plot
-<<<<<<<<<<<<<<| Plot 2D lon X lat = True |>>>>>>>>>>>>>
-```
-
-Line 1 indicates the **plot type** and **whether to create the plot** when passed into `MarsPlot.py`.
-
-### Line 2
-
-``` python
-# Line 2 ┌ file ┌ variable
-Title = None
-```
-
-Line 2 is where we set the plot title.
-
-### Line 3
-
-``` python
-# Line 3 ┌ file ┌ variable
-Main Variable = fixed.zsurf # file.variable
-Main Variable = [fixed.zsurf]/1000 # [] brackets for mathematical operations
-Main Variable = diurn_T.temp{tod=3} # {} brackets for dimension selection
-```
-
-Line 3 indicates the **variable** to plot and the **file** from which to pull the variable.
-
-Additional customizations include:
-
-- Element-wise operations (e.g., scaling by a factor)
-- Dimensional selection (e.g., selecting the time of day (`tod`) at which to plot from a time-shifted diurn file)
-
-### Line 4
-
-``` python
-# Line 4
-Cmin, Cmax = None # automatic, or
-Cmin, Cmax = -4,5 # contour limits, or
-Cmin, Cmax = -4,-2,0,1,3,5 # explicit contour levels
-```
-
-Line 4 line defines the **color-filled contours** for `Main Variable`. Valid inputs are:
-
-- `None` (default) enables Python's automatic interpretation of the contours
-- `min,max` specifies contour range
-- `X,Y,Z,...,N` gives explicit contour levels
-
-### Lines 5 & 6
-
-```python
-# Lines 5 & 6
-Ls 0-360 = None # for 'time' free dimension
-Level Pa/m = None # for 'pstd' free dimension
-```
-
-Lines 5 & 6 handle the **free dimension(s)** for `Main Variable` (the dimensions that are ***not*** plot dimensions).
-
-For example, `temperature` has four dimensions: `(time, pstd, lat, lon)`. For a `2D lon X lat` map of temperature, `lon` and `lat` provide the `x` and `y` dimensions of the plot. The free dimensions are then `pstd` (`Level Pa/m`) and `time` (`Ls 0-360`).
-
-Lines 5 & 6 accept four input types:
-
-1. `integer` selects the closest value
-2. `min,max` averages over a range of the dimension
-3. `all` averages over the entire dimension
-4. `None` (default) depends on the free dimension:
-
-```python
-# ┌ free dimension ┌ default setting
-Ls 0-360 = None # most recent timestep
-Level Pa/m = None # surface level
-Lon +/-180 = None # zonal mean over all longitudes
-Latitude = None # equatorial values only
-```
-
-### Lines 7 & 8
-
-``` python
-# Line 7 & 8
-2nd Variable = None # no solid contours
-2nd Variable = fixed.zsurf # draw solid contours
-Contours Var 2 = -4,5 # contour range, or
-Contours Var 2 = -4,-2,0,1,3,5 # explicit contour levels
-```
-
-Lines 7 & 8 (optional) define the **solid contours** on the plot. Contours can be drawn for `Main Variable` or a different `2nd Variable`.
-
-- Like `Main Variable`, `2nd Variable` minimally requires `file.variable`
-- Like `Cmin, Cmax`, `Contours Var 2` accepts a range (`min,max`) or list of explicit contour levels (`X,Y,Z,...,N`)
-
-### Line 9
-
-```python
-# Line 9 ┌ X axes limit ┌ Y axes limit ┌ colormap ┌ cmap scale ┌ projection
- Axis Options : lon = [None,None] | lat = [None,None] | cmap = jet | scale = lin | proj = cart
- ```
-
-Finally, Line 9 offers plot customization (e.g., axes limits, colormaps, map projections, linestyles, 1D axes labels).
-
-*[Return to Part II](#cap-practical-day-2)*
-
-***
-
-## Step 3: Generating the Plots
-
-Generate the plots set to `True` in `Custom.in` by saving and quitting the editor (`:wq`) and then passing the template file to `MarsPlot.py`. The first time we do this, we'll pass the `--date [-d]` flag to specify that we want to plot from the `03340` `average` and `fixed` files:
-
-```bash
-(amesCAP)~$ MarsPlot.py Custom.in -d 03340
-```
-
-Plots are created and saved in a file called `Diagnostics.pdf`.
-
-
-
-### Viewing Diagnostics.pdf
-
-To open the file, we need to copy it to our local computer. We'll create an alias for the command that does this so we can easily pull `Diagnostics.pdf` from the cloud environment.
-
-First, open a new terminal tab (`CRTL-t`).
-
-Then, change to the directory hosting your token for this tutorial (the token is the file ending in `.pem`).
-
-Finally, build the secure copy (`scp`) command OR use `sftp`.
-
-#### Using `scp`(recommended)
-
-To build your `scp` command:
-- The name of your `.pem` file (e.g., `mars-clusterXX.pem`)
-- The address you used to login to the cloud (something like `centos@YOUR_IP_ADDRESS`)
-- The path to the PDF in the cloud: `tutorial_files/cap_exercises/Diagnostics.pdf`
-
-Putting these together, the secure copy command is:
-
-```bash
-(local)~$ scp -i "mars-clusterXX.pem" centos@YOUR_IP_ADDRESS:tutorial_files/cap_exercises/Diagnostics.pdf .
-```
-
-To make the command into an alias named `getpdf`:
-
-```bash
-(local)~$ alias getpdf='scp -i "mars-clusterXX.pem" centos@YOUR_IP_ADDRESS:tutorial_files/cap_exercises/Diagnostics.pdf .'
-```
-
-Now we can pull the PDF to our local computer with one simple command:
-
-```bash
-(local)~$ getpdf # uses scp
-```
-
-#### Using `sftp`
-
-Alternatively, if `scp` isn't working for you, you can use `sftp`. To do this, go to your new terminal tab and type:
-
-```bash
-(local)~$ sftp -i "mars-clusterXX.pem" centos@YOUR_IP_ADDRESS
-sftp> cd tutorial_files/cap_exercises
-```
-
-Then when you want to pull the PDF to your local computer, type:
-
-```bash
-sftp> get Diagnostics.pdf
-```
-
-
-***
-
-### Summary
-
-Plotting with `MarsPlot.py` is done in 3 steps:
-
-```bash
-(amesCAP)~$ MarsPlot.py -template # generate Custom.in
-(amesCAP)~$ vim Custom.in # edit Custom.in
-(amesCAP)~$ MarsPlot.py Custom.in # pass Custom.in back to MarsPlot
-```
-
-Now we will go through some examples.
-
-***
-
-## Customizing the Plots
-
-Open `Custom.in` in the editor:
-
-```bash
-(amesCAP)~$ vim Custom.in
-```
-
-Copy the first two templates that are set to `True` and paste them below the line `Empty Templates (set to False)`. Then, set them to `False`. This way, we have all available templates saved at the bottom of the script.
-
-We'll preserve the first two plots, but let's define the sol number of the average and fixed files in the template itself so we don't have to pass the `--date [-d]` argument every time:
-
-```python
-# for the first plot (lon X lat topography):
-Main Variable = 03340.fixed.zsurf
-# for the second plot (lat X lev zonal wind):
-Main Variable = 03340.atmos_average.ucomp
-```
-
-Now we can omit the date (`--date [-d]`) when we pass `Custom.in` to `MarsPlot.py`.
-
-### Custom Set 1 of 4: Zonal Mean Surface Plots Over Time
-
-The first set of plots we'll make are zonal mean surface fields over time: surface temperature, CO$_2$ ice, and wind stress.
-
-
-
-For each of the plots, source variables from the *non*-interpolated average file, `03340.atmos_average.nc`.
-
-For the **surface temperature** plot:
-
-- Copy/paste the `Plot 2D time X lat` template above the `Empty Templates` line
-- Set it to `True`
-- Edit the title to `Zonal Mean Sfc T [K]`
-- Set `Main Variable = 03340.atmos_average.ts`
-- Edit the colorbar range: `Cmin, Cmax = 140,270` → *140-270 Kelvin*
-- Set `2nd Variable = 03340.atmos_average.ts` → *for overplotted solid contours*
-- Explicitly define the solid contours: `Contours Var 2 = 160,180,200,220,240,260`
-
-Let's pause here and pass the `Custom.in` file to `MarsPlot.py`.
-
-Type `ESC-:wq` to save and close the file. Then, pass it to `MarsPlot.py`:
-
-```bash
-(amesCAP)~$ MarsPlot.py Custom.in
-```
-
-Now, go to your **local terminal** tab and retrieve the PDF:
-
-```bash
-(local)~$ getpdf # uses scp
-```
-
-or
-
-```bash
-sftp> get Diagnostics.pdf # uses sftp
-```
-
-Now we can open it and view our plot.
-
-Go back to the **cloud environment** tab to finish generating the other plots on this page. Open `Custom.in` in `vim`:
-
-```bash
-(amesCAP)~$ vim Custom.in
-```
-
-Write a set of `HOLD ON` and `HOLD OFF` arguments around the surface temperature plot. We will paste the other templates within these arguments to tell `MarsPlot.py` to put these plots on the same page.
-
-Copy/paste the `Plot 2D time X lat` template plot twice more. Make sure to set the boolean to `True`.
-
-For the **surface CO$_2$ ice** plot:
-
-- Set the title to `Zonal Mean Sfc CO2 Ice [kg/m2]`
-- Set `Main Variable = 03340.atmos_average.co2ice_sfc`
-- Edit the colorbar range: `Cmin, Cmax = 0,800` → *0-800 kg/m$^2$*
-- Set `2nd Variable = 03340.atmos_average.co2ice_sfc` → *solid contours*
-- Explicitly define the solid contours: `Contours Var 2 = 200,400,600,800`
-- Change the colormap on the `Axis Options` line: `cmap = plasma`
-
-For the **surface wind stress** plot:
-
-- Set the title to `Zonal Mean Sfc Stress [N/m2]`
-- Set `Main Variable = 03340.atmos_average.stress`
-- Edit the colorbar range: `Cmin, Cmax = 0,0.03` → *0-0.03 N/m$^2$*
-
-Save and quit the editor (`ESC-:wq`) and pass `Custom.in` to `MarsPlot.py`:
-
-```bash
-(amesCAP)~$ MarsPlot.py Custom.in
-```
-
-In your **local terminal** tab, retrieve the PDF to view the plots:
-
-```bash
-(local)~$ getpdf # uses scp
-```
-
-or
-
-```bash
-sftp> get Diagnostics.pdf # uses sftp
-```
-
-*[Return to Part II](#cap-practical-day-2)*
-
-***
-
-### Custom Set 2 of 4: Global Mean Column-Integrated Dust Optical Depth Over Time
-
-Now we'll generate a 1D plot and practice plotting multiple lines on it.
-
-
-
-Let's start by setting up our 1D plot template:
-
-- Write a new set of `HOLD ON` and `HOLD OFF` arguments.
-- Copy/paste the `Plot 1D` template between them.
-- Set the template to `True`.
-
-Create the **visible dust optical depth** plot first:
-
-- Set the title: `Area-Weighted Global Mean Dust OD (norm.) [op]`
-- Edit the legend: `Visible`
-
-The input to `Main Variable` is not so straightforward this time. We want to plot the *normalized* dust optical depth, which is dervied as follows:
-
-```
-normalized_dust_OD = opacity / surface_pressure * reference_pressure
-```
-
-The MGCM outputs column-integrated visible dust opacity to the variable `taudust_VIS`, surface pressure is saved as `ps`, and we'll use a reference pressure of 610 Pa. Recall that element-wise operations are performed when square brackets `[]` are placed around the variable in `Main Variable`. Putting all that together, `Main Variable` is:
-
-```python
-# ┌ norm. OD ┌ opacity ┌ surface pressure ┌ ref. P
-Main Variable = [03340.atmos_average.taudust_VIS]/[03340.atmos_average.ps]*610
-```
-
-To finish up this plot, tell `MarsPlot.py` what to do to the dimensions of `taudust_VIS (time, lon, lat)`:
-
-- Leave `Ls 0-360 = AXIS` to use 'time' as the X axis dimension.
-- Set `Latitude = all` → *average over all latitudes*
-- Set `Lon +/-180 = all` → *average over all longitudes*
-- Set the Y axis label under `Axis Options`: `axlabel = Optical Depth`
-
-The **infrared dust optical depth** plot is identical to the visible dust OD plot except for the variable being plotted, so duplicate the **visible** plot we just created. Make sure both templates are between `HOLD ON` and `HOLD OFF` Then, change two things:
-
-- Change `Main Variable` from `taudust_VIS` to `taudust_IR`
-- Set the legend to reflect the new variable (`Legend = Infrared`)
-
-Save and quit the editor (`ESC-:wq`). pass `Custom.in` to `MarsPlot.py`:
-
-```bash
-(amesCAP)~$ MarsPlot.py Custom.in
-```
-
-In your **local terminal** tab, retrieve the PDF to view the plots:
-
-```bash
-(local)~$ getpdf # uses scp
-```
-
-or
-
-```bash
-sftp> get Diagnostics.pdf # uses sftp
-```
-
-Notice we have two separate 1D plots on the same page. This is because of the `HOLD ON` and `HOLD OFF` arguments. Without those, these two plots would be on separate pages. But how do we overplot the lines on top of one another?
-
-Go back to the cloud environment, open `Custom.in`, and type `ADD LINE` between the two 1D templates.
-
-Save and quit again, pass it through `MarsPlot.py`, and retrieve the PDF locally. Now we have the overplotted lines we were looking for.
-
-*[Return to Part II](#cap-practical-day-2)*
-
-***
-
-## Break
-
-**Take 15 minutes** to stretch, ask questions, or let us know your thoughts on CAP so far!
-
-***
-
-### Custom Set 3 of 4: 50 Pa Temperatures at 3 AM and 3 PM
-
-The first two plots are 3 AM and 3 PM 50 Pa temperatures at L$_s$=270. Below is the 3 PM - 3 AM difference.
-
-
-
-We'll generate all three plots before passing `Custom.in` to `MarsPlot.py`, so copy/paste the `Plot 2D lon X lat` template ***three times*** between a set of `HOLD ON` and `HOLD OFF` arguments and set them to `True`.
-
-For the first plot,
-
-- Title it for 3 AM temperatures: `3 AM 50 Pa Temperatures [K] @ Ls=270`
-- Set `Main Variable` to `temp` and select 3 AM for the time of day using curly brackets:
-
-```python
-Main Variable = 03847.atmos_diurn_Ls265_275_T_pstd.temp{tod=3}
-```
-
-- Set the colorbar range: `Cmin, Cmax = 145,290` → *145-290 K*
-- Set `Ls 0-360 = 270` → *southern summer solstice*
-- Set `Level Pa/m = 50` → *selects 50 Pa temperatures*
-- Set `2nd Variable` to be identical to `Main Variable`
-
-Now, edit the second template for 3 PM temperatures the same way. The only differences are the:
-
-- Title: edit to reflect 3 PM temperatures
-- Time of day selection: for 3 PM, `{tod=15}` ***change this for `2nd Variable` too!***
-
-For the **difference plot**, we will need to use square brackets in the input for `Main Variable` in order to subtract 3 AM temperatures from 3 PM temperatures. We'll also use a diverging colorbar to show temperature differences better.
-
-- Set the title to `3 PM - 3 AM Temperature [K] @ Ls=270`
-- Build `Main Variable` by subtracting the 3 AM `Main Variable` input from the 3 PM `Main variable` input:
-
-```python
-Main Variable = [03847.atmos_diurn_Ls265_275_T_pstd.temp{tod=15}]-[03847.atmos_diurn_Ls265_275_T_pstd.temp{tod=3}]
-```
-
-- Center the colorbar at `0` by setting `Cmin, Cmax = -20,20`
-- Like the first two plots, set `Ls 0-360 = 270` → *southern summer solstice*
-- Like the first two plots, set `Level Pa/m = 50` → *selects 50 Pa temperatures*
-- Select a diverging colormap in `Axis Options`: `cmap = RdBu_r`
-
-Save and quit the editor (`ESC-:wq`). pass `Custom.in` to `MarsPlot.py`, and pull it to your local computer:
-
-```bash
-(amesCAP)~$ MarsPlot.py Custom.in
-# switch to the local terminal...
-(local)~$ getpdf # uses scp
-```
-
-or
-
-```bash
-sftp> get Diagnostics.pdf # uses sftp
-```
-
-*[Return to Part II](#cap-practical-day-2)*
-
-***
-
-### Custom Set 4 of 4: Zonal Mean Circulation Cross-Sections
-
-For our final set of plots, we will generate four cross-section plots showing temperature, zonal (U) and meridional (V) winds, and mass streamfunction at L$_s$=270.
-
-
-
-Begin with the usual 3-step process:
-
-1. Write a set of `HOLD ON` and `HOLD OFF` arguments
-2. Copy-paste the `Plot 2D lat X lev` template between them
-3. Set the template to `True`
-
-Since all four plots are going to have the same X and Y axis ranges and `time` selection, let's edit this template before copying it three more times:
-
-- Set `Ls 0-360 = 270`
-- In `Axis Options`, set `Lat = [-90,90]`
-- In `Axis Options`, set `level[Pa/m] = [1000,0.05]`
-
-Now copy/paste this template three more times. Let the first plot be temperature, the second be mass streamfunction, the third be zonal wind, and the fourth be meridional wind.
-
-For **temperature**:
-
-```python
-Title = Temperature [K] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.temp
-Cmin, Cmax = 110,240
-...
-2nd Variable = 03847.atmos_average_Ls265_275_pstd.temp
-```
-
-For **streamfunction**, define explicit solid contours under `Contours Var 2` and set a diverging colormap.
-
-```python
-Title = Mass Stream Function [1.e8 kg s-1] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.msf
-Cmin, Cmax = -110,110
-...
-2nd Variable = 03847.atmos_average_Ls265_275_pstd.msf
-Contours Var 2 = -5,-3,-1,-0.5,1,3,5,10,20,40,60,100,120
-# set cmap = bwr in Axis Options
-```
-
-For **zonal** and **meridional** wind, use the dual-toned colormap `PiYG`.
-
-```python
-Title = Zonal Wind [m/s] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.ucomp
-Cmin, Cmax = -230,230
-...
-2nd Variable = 03847.atmos_average_Ls265_275_pstd.ucomp
-# set cmap = PiYG in Axis Options
-```
-Title = Zonal Wind [m/s] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.ucomp
-Cmin, Cmax = -230,230
-...
-2nd Variable = 03847.atmos_average_Ls265_275_pstd.ucomp
-# set cmap = PiYG in Axis Options
-```
-
-```python
-Title = Meridional Wind [m/s] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.vcomp
-Cmin, Cmax = -85,85
-...
-2nd Variable = 03847.atmos_average_Ls265_275_pstd.vcomp
-# set cmap = PiYG in Axis Options
-```
-
-Save and quit the editor (`ESC-:wq`). pass `Custom.in` to `MarsPlot.py`, and pull it to your local computer:
-
-```bash
-(amesCAP)~$ MarsPlot.py Custom.in
-# switch to the local terminal...
-(local)~$ getpdf # uses scp
-```
-
-or
-
-```bash
-sftp> get Diagnostics.pdf # uses sftp
-```
-
-*[Return to Part II](#cap-practical-day-2)*
-
-***
-
-### End Credits
-
-This concludes the practical exercise portion of the CAP tutorial. Please feel free to use these exercises as a reference when using CAP the future!
-
-*Written by Courtney Batterson, Alex Kling, and Victoria Hartwick. This document was created for the NASA Ames MGCM and CAP Tutorial held virtually November 13-15, 2023.*
-
-*Questions, comments, or general feedback? [Contact us](https://forms.gle/2VGnVRrvHDzoL6Y47)*.
-
-*[Return to Top](#table-of-contents)*
diff --git a/tutorial/CAP_Exercises.pdf b/tutorial/CAP_Exercises.pdf
deleted file mode 100644
index 8854ef4c..00000000
Binary files a/tutorial/CAP_Exercises.pdf and /dev/null differ
diff --git a/tutorial/CAP_Exercises_2021.md b/tutorial/CAP_Exercises_2021.md
deleted file mode 100644
index 8d4d4a40..00000000
--- a/tutorial/CAP_Exercises_2021.md
+++ /dev/null
@@ -1,1058 +0,0 @@
-
-
-
-## Table of Contents
-* [Practical: The Community Analysis Pipeline (CAP)](#practical-the-community-analysis-pipeline-cap)
- * [Begin by Activating CAP](#begin-by-activating-cap)
- * [1. Retrieving Data](#1-retrieving-data)
- * [1.1 Download MGCM Output with `MarsPull.py`](#11-download-mgcm-output-with-marspullpy)
- * [2. File Manipulations](#2-file-manipulations)
- * [2.1 Convert the `fort.11` files into `netCDF` files](#21-convert-the-fort11-files-into-netcdf-files)
- * [2.2 Interpolate `atmos_average` to standard pressure coordinates](#22-interpolate-atmosaverage-to-standard-pressure-coordinates)
- * [2.3 Add mass stream function (`msf`) to the pressure-interpolated file](#23-add-mass-stream-function-msf-to-the-pressure-interpolated-file)
- * [2.4 Add density (`rho`) and mid-point altitude (`zfull`) to `atmos_average`](#24-add-density-rho-and-mid-point-altitude-zfull-to-atmosaverage)
- * [2.5 Interpolate `atmos_average` to standard altitude](#25-interpolate-atmosaverage-to-standard-altitude)
- * [2.6 Time-shift and pressure-interpolate the `diurn` file](#26-time-shift-and-pressure-interpolate-the-diurn-file)
- * [2.7 Apply a low-pass filter (`-lpf`) to the surface pressure (`ps`) and temperature (`ts`) in the `daily` file](#27-apply-a-low-pass-filter--lpf-to-the-surface-pressure-ps-and-temperature-ts-in-the-daily-file)
- * [2.8 Estimate the magnitude of the wind shear using CAP](#28-estimate-the-magnitude-of-the-wind-shear-using-cap)
- * [2.9 Calculate the column-integrated dust, water ice, and water vapor mixing ratios in the `daily` file](#29-calculate-the-column-integrated-dust-water-ice-and-water-vapor-mixing-ratios-in-the-daily-file)
- * [2.10 Display the values of `pfull`, then display the minimum, mean, and maximum near-surface temperatures `temp` over the globe](#210-display-the-values-of-pfull-then-display-the-minimum-mean-and-maximum-near-surface-temperatures-temp-over-the-globe)
- * [2.1b (for `/ACTIVECLDS`) Convert `fort.11` files into `netCDF` files](#21b-for-activeclds-convert-fort11-files-into-netcdf-files)
- * [2.2b (for `/ACTIVECLDS`) Interpolate `atmos_average` to standard pressure](#22b-for-activeclds-interpolate-atmosaverage-to-standard-pressure)
- * [2.5b (for `/ACTIVECLDS`) Interpolate `atmos_average` to standard altitude](#25b-for-activeclds-interpolate-atmosaverage-to-standard-altitude)
-* [Optional: Download the Answer Key for Step 2](#optional-download-the-answer-key-for-step-2)
-* [Break](#break)
- * [3. Plotting Routines](#3-plotting-routines)
- * [3.1 Create a global map of surface albedo (`alb`) with topography (`zsurf`) contoured on top](#31-create-a-global-map-of-surface-albedo-alb-with-topography-zsurf-contoured-on-top)
- * [3.2 Plot the zonal mean zonal wind cross-section at Ls=270° using altitude as the vertical coordinate](#32-plot-the-zonal-mean-zonal-wind-cross-section-at-ls270-using-altitude-as-the-vertical-coordinate)
- * [3.3 Add the same plot for the RAC case to the same page](#33-add-the-same-plot-for-the-rac-case-to-the-same-page)
- * [3.4 Overplot temperature in solid contours](#34-overplot-temperature-in-solid-contours)
- * [3.5 Plot the surface CO2 ice content in g/m2 and compute and plot surface wind speed from the U and V winds](#35-plot-the-surface-co2-ice-content-in-gm2-and-compute-and-plot-surface-wind-speed-from-the-u-and-v-winds)
- * [3.6 Make the following changes to the plots you created in 3.5](#36-make-the-following-changes-to-the-plots-you-created-in-35)
- * [3.7 Create the following zonal mean `time X lat` plots on a new page](#37-create-the-following-zonal-mean-time-x-lat-plots-on-a-new-page)
- * [3.8 Plot the following two cross-sections (`lat X lev`) on the same page](#38-plot-the-following-two-cross-sections-lat-x-lev-on-the-same-page)
- * [3.9 Plot zonal mean temperature from the RIC and RAC cases](#39-plot-zonal-mean-temperature-from-the-ric-and-rac-cases)
- * [3.10 Generate two 1D temperature profiles (`temp`) from the RIC case](#310-generate-two-1d-temperature-profiles-temp-from-the-ric-case)
- * [**NOTE:** You do not use `HOLD ON` and `HOLD OFF` to overplot 1D plots. `HOLD` is always for drawing separate plots on the same page](#note-you-do-not-use-hold-on-and-hold-off-to-overplot-1d-plots-hold-is-always-for-drawing-separate-plots-on-the-same-page)
- * [3.11 Plot the 1D filtered and unfiltered surface pressure over a 20-sol period](#311-plot-the-1d-filtered-and-unfiltered-surface-pressure-over-a-20-sol-period)
- * [That's a Wrap](#thats-a-wrap)
-
-
-***
-
-# Practical: The Community Analysis Pipeline (CAP)
-
-**Recap:** CAP is a Python toolkit designed to simplify post-processing and plotting MGCM output. CAP consists of five Python executables:
-
-1. `MarsPull.py` for accessing MGCM output
-2. `MarsFiles.py` for reducing the files
-3. `MarsVars.py` for performing variable operations
-4. `MarsInterp.py` for interpolating the vertical grid
-5. `MarsPlot.py` for visualizing the MGCM output
-
-It is useful to divide these functions into three categories and explore them in order:
-
-1. [Retrieving Data](#1-retrieving-data) -> `MarsPull.py`
-2. [File Manipulations](#2-file-manipulations) -> `MarsFiles.py`, `MarsVars.py`, & `MarsInterp.py`
-3. [Plotting Routines](#3-plotting-routines) -> `MarsPlot.py`
-
-You already have experience using `MarsPull.py` for retrieving data, which was covered at the end of [CAP_Install.md](https://github.com/NASA-Planetary-Science/AmesCAP/blob/master/tutorial/CAP_Install.md). We will build on that knowledge in this tutorial. You may revisit the installation instructions at any time during the tutorial.
-
-## Begin by Activating CAP
-
-As always with CAP, you must activate the `amesCAP` virtual environment to access the Python executables:
-
-```bash
-(local)>$ source ~/amesCAP/bin/activate # bash
-(local)>$ source ~/amesCAP/bin/activate.csh # csh/tcsh
-# ................... OR ...................
-(local)>$ source ~/amesCAP/Scripts/activate # Windows
-```
-
-Your prompt should change to confirm you're in the virtual environment. Before continuing, make sure you're using the most up-to-date version of CAP by running:
-
-```bash
-(AmesCAP)>$ pip install git+https://github.com/NASA-Planetary-Science/AmesCAP.git --upgrade
-```
-
-Then, confirm that CAP's executables are accessible by typing:
-
-```bash
-(AmesCAP)>$ MarsPull.py -h
-```
-
-This is the `--help` argument, which shows the documentation for any of the `Mars*.py` executables.
-
-Let's begin with a review of the data retrieval process you performed when installing CAP ([CAP_Install.md](https://github.com/NASA-Planetary-Science/AmesCAP/blob/master-dev/tutorial/CAP_Install.md)).
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-## 1. Retrieving Data
-
-### 1.1 Download MGCM Output with `MarsPull.py`
-
-
-`MarsPull` is used to access and download MGCM output files from the [MCMC Data portal](https://data.nas.nasa.gov/legacygcm/data_legacygcm.php).
-
-
-Choose a directory in which to store these MGCM output files on your machine (we will name it `CAP_tutorial`). We will also create two sub- directories, one named `INERTCLDS` for an MGCM simulation with radiatively inert clouds (RIC) and one named `ACTIVECLDS` for an MGCM simulation with radiatively active clouds (RAC):
-
-```bash
-(AmesCAP)>$ mkdir CAP_tutorial
-(AmesCAP)>$ cd CAP_tutorial
-(AmesCAP)>$ mkdir INERTCLDS ACTIVECLDS
-```
-
-Then, download the corresponding `fort.11` with solar longitudes spanning from Ls 255° to 285° in each directory using `MarsPull`:
-
-```bash
-(AmesCAP)>$ cd INERTCLDS
-(AmesCAP)>$ MarsPull.py -id INERTCLDS -ls 255 285
-(AmesCAP)>$ cd ../ACTIVECLDS
-(AmesCAP)>$ MarsPull.py -id ACTIVECLDS -ls 255 285
-```
-
-You should have the following 5 `fort.11` files in each directory:
-
-```
-CAP_tutorial/
-├── INERTCLDS/
-│ └── fort.11_0719 fort.11_0720 fort.11_0721 fort.11_0722 fort.11_0723
-└── ACTIVECLDS/
- └── fort.11_0719 fort.11_0720 fort.11_0721 fort.11_0722 fort.11_0723
-```
-
-Finally, check for files integrity using the `disk use` command:
-
-```bash
-cd ..
-du -h INERTCLDS/fort.11*
-du -h ACTIVECLDS/fort.11*
-> 433M fort.11_0719
-[...]
-```
-
-The files should be 433Mb each.
-
-> If you encounter an issue during the download process or if the files are not 433Mb, please verify the files availability on [the MCMC Data Portal](https://data.nas.nasa.gov/legacygcm/data_legacygcm.php) and try again later. You can re-attempt to download specific files as follows: `MarsPull.py -id ACTIVECLDS -f fort.11_0720 fort.11_0723` (make sure to navigate to the appropriate simulation directory first on your computer), or simply download the 10 files listed above manually from the website.
-
-***
-
-
-If you have any `fort.11` files **other than the ones listed above** in **either** directory, we recommend you **delete** them before processing to the rest of the exercises to stay consistent with the command-line instructions.
-
-[(Return to Top)](#table-of-contents)
-
-***
-## 2. File Manipulations
-
-We've retrieved the `fort.11` files from the data portal and we can now begin processing the data.
-
-CAP's post-processing capabilities include interpolating and regridding data to different vertical coordinate systems, adding derived variables to the files, and converting between filetypes, just to name a few examples.
-
-The following exercises are designed to demonstrate how CAP can be used for post-processing MGCM output. Please follow along with the demonstration. **We will use the files created here to make plots with `MarsPlot` later, so do *not* delete anything!**
-
-Begin in the `/INERTCLDS` directory and complete exercises 2.1-2.10:
-
-```bash
-(AmesCAP)>$ cd ~/CAP_tutorial/INERTCLDS
-```
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 2.1 Convert the `fort.11` files into `netCDF` files
-
-In the `/INERTCLDS` directory, type:
-
-```bash
-(AmesCAP)>$ MarsFiles.py fort.11_* -fv3 fixed average daily diurn
-```
-
-Several `netCDF` files were created from the `fort.11` files:
-
-```bash
-(AmesCAP)>$ ls
-> 07180.atmos_average.nc 07190.atmos_average.nc 07200.atmos_average.nc 07210.atmos_average.nc 07220.atmos_average.nc
-> 07180.atmos_daily.nc 07190.atmos_daily.nc 07200.atmos_daily.nc 07210.atmos_daily.nc 07220.atmos_daily.nc
-> 07180.atmos_diurn.nc 07190.atmos_diurn.nc 07200.atmos_diurn.nc 07210.atmos_diurn.nc 07220.atmos_diurn.nc
-> 07180.fixed.nc 07190.fixed.nc 07200.fixed.nc 07210.fixed.nc 07220.fixed.nc
-```
-
-Remember, the `netCDF` filetypes are:
-
-| Type | Description |
-| --------------------- | ----------- |
-| `*atmos_fixed.nc` | static variables that **do not change over time** |
-| `*atmos_average.nc` | **5-day averages** of MGCM output |
-| `*atmos_diurn.nc` | files contain **hourly** MGCM output averaged over 5 days |
-| `*atmos_daily.nc` | **continuous time series** of the MGCM output |
-
-> **NOTE:** the 5-digit sol number at the begining of each `netCDF` file indicates when the file's records begin. These files are pulled from a simulation that was warm-started from a 10 year run. `10 years x ~668 sols/year = 6680 sols`. The earliest date on these files is 07180 (the middle of the year).
-
-For easier post-processing and plotting, concatenate like-filetypes along the `time` axis:
-
-```bash
-(AmesCAP)>$ MarsFiles.py *fixed.nc -c
-(AmesCAP)>$ MarsFiles.py *average.nc -c
-(AmesCAP)>$ MarsFiles.py *diurn.nc -c
-(AmesCAP)>$ MarsFiles.py *daily.nc -c
-```
-
-Our directory now contains **four** `netCDF` files in addition to the `fort.11` files:
-
-```bash
-(AmesCAP)>$ ls
-> 07180.atmos_fixed.nc fort.11_0719 fort.11_0723
-> 07180.atmos_average.nc fort.11_0720
-> 07180.atmos_diurn.nc fort.11_0721
-> 07180.atmos_daily.nc fort.11_0722
-```
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 2.2 Interpolate `atmos_average` to standard pressure coordinates
-
-This step uses `MarsInterp`, and the documentation can be viewed using the `--help` argument:
-
-```bash
-(AmesCAP)>$ MarsInterp.py -h
-```
-
-Use the `--type` (`-t`) argument to interpolate the file to standard pressure coordinates (`pstd`):
-
-```bash
-(AmesCAP)>$ MarsInterp.py 07180.atmos_average.nc -t pstd
-```
-
-A new pressure-interpolated file called `07180.atmos_average_pstd.nc` was created and the original file was preserved.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 2.3 Add mass stream function (`msf`) to the pressure-interpolated file
-
-This step uses `MarsVars`, and the documentation can be viewed using the `--help` argument:
-
-```bash
-(AmesCAP)>$ MarsVars.py -h
-```
-
-Adding or removing variables from files is done using the `-add` and `-rem` arguments in the call to `MarsVars`. `msf` is a variable derived from the meridional wind (`vcomp`), so we must first confirm that `vcomp` is indeed a variable in `07180.atmos_average_pstd.nc` by using the `MarsPlot.py --inspect (-i)` command to list the variables in the file:
-
-```python
-(AmesCAP)>$ MarsPlot.py -i 07180.atmos_average_pstd.nc
-
-> ===================DIMENSIONS==========================
-> ['lat', 'lon', 'phalf', 'time', 'pstd']
-> .. (etc) ..
-> ====================CONTENT==========================
-> .. (etc) ..
-> vcomp : ('time', 'pstd', 'lat', 'lon')= (10, 36, 36, 60), meridional wind [m/s]
-> .. (etc) ..
-> Ls ranging from 255.42 to 284.19: 45.00 days
-> (MY 01) (MY 01)
-> =====================================================
-```
-
-We can see that `vcomp` is a variable in the file and therefore `msf` can be derived and added:
-
-```bash
-(AmesCAP)>$ MarsVars.py 07180.atmos_average_pstd.nc -add msf
-```
-
-> **Note:** `msf` should not be added before pressure-interpolating the file because it is derived on pressure coordinates.
-
-**`MarsPlot.py -i` works on any netCDF file, not just the ones created with CAP!**
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 2.4 Add density (`rho`) and mid-point altitude (`zfull`) to `atmos_average`
-
-This step also uses the `-add` function from `MarsVars`:
-
-```bash
-(AmesCAP)>$ MarsVars.py 07180.atmos_average.nc -add rho zfull
-```
-
-Density (`rho`) is derived from pressure (`pfull`) and temperature (`temp`), and mid-point altitude (`zfull`) is obtained via hydrostatic integration.
-
-> **Note:** `rho` and `zfull` must be added to a file before interpolating to another vertical coordinate. Unlike `msf`, these variables are computed on the native model grid and will not be properly calculated on any other vertical grid.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 2.5 Interpolate `atmos_average` to standard altitude
-
-Now that `rho` and `zfull` have been added to `07180.atmos_average.nc`, interpolating the file to standard altitude will include those variables in the new file (`07180.atmos_average_zstd.nc`):
-
-```bash
-(AmesCAP)>$ MarsInterp.py 07180.atmos_average.nc -t zstd
-```
-
-Your `/INERTCLDS` directory should now contain the fort.11 files and six `netCDF` files:
-
-```bash
-> 07180.atmos_fixed.nc 07180.atmos_average_pstd.nc fort.11_0721
-> 07180.atmos_average.nc 07180.atmos_average_zstd.nc fort.11_0722
-> 07180.atmos_diurn.nc fort.11_0719 fort.11_0723
-> 07180.atmos_daily.nc fort.11_0720
-```
-
-Use the inspect (`MarsPlot.py -i`) function to confirm that:
-
-* The original file (`07180.atmos_average.nc`) contains `rho` and `zfull` but not `msf`.
-* The altitude-interpolated file (`07180.atmos_average_zstd.nc`) contains `rho` and `zfull` but not `msf`.
-* The pressure-interpolated file (`07180.atmos_average_pstd.nc`) contains `msf` but not `rho` or `zfull`.
-
-```bash
-(AmesCAP)>$ MarsPlot.py -i 07180.atmos_average.nc # contains rho, zfull, not msf
-(AmesCAP)>$ MarsPlot.py -i 07180.atmos_average_zstd.nc # contains rho, zfull, not msf
-(AmesCAP)>$ MarsPlot.py -i 07180.atmos_average_pstd.nc # contains msf
-```
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 2.6 Time-shift and pressure-interpolate the `diurn` file
-
-The time-shift function is part of `MarsFiles` and pressure-interpolating is, as we know, part of `MarsInterp`. We'll start by pressure-interpolating the file, **but note that these functions can be used in either order.**
-
-The `diurn` file is organized by time-of-day assuming **universal time** beginning at the Martian prime meridian. Time-shifting the file converts the file to **uniform local time**, which is useful for comparing MGCM output to observations from satellites in fixed local time orbit, for example. Time-shifting can only be done on the `diurn` files because these contain a local time dimension (`ltst`).
-
-For this exercise, include only the surface pressure (`ps`), surface temperature (`ts`), and atmospheric temperature (`temp`) variables. This will minimize file size and processing time.
-
-Time-shift `ps`, `ts`, and `temp` using `MarsFiles`:
-
-```bash
-(AmesCAP)>$ MarsFiles.py 07180.atmos_diurn.nc -t --include ts ps temp
-```
-
-This created a new file ending in `_T.nc` and containing only `ts`, `ps`, `temp`, and their relevant dimensions. Now, pressure-interpolate the file using `MarsInterp`:
-
-```bash
-(AmesCAP)>$ MarsInterp.py 07180.atmos_diurn_T.nc -t pstd
-```
-
-This should take just over a minute.
-
-> **Note:** Interpolating large files (such as `daily` or `diurn` files) with CAP can take a long time because the code is written in Python. That's why we are only including three variables (`ps`, `ts`, and `temp`) in this particular demonstration.
-
-After time-shifting and pressure-interpolating, `/INERTCLDS` should contain three `diurn` files:
-
-```bash
-> 07180.atmos_diurn.nc 07180.atmos_diurn_T.nc 07180.atmos_diurn_T_pstd.nc
-```
-
-> **Note:** We will *not* do this here, but you can create custom vertical grids that you want CAP to interpolate to. See the documentation for `MarsInterp` for more information.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 2.7 Apply a low-pass filter (`-lpf`) to the surface pressure (`ps`) and temperature (`ts`) in the `daily` file
-
-Temporal filtering and tidal analyses are functions of `MarsFiles`. The low-pass filter argument requires a cutoff frequency, `sol_max`. Here, we use a 2-sol cut-off frequency to isolate synoptic-scale features. Include only `ps` and `ts` in the new file:
-
-```bash
-(AmesCAP)>$ MarsFiles.py 07180.atmos_daily.nc -lpf 2 -include ps ts
-```
-
-This created `07180.atmos_daily_lpf.nc` containing only `ps`, `ts`, and their relevant dimensions.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 2.8 Estimate the magnitude of the wind shear using CAP
-
-This can be done by vertically-differentiating the zonal (U) and meridional (V) winds, i.e. computing dU/dz and dV/dz. The U and V winds are output by the model as `ucomp` and `vcomp`, respectively.
-
-You already know that `MarsVars` is used for adding variables, however, the `-add` argument will not work here. Instead, there is a call specifically for vertical differentiation called `-zdiff`.
-
-Compute and add dU/dz and dV/dz to `07180.atmos_average_zstd.nc` using `-zdiff`:
-
-```bash
-(AmesCAP)>$ MarsVars.py 07180.atmos_average_zstd.nc -zdiff ucomp vcomp
-```
-
-Using the inspect (`MarsPlot.py -i`) function, we can see the new variables in the file:
-
-```bash
-(AmesCAP)>$ MarsPlot.py -i 07180.atmos_average_zstd.nc
-> ===================DIMENSIONS==========================
-> ['lat', 'lon', 'phalf', 'time', 'zstd']
-> .. (etc) ..
-> ====================CONTENT==========================
-> .. (etc) ..
-> d_dz_ucomp : ('time', 'zstd', 'lat', 'lon')= (10, 45, 36, 60), vertical gradient of zonal wind [m/s/m]]
-> d_dz_vcomp : ('time', 'zstd', 'lat', 'lon')= (10, 45, 36, 60), vertical gradient of meridional wind [m/m]]
-> .. (etc) ..
->
-> Ls ranging from 255.42 to 284.19: 45.00 days
-> (MY 01) (MY 01)
-> =====================================================
-```
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 2.9 Calculate the column-integrated dust, water ice, and water vapor mixing ratios in the `daily` file
-
-Similar to the -`zdiff` function, `MarsVars` has a `-col` function that performs a column integration on specified variables.
-
-Column-integrate the dust, water ice, and water vapor mixing ratios like so:
-
-```bash
-(AmesCAP)>$ MarsVars.py 07180.atmos_daily.nc -col dst_mass ice_mass vap_mass
-```
-
-Using the inspect (`MarsPlot.py -i`) function, we can see the new variables in the file:
-
-```bash
-(AmesCAP)>$ MarsPlot.py -i 07180.atmos_daily.nc
-> ===================DIMENSIONS==========================
-> ['lat', 'lon', 'pfull', 'phalf', 'zgrid', 'scalar_axis', 'time']
-> .. (etc) ..
-> ====================CONTENT==========================
-> .. (etc) ..
-> dst_mass_col : ('time', 'lat', 'lon')= (800, 36, 60), column integration of dust aerosol mass mixing ratio [kg/m2]
-> ice_mass_col : ('time', 'lat', 'lon')= (800, 36, 60), column integration of water ice aerosol mass mixing ratio [kg/m2]
-> vap_mass_col : ('time', 'lat', 'lon')= (800, 36, 60), column integration of water vapor mass mixing ratio [kg/m2]
-> dst_mass : ('time', 'pfull', 'lat', 'lon')= (800, 24, 36, 60), dust aerosol mass mixing ratio [kg/kg]
-> ice_mass : ('time', 'pfull', 'lat', 'lon')= (800, 24, 36, 60), water ice aerosol mass mixing ratio [kg/kg]
-> vap_mass : ('time', 'pfull', 'lat', 'lon')= (800, 24, 36, 60), water vapor mass mixing ratio [kg/kg]
->
-> Ls ranging from 254.12 to 286.06: 49.94 days
-> (MY 01) (MY 01)
-> =====================================================
-```
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 2.10 Display the values of `pfull`, then display the minimum, mean, and maximum near-surface temperatures `temp` over the globe
-
-Here, we build on our knowledge of the inspect (`MarsPlot.py -i`) function. We already know that `MarsPlot.py -i` displays the variables in a file and information about the file, but `--inspect` can be combined with `--dump` and `--stat` to show more information about specific variables.
-
-Display values of `pfull` in `07180.atmos_average.nc` using `--dump`:
-
-```bash
-(AmesCAP)>$ MarsPlot.py -i 07180.atmos_average.nc -dump pfull
-> pfull=
-> [8.7662227e-02 2.5499690e-01 5.4266089e-01 1.0518962e+00 1.9545468e+00
-> 3.5580616e+00 6.2466631e+00 1.0509957e+01 1.7400265e+01 2.8756382e+01
-> 4.7480076e+01 7.8348366e+01 1.2924281e+02 2.0770235e+02 3.0938846e+02
-> 4.1609518e+02 5.1308148e+02 5.9254102e+02 6.4705731e+02 6.7754218e+02
-> 6.9152936e+02 6.9731799e+02 6.9994830e+02 7.0082477e+02]
-> ______________________________________________________________________
-```
-
-As you can see, `--dump` is a kind of analog for the NCL command `ncdump`.
-
-Indexing specific values of `pfull` is done using quotes and square brackets:
-
-```bash
-(AmesCAP)>$ MarsPlot.py -i 07180.atmos_average.nc -dump 'pfull[-1]'
-> pfull[-1]=
-> 700.8247680664062
-> ______________________________________________________________________
-```
-
-Indexing the last array element with `-1` (Python syntax), we can see the reference pressure of the first layer above the surface in the MGCM.
-
-> **Note:** quotes `''` are necessary when browsing dimensions.
-
-The minimum, mean, and maximum values of a variable are computed and displayed in the terminal with the `-stat` argument. `-stat` is better suited for visualizing statistics over large arrays like the four-dimensional temperature variable (`temp`). Given the dimensions of the `temp` variable, `[time,pfull,lat,lon]`, use `-stat` to display the minimum, mean, and maximum **near-surface air temperature (over all timesteps and all locations)**:
-
-```bash
-(AmesCAP)>$ MarsPlot.py -i 07180.atmos_average.nc -stat 'temp[:,-1,:,:]'
-> __________________________________________________________________________
-> VAR | MIN | MEAN | MAX |
-> __________________________|_______________|_______________|_______________|
-> temp[:,-1,:,:]| 149.016| 202.508| 251.05|
-> __________________________|_______________|_______________|_______________|
-```
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-and... that's it for post-processing the data in the RIC simulation!
-
-Before moving on to plotting, we need to repeat some of these steps for the RAC simulation. Feel free to repeat all of Steps 2.1-2.10 for the RAC case if you like, but **you are only required to repeat Steps 2.1, 2.2, and 2.5** for this tutorial. For simplicity, we've summarized these steps here:
-
-***
-
-### 2.1b (for `/ACTIVECLDS`) Convert `fort.11` files into `netCDF` files
-
-In the `/ACTIVECLDS` directory, use `MarsFiles` to convert from `fort.11` to `netCDF`, and then concatenate the files along their `time` axes:
-
-```bash
-(AmesCAP)>$ MarsFiles.py fort.11_* -fv3 fixed average daily diurn
-(AmesCAP)>$ MarsFiles.py *fixed.nc -c
-(AmesCAP)>$ MarsFiles.py *average.nc -c
-(AmesCAP)>$ MarsFiles.py *diurn.nc -c
-(AmesCAP)>$ MarsFiles.py *daily.nc -c
-```
-
-`/ACTIVECLDS` should now contain the original `fort.11` files and just **four** `netCDF` files:
-
-```bash
-> 07180.atmos_fixed.nc fort.11_0719 fort.11_0723
-> 07180.atmos_average.nc fort.11_0720
-> 07180.atmos_diurn.nc fort.11_0721
-> 07180.atmos_daily.nc fort.11_0722
-```
-
-***
-
-### 2.2b (for `/ACTIVECLDS`) Interpolate `atmos_average` to standard pressure
-
-Use `MarsInterp`'s' `--type` (`-t`) command to create `07180.atmos_average_pstd.nc`.:
-
-```bash
-(AmesCAP)>$ MarsInterp.py 07180.atmos_average.nc -t pstd
-```
-
-***
-
-### 2.5b (for `/ACTIVECLDS`) Interpolate `atmos_average` to standard altitude
-
-Again, use `MarsInterp`'s' `--type` (`-t`) command to create `07180.atmos_average_zstd.nc`.:
-
-```bash
-(AmesCAP)>$ MarsInterp.py 07180.atmos_average.nc -t zstd
-```
-
-Your `/ACTIVECLDS` directory should now contain the fort.11 files and six `netCDF` files:
-
-```bash
-> 07180.atmos_fixed.nc 07180.atmos_average_pstd.nc fort.11_0721
-> 07180.atmos_average.nc 07180.atmos_average_zstd.nc fort.11_0722
-> 07180.atmos_diurn.nc fort.11_0719 fort.11_0723
-> 07180.atmos_daily.nc fort.11_0720
-```
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-# Optional: Download the Answer Key for Step 2
-
-1. Download `KEY.zip` from the CAP tutorial GitHub page [here](https://github.com/NASA-Planetary-Science/AmesCAP/tree/master/tutorial/tutorial_files).
-2. **Double-click** `KEY.zip` to unzip the file (do not do this from the command line) -> this should create a `KEY/` directory
-4. Open a terminal and run the command:
-
-```bash
-(AmesCAP)>$ path/to/KEY/Step2_Check.sh
-```
-
- **Note:** any permission errors can be fixed by running:
-
-```bash
-(AmesCAP)>$ chmod 766 path/to/KEY/Step2_Check.sh
-```
-
-`Step2_Check.sh` will prompt you for the path to your `/CAP_tutorial` directory:
-
-```bash
-(AmesCAP)>$ path/to/KEY/Step2_Check.sh
-> Please type the path to the directory containing CAP_tutorial, i.e. /Users/username:
->
-/Users/username/path/to/directory
->
-> Looking in /Users/username/path/to/directory for CAP_tutorial
-```
-
-When the script is done checking your answers, it will notify you which (if any) files or variables are missing from Step 2. Go back to the Step listed and redo them!
-
-If you are really stuck, you can run this shell script that will do all of Step 2 for you. This ensures you can follow along with the plotting routines in Step 3.
-
-To run the answer key, type in your terminal:
-
-```bash
-(AmesCAP)>$ path/to/KEY/KEY.sh
-```
-
-This will again ask for the path to `/CAP_tutorial`:
-
-```bash
-(AmesCAP)>$ path/to/KEY/KEY.sh
-> Please type the path to the directory containing CAP_tutorial, i.e. /Users/username:
->
-/Users/username/path/to/directory
->
-> Looking in /Users/username/path/to/directory for CAP_tutorial
-```
-
-> **Note:** Optionally, you can move `KEY.in` to your `/CAP_tutorial/INERTCLDS` directory and `KEY.sh` will do all of Step 2 **AND Step 3** for you.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-# Break
-
-Once you've completed Step 2, you are welcome to take a 15 minute break from the tutorial.
-
-You can use this time to catch up if you haven't completed Steps 1 and/or 2 already, but we highly encourage you to step away from your machine for these 15 minutes.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-## 3. Plotting Routines
-
-Time to practice plotting MGCM output with CAP!
-
-CAP's plotting routine is `MarsPlot`, which can create several plot types:
-
-|Type of plot |MarsPlot Designation |
-| ---: | :--- |
-| Longitude v Latitude |`Plot 2D lon x lat` |
-| Longitude v Time |`Plot 2D lon x time` |
-| Longitude v Level |`Plot 2D lon x lev` |
-| Latitude v Level |`Plot 2D lat x lev` |
-| Time v Latitude |`Plot 2D time x lat` |
-| Time v level |`Plot 2D time x lev` |
-| Any 1-D line plot |`Plot 1D` |
-
-`MarsPlot` is customizable. Options include:
-* PDF or image format
-* Landscape or portrait mode
-* 1+ plots per page
-* Overplotting is supported
-* Adjustible axes dimensions, colormaps, map projections, contour levels, etc.
-
-**Plotting with CAP requires passing a template to `MarsPlot`.**
-
-Create the default template by typing:
-
-```bash
-(AmesCAP)>$ MarsPlot.py -template
-```
-
-The template is called `Custom.in`. We will edit `Custom.in` to create various plots. **We highly recommend using a text editor that opens `Custom.in` in its own window.** Some options include: gvim, sublime text, atom, and pyzo.
-
-If you use vim, you just have to be familiar with copying and pasting in the terminal. You will also benefit from opening another terminal from which to run command-line calls.
-
-Open `Custom.in` in your preferred text editor, for example:
-
-```bash
-(AmesCAP)>$ gvim Custom.in
-```
-
-Scroll down until you see the first two templates shown in the image below:
-
-
-
-By default, `Custom.in` is set to create the two plots shown above: a global topographical map and a zonal mean wind cross-section. The plot type is indicated at the top of each template:
-
-``` python
-> <<<<<<<<<<<<<<| Plot 2D lon X lat = True |>>>>>>>>>>>>>
-> <<<<<<<<<<<<<<| Plot 2D lat X lev = True |>>>>>>>>>>>>>
-```
-
-When set to `True` (as it is here), `MarsPlot` will draw that plot. If `False`, `MarsPlot` will skip that plot.
-
-The variable to be plotted is `Main Variable`, which requires the variable name and the file containing it as input:
-
-```python
- Main Variable = fixed.zsurf # file.variable
-```
-
-**Without making any changes to `Custom.in`**, close the file and pass it back to `MarsPlot`:
-
-```bash
-(AmesCAP)>$ MarsPlot.py Custom.in
-```
-
-This creates `Diagnostics.pdf`, a single-page PDF displaying the two plots we just discussed: global topography and zonal mean wind. Open the PDF to see the plots.
-
-You can rename `Custom.in` and still pass it to `MarsPlot` successfully. If the template is named anything other than `Custom.in`, `MarsPlot` will produce a PDF named after the template, i.e. `myplots.in` creates `myplots.pdf`. For example:
-
-```bash
-(AmesCAP)>$ mv Custom.in myplots.in
-(AmesCAP)>$ MarsPlot.py myplots.in
-> Reading myplots.in
-> [----------] 0 % (2D_lon_lat :fixed.zsurf)
-> [#####-----] 50 % (2D_lat_lev :atmos_average.ucomp, Ls= (MY 1) 284.19, zonal avg)
-> [##########]100 % (Done)
-> Merging figures...
-> "/username/CAP_tutorial/INERTCLDS/myplots.pdf" was generated
-```
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-Those are the basics of plotting with CAP. We'll create several plots in exercises 3.1-3.11 below. Begin by deleting `myplots.in` and `myplots.pdf` (if you have them), and then create a new `Custom.in` template:
-
-```bash
-(AmesCAP)>$ rm myplots.in myplots.pdf
-(AmesCAP)>$ MarsPlot.py -template
-```
-
-**Make sure you're in the `/INERTCLDS` directory before continuing.**
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 3.1 Create a global map of surface albedo (`alb`) with topography (`zsurf`) contoured on top
-
-Open `Custom.in` in your preferred text editor and make the following changes:
-
-* Set `Plot 2D lat X lev` to `False` so that `MarsPlot` does not draw it
-* On `Plot 2D lon X lat`, set `Main Variable` to albedo (`alb`), which is located in the `fixed` file. Albedo will be color-filled contours.
-* Set `2nd Variable` to topography (`zsurf`), also located in the `fixed` file. Topography will be solid contours.
-* Set the `Title` to reflect the variable(s) being plotted (we like to set the title to reflect the exercise being plotted)
-
-Here is what your template should look like:
-
-```python
-> <<<<<<<<<<<<<<| Plot 2D lon X lat = True |>>>>>>>>>>>>>
-> Title = 3.1: Albedo w/Topography Overplotted
-> Main Variable = fixed.alb
-> Cmin, Cmax = None
-> Ls 0-360 = None
-> Level [Pa/m] = None
-> 2nd Variable = fixed.zsurf
-> Contours Var 2 = None
-> Axis Options : lon = [None,None] | lat = [None,None] | cmap = binary | scale = lin | proj = cart
-```
-
-Save `Custom.in` (but don't close it!) and go back to the terminal. Pass `Custom.in` back to `MarsPlot`:
-
-```bash
-(AmesCAP)>$ MarsPlot.py Custom.in
-```
-
-Open `Diagnostics.pdf` and check to make sure it contains a global map of surface albedo with topography contoured overtop.
-
-> Depending on the settings for your specific PDF viewer, you may have to close and reopen the file to view it.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 3.2 Plot the zonal mean zonal wind cross-section at Ls=270° using altitude as the vertical coordinate
-
-`Custom.in` should still be open in your text editor. If not, open it again.
-
-To use altitude as the vertical coordinate, source the variable from the altitude-interpolated file: `atmos_average_zstd`.
-
-* Set the `2D lat X lev` template to `True`
-* Change `Main Variable` to point to `ucomp` stored in the `atmos_average_zstd` file
-* Set `Ls` to 270°
-* Edit the `Title` accordingly
-
-Save `Custom.in`, and pass it to `MarsPlot`. Again, view `Diagnostics.pdf` to see your plots!
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 3.3 Add the same plot for the RAC case to the same page
-
-> **Tip:** Copy and paste the `lat x lev` plot you made in 3.2 so that you have two identical templates.
-
-Point `MarsPlot` to the `/ACTIVECLDS` directory. Do this by editing the `<<<<<<< Simulations <<<<<<<` section so that `2>` points to `/ACTIVECLDS` like so:
-
-```python
-> <<<<<<<<<<<<<<<<<<<<<< Simulations >>>>>>>>>>>>>>>>>>>>>
-> ref> None
-> 2> ../ACTIVECLDS
-> 3>
-```
-
-Edit `Main Variable` in the duplicate template so that the `atmos_average_zstd` file in `/ACTIVECLDS` is sourced:
-
-```python
-> Main Variable = atmos_average_zstd@2.ucomp
-```
-
-> **Tip:** Make use of `HOLD ON` and `HOLD OFF` for these.
-
-Save `Custom.in` and pass it to `MarsPlot`. View `Diagnostics.pdf` to see the results.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 3.4 Overplot temperature in solid contours
-
-Add `temp` as the `2nd Variable` in the plots you created in 3.2 and 3.3:
-
-```python
-> <<<<<<<<<<<<<<| Plot 2D lat X lev = True |>>>>>>>>>>>>>
-> > 2nd Variable = atmos_average_zstd.temp
-> .. (etc) ..
->
-> <<<<<<<<<<<<<<| Plot 2D lat X lev = True |>>>>>>>>>>>>>
-> > 2nd Variable = atmos_average_zstd@2.temp
-> .. (etc) ..
-```
-
-Save `Custom.in` and pass it to `MarsPlot`. View `Diagnostics.pdf` to see the results.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 3.5 Plot the surface CO2 ice content in g/m2 and compute and plot surface wind speed from the U and V winds
-
-These will be `lon X lat` plots. Both require variable operations using square brackets `[]`. Plot the results at Ls=270°. Source all of the variables from the `atmos_daily` file in `/INERTCLDS`.
-
-Surface CO2 Ice (`snow`):
-* Convert kg/m2 -> g/m2
-* Set the plot area to between 50 °N and 90 °N.
-
-Using square brackets, `Main Variable` is set (and units converted) like:
-
-```python
-Main Variable = [atmos_daily.snow]*1000
-```
-
-Surface Wind Speed (`sqrt(u^2 + v^2)`):
-* Call both `ucomp` and `vcomp` under `Main Variable`
-
- Using square brackets, `Main Variable` is set (and computed) like:
-
-```python
-Main Variable = sqrt([atmos_daily.ucomp]**2+[atmos_daily.vcomp]**2)
-```
-
-Use `HOLD ON` and `HOLD OFF` again. You can use this syntax multiple times in the same template.
-
-The general format will be:
-
-```python
-> HOLD ON
->
-> <<<<<<| Plot 2D lon X lat = True |>>>>>>
-> Title = Surface CO2 Ice (g/m2)
-> .. (etc) ..
->
-> <<<<<<| Plot 2D lon X lat = True |>>>>>>
-> Title = Surface Wind Speed (m/s)
-> .. (etc) ..
->
-> HOLD OFF
-```
-
-Name the plots accordingly. Save `Custom.in` and pass it to `MarsPlot`. You should see two plots on one page in `Diagnostics.pdf`
-
-### 3.6 Make the following changes to the plots you created in 3.5
-
-For the **surface CO2 ice** plot:
-
-* Set the projection type to `Npole`
-* Change the Y axis limits to 60-90 N
-
-For the **surface wind speed** plot:
-
-* Draw contours at 1, 10, and 20, m/s *(add a second variable!)*
-* Constrain the Y axis limits to the northern hemisphere
-* Constrain the X axis limits to the western hemisphere
-
-**Hint:** we set the latitude range in the previous plot by editing `lat` in `Axis Options`:
-
-```python
-Axis Options : lon = [None,None] | lat = [50,90] | cmap = jet | scale = lin | proj = cart
-```
-
-but this only works for cylindrical projections (cartesian `cart`, Robinson `robin`, Mollweide `moll` ).
-
-When you choose an azimutal projection (North polar `Npole`, South polar `Spole`, orthographic `ortho`), you set the **bounding latitude** by adding an argument *after* specifying the projection:
-
-```python
-Axis Options : lon = [None,None] | lat = [None,None] | cmap = jet | scale = lin | proj = Npole 60
-```
-
-For each azimutal projection, acceptable arguments are: `proj = Npole lat_max`, `proj = Spole lat_min`, and `proj = ortho lon_center lat_center`.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 3.7 Create the following zonal mean `time X lat` plots on a new page
-
-Source all of the variables from the `atmos_daily` file in `/INERTCLDS`:
-
-* Surface Temperature (`ts`). Set the colormap to `nipy_spectral`.
-* Column dust mass (`dst_mass_col`). Set the colormap to `Spectral_r`.
-* Column water ice mass (`ice_mass_col`). Set the colormap to `Spectral_r`.
-* Column water vapor mass (`vap_mass_col`). Set the colormap to `Spectral_r`.
-
-> **NOTE:** set the colormap (`cmap`) in `Axis Options`:
->
->```python
->Axis Options : sols = [None,None] | lat = [None,None] | cmap = nipy_spectral |scale = lin
->```
-
-The general format will look like:
-
-```python
-> HOLD ON
->
-> <<<<<<| Plot 2D time X lat = True |>>>>>>
-> Title = Zonal Mean Surface Temperature (K)
-> .. (etc) ..
->
-> <<<<<<| Plot 2D time X lat = True |>>>>>>
-> Title = Zonal Mean Column Integrated Dust Mass (kg/m2)
-> .. (etc) ..
->
-> <<<<<<| Plot 2D time X lat = True |>>>>>>
-> Title = Zonal Mean Column Integrated Water Ice Mass (kg/m2)
-> .. (etc) ..
->
-> <<<<<<| Plot 2D time X lat = True |>>>>>>
-> Title = 1Zonal Mean Column Integrated Water Vapor Mass (kg/m2)
-> .. (etc) ..
->
-> HOLD OFF
-```
-
-Name the plots accordingly. Save `Custom.in` and pass it to `MarsPlot`.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 3.8 Plot the following two cross-sections (`lat X lev`) on the same page
-
-**Zonal mean mass streamfunction (`msf`) at Ls=270°**
-
-* Force symmetrical contouring by setting the colorbar's minimum and maximum values to -150 and 150
-* Overplot solid contours at `-100,-50,-10,-5,5,10,50,100` *(Hint: set both `Main Variable` and `2nd Variable` to `msf`)*
-* Adjust the Y axis limits to 1,000-1 Pa
-* Change the colormap from `jet` to `RdBu_r`
-
-**Zonal mean temperature (`temp`) at Ls=270°**
-
-* Source `temp` from the same pressure-interpolated file you sourced `msf` from
-* Overplot (`2nd Variable`) the zonal mean zonal wind (`ucomp`)
-* Adjust the Y axis limits to 1,000-1 Pa
-* Set the colormap to `jet`
-
-Don't forget to use `HOLD ON` and `HOLD OFF` and to name your plots accordingly. Save `Custom.in` and pass it to `MarsPlot`.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 3.9 Plot zonal mean temperature from the RIC and RAC cases
-
-Create the plots at Ls=270° from the `atmos_average_pstd` file, then create a difference plot.
-
-Make use of `HOLD ON` and `HOLD OFF` again here. Copy and paste a `lat x lev` template, edit the first plot, then copy and paste that two more times. For the difference plot, you'll need subtract the two `temp` variables from one another, so make use of `@N` to point to the `/ACTIVECLDS` directory and square brackets `[]` to subtract one variable from the other:
-
-```python
-> Main Variable = [atmos_average_pstd.temp]-[atmos_average_pstd@2.temp]
-```
-
-* On the RIC & RAC plots: set the minimum and maximum contour-fill interval (`Cmin,Cmax`) to 130 and 250 (K)
-* On the difference plot: set the colormap to `RdBu`
-* On the difference plot: set the minimum and maximum contour-fill interval (`Cmin,Cmax`) -15 and 15 (K)
-* On all three plots: set the vertical range to 1,000 - 1 Pa
-* On all three plots: set proper titles
-
-Save `Custom.in` and pass it to `MarsPlot`.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 3.10 Generate two 1D temperature profiles (`temp`) from the RIC case
-
-Draw the 3 AM and 3 PM thermal profiles at `50°N, 150°E` at Ls=270°. Call `temp` from the `atmos_diurn_T_pstd` file, which is the time-shifted and pressure-interpolated version of the diurn file. 3 AM is index=`3`, 3 PM is index=`15`, so `Main Variable` will be set as:
-
-```python
-> Main Variable = atmos_diurn_T_pstd.temp{ tod=3 }
-# filename.var{ tod=X }
-```
-
-for the 3 AM line, and
-
-```python
-> Main Variable = atmos_diurn_T_pstd.temp{tod=15}
-```
-
-for the 3 PM line. You will have to specify `Level [Pa/m]` as the other axis:
-
-```python
-> Level [Pa/m] = AXIS
-```
-
-> Note that when you specify level as the AXIS, MarsPlot automatically reverses the axes to draw a vertical profile of the requested variable.
-
-Fnally, change the Y axis limits from `None` to `1000,1` Pa:
-
-```python
-> lat,lon+/-180,[Pa/m],sols = [1000,1]
-```
-
-As a reminder, to draw two lines on one axes, use `ADD LINE`:
-
-```python
-> <<<<<<| Plot 1D = True |>>>>>>
-> Main Variable = var1
-> .. (etc) ..
->
-> ADD LINE
->
-> <<<<<<| Plot 1D = True |>>>>>>
-> Main Variable = var2
-> .. (etc) ..
-```
-
-#### **NOTE:** You do not use `HOLD ON` and `HOLD OFF` to overplot 1D plots. `HOLD` is always for drawing separate plots on the same page
-
-Save `Custom.in` and pass it to `MarsPlot`. View `Diagnostics.pdf`.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-### 3.11 Plot the 1D filtered and unfiltered surface pressure over a 20-sol period
-
-Compare the unfiltered surface pressure `ps`, which is the original variable in the orginal daily file (`atmos_daily`), to the filtered surface pressure, which is the time-filtered variable created when we applied a low-pass filter to the daily file (`atmos_daily_lpf`) in exercise 2.6, at 50°N and 150°E.
-
-* Both are 1D plots. Use `ADD LINE` to plot on the same axes
-* Use `ps` from `atmos_daily` and `atmos_daily_lpf`
-* Set `Latitude = 50` and `Lon +/-180 = 150`
-* To show a 20-sol period: under `Axis Options`, set the X axis range to (`Ls = [260, 280]`)
-* Narrow the Y axis range: under `Axis Options`, set the Y axis range to (`var = [860,980]` Pa)
-
-Save `Custom.in` and pass it to `MarsPlot`. View `Diagnostics.pdf`.
-
-[(Return to Top)](#table-of-contents)
-
-***
-
-## That's a Wrap
-
-This concludes the practical exercise portion of the CAP tutorial. Please keep these exercises as a reference for the future!
-
-*This document was completed in October 2021. Written by Alex Kling, Courtney Batterson, and Victoria Hartwick*
-
-Please submit feedback to Alex Kling: alexandre.m.kling@nasa.gov
-
-[(Return to Top)](#table-of-contents)
-
-***
diff --git a/tutorial/CAP_Install.md b/tutorial/CAP_Install.md
deleted file mode 100644
index b99995af..00000000
--- a/tutorial/CAP_Install.md
+++ /dev/null
@@ -1,444 +0,0 @@
-
-
-
-***
-
-# Installing the Community Analysis Pipeline (CAP)
-
-### Welcome!
-
-This document contains the instructions for installing the NASA Ames MCMC's Community Analysis Pipeline (CAP).
-
-Installing CAP is fairly straightforward. We will create a Python virtual environment, download CAP, and then install CAP in the virtual environment. That's it!
-
-A quick overview of what is covered in this installation document:
-
-1. [Creating the Virtual Environment](#1-creating-the-virtual-environment)
-2. [Installing CAP](#2-installing-cap)
-3. [Testing & Using CAP](#3-testing-using-cap)
-4. [Practical Tips](#4-practical-tips-for-later-use-during-the-tutorial)
-
-
-
-***
-
-## 1. Creating the Virtual Environment
-
-We begin by creating a virtual environment in which to install CAP. The virtual environment is an isolated Python environment cloned from an existing Python distribution. The virtual environment consists of the same directory trees as the original environment, but it includes activation and deactivation scripts that are used to move in and out of the virtual environment. Here's an illustration of how the two Python environments might differ:
-
-```
- anaconda3 virtual_env3/
- ├── bin ├── bin
- │ ├── pip (copy) │ ├── pip
- │ └── python3 >>>> │ ├── python3
- └── lib │ ├── activate
- │ ├── activate.csh
- │ └── deactivate
- └── lib
-
- ORIGINAL ENVIRONMENT VIRTUAL ENVIRONMENT
- (untouched) (vanishes when deactivated)
-```
-
-We can install and upgrade packages in the virtual environment without breaking the main Python environment. In fact, it is safe to change or even completely delete the virtual environment without breaking the main distribution. This allows us to experiment freely in the virtual environment, making it the perfect location for installing and testing CAP.
-
-
-
-
-***
-
-### Step 1: Identify Your Preferred Python Distribution
-
-If you are already comfortable with Python's package management system, you are welcome to install the pipeline on top any python**3** distribution already present on your computer. Jump to Step #2 and resolve any missing package dependency.
-
-For all other users, we highly recommend using the latest version of the Anaconda Python distribution. It ships with pre-compiled math and plotting packages such as `numpy` and `matplotlib` as well as pre-compiled libraries like `hdf5` headers for reading `netCDF` files (the preferred filetype for analysing MGCM output).
-
-You can install the Anaconda Python distribution via the command-line or using a [graphical interface](https://www.anaconda.com/download) (scroll to the very bottom of the page for all download options). You can install Anaconda at either the `System/` level or the `User/` level (the later does not require admin-priviledges). The instructions below are for the **command-line installation** and installs Anaconda in your **home directory**, which is the recommended location. Open a terminal and type the following:
-
-```bash
-(local)>$ chmod +x Anaconda3-2021.05-MacOSX-x86_64.sh # make the .sh file executable (actual name may differ)
-(local)>$ ./Anaconda3-2021.05MacOSX-x86_64.sh # runs the executable
-```
-
-Which will return:
-
-```bash
-> Welcome to Anaconda3 2021.05
->
-> In order to continue the installation process, please review the license agreement.
-> Please, press ENTER to continue
-> >>>
-```
-
-Read (`ENTER`) and accept (`yes`) the terms, choose your installation location, and initialize Anaconda3:
-
-```bash
-(local)>$ [ENTER]
-> Do you accept the license terms? [yes|no]
-> >>>
-(local)>$ yes
-> Anaconda3 will now be installed into this location:
-> /Users/username/anaconda3
->
-> - Press ENTER to confirm the location
-> - Press CTRL-C to abort the installation
-> - Or specify a different location below
->
-> [/Users/username/anaconda3] >>>
-(local)>$ [ENTER]
-> PREFIX=/Users/username/anaconda3
-> Unpacking payload ...
-> Collecting package metadata (current_repodata.json):
-> done
-> Solving environment: done
->
-> ## Package Plan ##
-> ...
-> Preparing transaction: done
-> Executing transaction: -
-> done
-> installation finished.
-> Do you wish the installer to initialize Anaconda3 by running conda init? [yes|no]
-> [yes] >>>
-(local)>$ yes
-```
-
-> For Windows users, we recommend installing the pipeline in a Linux-type environment using [Cygwin](https://www.cygwin.com/). This will enable the use of CAP command line tools. Simply download the Windows version of Anaconda on the [Anaconda website](https://www.anaconda.com/distribution/#download-section) and follow the instructions from the installation GUI. When asked about the installation location, make sure you install Python under your emulated-Linux home directory (`/home/username`) and ***not*** in the default location (`/cygdrive/c/Users/username/anaconda3`). From the installation GUI, the path you want to select is something like: `C:/Program Files/cygwin64/home/username/anaconda3`. Also be sure to check **YES** when prompted to "Add Anaconda to my `PATH` environment variable."
-
-Confirm that your path to the Anaconda Python distribution is fully actualized by closing out of the current terminal, opening a new terminal, and typing:
-
-```bash
-(local)>$ python[TAB]
-```
-
-If this returns multiple options (e.g. `python`, `python2`, `python 3.7`, `python.exe`), then you have more than one version of Python sitting on your system (an old `python2` executable located in `/usr/local/bin/python`, for example). You can see what these versions are by typing:
-
-```bash
-(local)>$ python3 --version # Linux/MacOS
-(local)>$ python.exe --version # Cygwin/Windows
-```
-
-Check your version of `pip` the same way, then find and set your `$PATH` environment variable to point to the Anaconda Python *and* Anaconda pip distributions. If you are planning to use Python for other projects, you can update these paths like so:
-
-```bash
-# with bash:
-(local)>$ echo 'export PATH=/Users/username/anaconda3/bin:$PATH' >> ~/.bash_profile
-# with csh/tsch:
-(local)>$ echo 'setenv PATH $PATH\:/Users/username/anaconda3/bin\:$HOME/bin\:.' >> ~/.cshrc
-```
-
-Confirm these settings using the `which` command:
-
-```bash
-(local)>$ which python3 # Linux/MacOS
-(local)>$ which python.exe # Cygwin/Windows
-```
-
-which hopefully returns a Python executable that looks like **it was installed with Anaconda**, such as:
-
-```bash
-> /username/anaconda3/bin/python3 # Linux/MacOS
-> /username/anaconda3/python.exe # Cygwin/Windows
-```
-
-If `which` points to either of those locations, you are good to go and you can proceed from here using the shorthand path to your Anaconda Python distribution:
-
-```bash
-(local)>$ python3 # Linux/MacOS
-(local)>$ python.exe # Cygwin/Windows
-```
-
-If, however, `which` points to some other location, such as `/usr/local/bin/python`, or more than one location, proceed from here using the **full** path to the Anaconda Python distribution:
-
-```bash
-(local)>$ /username/anaconda3/bin/python3 # Linux/MacOS
-(local)>$ /username/anaconda3/python.exe # Cygwin/Windows
-```
-
-
-
-
-***
-
-### Step 2: Set Up the Virtual Environment:
-
-Python virtual environments are created from the command line. Create an environment called `AmesCAP` by typing:
-
-```bash
-(local)>$ python3 -m venv --system-site-packages AmesCAP # Linux/MacOS Use FULL PATH to python if needed
-(local)>$ python.exe -m venv –-system-site-packages AmesCAP # Cygwin/Windows Use FULL PATH to python if needed
-```
-
-First, find out if your terminal is using *bash* or a variation of *C-shell* (*.csh*, *.tsch*...) by typing:
-
-```bash
-(local)>$ echo $0
-> -bash
-```
-
-Depending on the answer, you can now activate the virtual environment with one of the options below:
-
-```bash
-(local)>$ source AmesCAP/bin/activate # bash
-(local)>$ source AmesCAP/bin/activate.csh # csh/tcsh
-(local)>$ source AmesCAP/Scripts/activate.csh # Cygwin/Windows
-(local)>$ conda AmesCAP/bin/activate # if you used conda
-```
-
-> In Cygwin/Windows, the `/bin` directory may be named `/Scripts`.
-
-You will notice that after sourcing `AmesCAP`, your prompt changed indicate that you are now *inside* the virtual environment (i.e. `(local)>$ ` changed to `(AmesCAP)>$`).
-
-We can verify that `which python` and `which pip` unambiguously point to `AmesCAP/bin/python3` and `AmesCAP/bin/pip`, respectively, by calling `which` within the virtual environment:
-
-```bash
-(AmesCAP)>$ which python3 # in bash, csh
-> AmesCAP/bin/python3
-(AmesCAP)>$ which pip
-> AmesCAP/bin/pip
-
-(AmesCAP)>$ which python.exe # in Cygwin/Windows
-> AmesCAP/Scripts/python.exe
-(AmesCAP)>$ which pip
-> AmesCAP/Scripts/pip
-```
-
-There is therefore no need to reference the full paths while **inside** the virtual environment.
-
-
-
-
-***
-
-## 2. Installing CAP
-
-### Using `pip`
-
-Open a terminal window, activate the virtual environment, and untar the file or install from the github:
-
-```bash
-(local)>$ source ~/AmesCAP/bin/activate # bash
-(local)>$ source ~/AmesCAP/bin/activate.csh # cshr/tsch
-(local)>$ source ~/AmesCAP/Scripts/activate.csh # Cygwin/Windows
-(local)>$ conda AmesCAP/bin/activate # if you used conda
-
-
-(AmesCAP)>$ pip install git+https://github.com/NASA-Planetary-Science/AmesCAP.git
-```
-> Please follow the instructions to upgrade pip if recommended during that steps. Instructions relevant the *conda* package manager are listed at the end of this section
-
-
-
-That's it! CAP is installed in `AmesCAP` and you can see the `MarsXXXX.py` executables stored in `~/AmesCAP/bin/`:
-
-```bash
-(local)>$ ls ~/AmesCAP/bin/
-> Activate.ps1 MarsPull.py activate.csh nc4tonc3 pip3
-> MarsFiles.py MarsVars.py activate.fish ncinfo pip3.8
-> MarsInterp.py MarsViewer.py easy_install normalizer python
-> MarsPlot.py activate easy_install-3.8 pip python3
-```
-
-
-Double check that the paths to the executables are correctly set in your terminal by exiting the virtual environment:
-
-```bash
-(AmesCAP)>$ deactivate
-```
-
-then reactivating the virtual environment:
-
-```bash
-(local)>$ source ~/AmesCAP/bin/activate # bash
-(local)>$ source ~/AmesCAP/bin/activate.csh # csh/tsch
-(local)>$ source ~/AmesCAP/Scripts/activate.csh # cygwin
-(local)>$ conda AmesCAP/bin/activate # if you used conda
-```
-
-and checking the documentation for any CAP executable using the `--help` option:
-
-```bash
-(AmesCAP)>$ MarsPlot.py --help
-(AmesCAP)>$ MarsPlot.py -h
-```
-
-or using **full** paths:
-
-```bash
-(AmesCAP)>$ ~/AmesCAP/bin/MarsPlot.py -h # Linux/MacOS
-(AmesCAP)>$ ~/AmesCAP/Scripts/MarsPlot.py -h # Cygwin/Windows
-```
-
-If the pipeline is installed correctly, `--help` will display documentation and command-line arguments for `MarsPlot` in the terminal.
-
-> If you have either purposely or accidentally installed the `AmesCAP` package on top of your main python distribution (e.g. in `~/anaconda3/lib/python3.7/site-packages/` or `~/anaconda3/bin/`) BEFORE setting-up the `AmesCAP` virtual environment, the `Mars*.py` executables may not be present in the `~/AmesCAP/bin/` directory of the virtual environment (`~/AmesCAP/Scripts/` on Cygwin). Because on Step 2 we created the virtual environment using the `--system-site-packages` flag, python will consider that `AmesCAP` is already installed when creating the new virtual environment and pull the code from that location, which may change the structure of the `~/AmesCAP/bin` directory within the virtual environment. If that is the case, the recommended approach is to exit the virtual environment (`deactivate`), run `pip uninstall AmesCAP` to remove CAP from the main python distribution, and start over at Step 2.
-
-This completes the one-time installation of CAP in your virtual environment, `AmesCAP`, which now looks like:
-
-```
-AmesCAP/
-├── bin
-│ ├── MarsFiles.py
-│ ├── MarsInterp.py
-│ ├── MarsPlot.py
-│ ├── MarsPull.py
-│ ├── MarsVars.py
-│ ├── activate
-│ ├── activate.csh
-│ ├── deactivate
-│ ├── pip
-│ └── python3
-├── lib
-│ └── python3.7
-│ └── site-packages
-│ ├── netCDF4
-│ └── amescap
-│ ├── FV3_utils.py
-│ ├── Ncdf_wrapper.py
-│ └── Script_utils.py
-├── mars_data
-│ └── Legacy.fixed.nc
-└── mars_templates
- ├──amescap_profile
- └── legacy.in
-```
-
-
-
-
-***
-
-### Using `conda`
-
-If you prefer using the `conda` package manager for setting up your virtual environment instead of `pip`, you may use the following commands to install CAP.
-
-First, verify (using `conda info` or `which conda`) that you are using the intented `conda` executable (two or more versions of `conda` might be present if both Python2 and Python3 are installed on your system). Then, create the virtual environment with:
-
-```bash
-(local)>$ conda create -n AmesCAP
-```
-
-Activate the virtual environment, then install CAP:
-
-```bash
-(local)>$ conda activate AmesCAP
-(AmesCAP)>$ conda install pip
-(AmesCAP)>$ pip install git+https://github.com/NASA-Planetary-Science/AmesCAP.git
-```
-
-The source code will be installed in:
-
-```bash
-/path/to/anaconda3/envs/AmesCAP/
-```
-
-and the virtual environment may be activated and deactivated with `conda`:
-
-```bash
-(local)>$ conda activate AmesCAP
-(AmesCAP)>$ conda deactivate
-(local)>$
-```
-
-
-> **Note:** CAP requires the following Python packages, which were automatically installed with CAP:
-> ```bash
-> matplotlib # the MatPlotLib plotting library
-> numpy # math library
-> scipy # math library and input/output for fortran binaries
-> netCDF4 Python # handling netCDF files
-> requests # downloading GCM output from the MCMC Data Portal
-> ```
-
-
-
-***
-
-### Removing CAP
-
-To permanently remove CAP, activate the virtual environment and run the `uninstall` command:
-
-```bash
-(local)>$ source AmesCAP/bin/activate # bash
-(local)>$ source AmesCAP/bin/activate.csh # csh/tcsh
-(local)>$ source AmesCAP/Scripts/activate.csh # Cygwin/Windows
-(AmesCAP)>$ pip uninstall AmesCAP
-```
-
-You may also delete the `AmesCAP` virtual environment directory at any time. This will uninstall CAP, remove the virtual environment from your machine, and will not affect your main Python distribution.
-
-
-***
-
-## 3. Testing & Using CAP
-
-Whenever you want to use CAP, simply activate the virtual environment and all of CAP's executables will be accessible from the command line:
-
-```bash
-(local)>$ source AmesCAP/bin/activate # bash
-(local)>$ source AmesCAP/bin/activate.csh # csh/tcsh
-(local)>$ source AmesCAP/Scripts/activate.csh # Cygwin/Windows
-```
-
-You can check that the tools are installed properly by typing `Mars` and then pressing the **TAB** key. No matter where you are on your system, you should see the following pop up:
-
-```bash
-(AmesCAP)>$ Mars[TAB]
-> MarsFiles.py MarsInterp.py MarsPlot.py MarsPull.py MarsVars.py
-```
-
-If no executables show up then the paths have not been properly set in the virtual environment. You can either use the full paths to the executables:
-
-```bash
-(AmesCAP)>$ ~/AmesCAP/bin/MarsPlot.py
-```
-
-Or set up aliases in your `./bashrc` or `.cshrc`:
-
-```bash
-# with bash:
-(local)>$ echo alias MarsPlot='/Users/username/AmesCAP/bin/MarsPlot.py' >> ~/.bashrc
-(local)>$ source ~/.bashrc
-
-# with csh/tsch
-(local)>$ echo alias MarsPlot /username/AmesCAP/bin/MarsPlot >> ~/.cshrc
-(local)>$ source ~/.cshrc
-```
-
-
-
-***
-
-## 4. Practical Tips for Later Use During the Tutorial
-
-
-
-### Install `ghostscript` to Create Multiple-Page PDFs When Using `MarsPlot`
-
-Installing `ghostscript` on your local machine allows CAP to generate a multiple-page PDF file instead of several individual PNGs when creating several plots. Without `ghostcript`, CAP defaults to generating multiple `.png` files instead of a single PDF file, and we therefore strongly recommend installing `ghostscript` to streamline the plotting process.
-
-
-First, check whether you already have `ghostscript` on your machine. Open a terminal and type:
-
-```bash
-(local)>$ gs -version
-> GPL Ghostscript 9.54.0 (2021-03-30)
-> Copyright (C) 2021 Artifex Software, Inc. All rights reserved.
-```
-
-If `ghostscript` is not installed, follow the directions on the `ghostscript` [website](https://www.ghostscript.com/download.html) to install it.
-> If `gs -version` returns a 'command not found error' but you are able to locate the `gs` executable on your system (e.g. /opt/local/bin/gs) you may need to add that specific directory (e.g. /opt/local/bin/) to your search $PATH as done for Python and pip in Step 1
-
-
-
-### Enable Syntax Highlighting for the Plot Template
-
-The `MarsPlot` executable requires an input template with the `.in` file extension. We recommend using a text editor that provides language-specific (Python) syntax highlighting to make keywords more readable. A few options include: [Atom](https://atom.io/) and vim (compatible with MacOS, Windows, Linux), notepad++ (compatible with Windows), or gedit (compatible with Linux).
-
-The most commonly used text editor is vim. Enabling proper syntax-highlighting for Python in **vim** can be done by adding the following lines to `~/.vimrc`:
-
-```bash
-syntax on
-colorscheme default
-au BufReadPost *.in set syntax=python
-```
diff --git a/tutorial/CAP_lecture.md b/tutorial/CAP_lecture.md
deleted file mode 100644
index 6ab68655..00000000
--- a/tutorial/CAP_lecture.md
+++ /dev/null
@@ -1,762 +0,0 @@
-
-
-# Introducing the Community Analysis Pipeline (CAP)
-
-
-
-
-## Table of Contents
-* [Introducing the Community Analysis Pipeline (CAP)](#introducing-the-community-analysis-pipeline-cap)
-* [Cheat sheet](#cheat-sheet)
-* [The big question... How do I do this? > Ask for help! ](#the-big-question-how-do-i-do-this---span-stylecolorredask-for-help--span)
-* [1. `MarsPull.py` - Downloading Raw MGCM Output](#1-marspullpy---downloading-raw-mgcm-output)
-* [2. `MarsFiles.py` - Files Manipulations and Reduction](#2-marsfilespy---files-manipulations-and-reduction)
-* [3. `MarsVars.py` - Performing Variable Operations](#3-marsvarspy---performing-variable-operations)
-* [4. `MarsInterp.py` - Interpolating the Vertical Grid](#4-marsinterppy---interpolating-the-vertical-grid)
-* [5. `MarsPlot.py` - Plotting the Results](#5-marsplotpy---plotting-the-results)
-* [MarsPlot.py: How to?](#marsplotpy--how-to)
- * [Inspect variable content of netCDF files](#inspect-variable-content-of-netcdf-files)
- * [Disable or add a new plot](#disable-or-add-a-new-plot)
- * [Adjust the color range and colormap](#adjust-the-color-range--and-colormap)
- * [Make a 1D-plot](#make-a-1d-plot)
- * [Customize 1D plots](#customize-1d-plots)
- * [Put multiple plots on the same page](#put-multiple-plots-on-the-same-page)
- * [Put multiple 1D-plots on the same page](#put-multiple-1d-plots-on-the-same-page)
- * [Use a different start date](#use-a-different-start-date)
- * [Access simulation in a different directory](#access-simulation-in-a-different-directory)
- * [Overwrite the free dimensions.](#overwrite-the-free-dimensions)
- * [Element-wise operations](#element-wise-operations)
- * [Code comments and speed-up processing](#code-comments-and-speed-up-processing)
- * [Change projections](#change-projections)
- * [Figure format, size](#figure-format-size)
- * [Access CAP libraries and make your own plots](#access-cap-libraries-and-make-your-own-plots)
- * [Debugging](#debugging)
-
-
-***
-
-
-
-CAP is a toolkit designed to simplify the post-processing of MGCM output. CAP is written in Python and works with existing Python libraries, allowing any Python user to install and use CAP easily and free of charge. Without CAP, plotting MGCM output requires that a user provide their own scripts for post-processing, including code for interpolating the vertical grid, computing and adding derived variables to files, converting between file types, and creating diagnostic plots. In other words, a user would be responsible for the entire post-processing effort as illustrated in Figure 1.
-
-
-
-Such a process requires that users be familiar with Fortran files and be able to write (or provide) script(s) to perform file manipulations and create plots. CAP standardizes the post-processing effort by providing executables that can perform file manipulations and create diagnostic plots from the command line. This enables users of almost any skill level to post-process and plot MGCM data (Figure 2).
-
-
-
-
-As a foreword, we will list a few design characteristics of CAP:
-
-* CAP is written in **Python**, an open-source programming language with extensive scientific libraries available
-* CAP is installed within a Python **virtual environment**, which provides cross-platform support (MacOS, Linux and Windows), robust version control (packages updated within the main Python distribution will not affect CAP), and is not intrusive as it disappears when deactivated
-* CAP is composed of a **set of libraries** (functions), callable from a user's own scripts and a collection of **five executables**, which allows for efficient processing of model outputs from the command-line.
-* CAP uses the **netCDF4 data format**, which is widely used in the climate modeling community and self-descriptive (meaning that a file contains explicit information about its content in term of variables names, units etc...)
-* CAP uses a convention for output formatting inherited from the GFDL Finite-Volume Cubed-Sphere Dynamical Core, referred here as "**FV3 format**": outputs may be binned and averaged in time in various ways for analysis.
-* CAP's long-term goal is to offer **multi-model support**. At the time of the writing, both the NASA Ames Legacy GCM and the NASA Ames GCM with the FV3 dynamical core are supported. Efforts are underway to offer compatibility to others Global Climate Models (e.g. eMARS, LMD, MarsWRF).
-
-
-Specifically, CAP consists of five executables:
-
-1. `MarsPull.py` Access MGCM output
-2. `MarsFiles.py` Reduce the files
-3. `MarsVars.py` Perform variable operations
-4. `MarsInterp.py` Interpolate the vertical grid
-5. `MarsPlot.py` Visualize the MGCM output
-
-
-These executables and their commonly-used functions are illustrated in the cheat sheet below in the order in which they are most often used. You should feel free to reference the cheat sheet during and after the tutorial.
-
-# Cheat sheet
-
-
-
-CAP is designed to be modular. For example, a user could post-process and plot MGCM output exclusively with CAP or a user could employ their own post-processing routine and then use CAP to plot the data. Users are free to selectively integrate CAP into their own analysis routine to the extent they see fit.
-
-
-
-***
-# The big question... How do I do this? > Ask for help!
-Use the `--help` (`-h` for short) option on any executable to display documentation and examples.
-
-```
-(amesCAP)>$ MarsPlot.py -h
-> usage: MarsPlot.py [-h] [-i INSPECT_FILE] [-d DATE [DATE ...]] [--template]
-> [-do DO] [-sy] [-o {pdf,eps,png}] [-vert] [-dir DIRECTORY]
-> [--debug]
-> [custom_file]
-```
-
-
-***
-
-# 1. `MarsPull.py` - Downloading Raw MGCM Output
-
-`MarsPull` is a utility for accessing MGCM output files hosted on the [MCMC Data Portal](https://data.nas.nasa.gov/mcmcref/index.html). `MarsPull` uses simulation identifiers (`-id` flag) to point to various sub-directories on the MCMC data portal, and then automates the downloading of files within those sub-directories. `MarsPull` is most useful to download simulations that contain a large number of outputs. Additionally, for Legacy GCM files, `MarsPull` allows users to request a file at a specific Ls (or for a range of Ls) using the `-ls` flag.
-
-
-```bash
-MarsPull.py -id FV3BETAOUT1 -f 03340.fixed.nc 03340.atmos_average.nc #using file names with -f flag
-MarsPull.py -id INERTCLDS -ls 255 285 #LEGACY ONLY, using solar longitude
-```
-
-[Back to Top](#cheat-sheet)
-***
-
-# 2. `MarsFiles.py` - Files Manipulations and Reduction
-
-`MarsFiles` provides several tools for file manipulations, file reduction, filtering and data from MGCM outputs.
-
-Files generated by the NASA Ames MGCM, will natively be in the Netcdf4 data format, with different (runscript-customizable) binning options: `average`, `daily` and `diurn` and `fixed`
-
-| File name | Description |Timesteps for 10 sols x 24 output/sol |Ratio to daily file |
-|-----------|------------------------------------------------|----------------------------------------------- | --- |
-|**atmos_daily.nc** | continuous time series | (24 x 10)=240 | 1 |
-|**atmos_diurn.nc** | data binned by time of day and 5-day averaged | (24 x 2)=48 | x5 smaller |
-|**atmos_average.nc** | 5-day averages | (1 x 2) = 2 | x80 smaller |
-|**fixed.nc** | statics variable such as surface albedo and topography | static |few kB |
-
-
-`MarsFiles` provides several functions to perform *data reduction*:
-
-* Create **multi-day averages** of contineous time-series: `--bin_average` flag
-* Create **diurnal composites** of contineous time-series: `--bin_diurn` flag
-* Extract **specific seasons** from `average`, `daily` and `diurn` file: `--split`
-* Combine **multiple** `average`, `daily` and `diurn` files as one :`--combine`
-* Create **zonally-averaged** files: `--zonal_average` flag
-
-
-
-`MarsFiles` provides several functions to alter the spatio-temporal of the files:
-
-
-* Perform **tidal analysis** (e.g. diurnal, semi-diurnal components) on diurnal composites files: `--tidal` flag
-* Apply **temporal filters** to time-varying fields: low pass (`-lpf`), high-pass (`-hpf`) and band-pass (`-bpf`) flags
-* **Regrid** a file to a different spatio/temporal grid : `--regrid_source` flag
-* **Time shifting** diurnal composite files to the same universal local time (e.g. 3pm everywhere): `--tshift` flag
-
->For all the operations mentioned above, the user has the option of processing all, or only a select number of variables within the file (`--include var1 var2 ...` flag )
-
-
-Time shifting allows for the interpolation of diurnal composite files to the same local times at all longitudes. This is useful to compare with orbital datasets which often provides two (e.g. 3am and 3pm) local times.
-
-```bash
-(AmesCAP)>$ MarsFiles.py *.atmos_diurn.nc --tshift
-(AmesCAP)>$ MarsFiles.py *.atmos_diurn.nc --tshift '3. 15.'
-```
-
-*3pm surface temperature before (left) and after (right) processing a diurn file with MarsFile to uniform local time (`diurn_T.nc`)*
-
-
-[Back to Top](#cheat-sheet)
-***
-
-# 3. `MarsVars.py` - Performing Variable Operations
-
-`MarsVars` provides several tools relating to variable operations such as adding and removing variables, and performing column integrations. With no other arguments, passing a file to `MarsVars` displays file content, much like `ncdump`:
-
-```bash
-(amesCAP)>$ MarsVars.py 00000.atmos_average.nc
->
-> ===================DIMENSIONS==========================
-> ['bnds', 'time', 'lat', 'lon', 'pfull', 'scalar_axis', 'phalf']
-> (etc)
-> ====================CONTENT==========================
-> pfull : ('pfull',)= (30,), ref full pressure level [Pa]
-> temp : ('time', 'pfull', 'lat', 'lon')= (4, 30, 180, 360), temperature [K]
-> (etc)
-```
-
-A typical option of `MarsVars` would be to add the atmospheric density `rho` to a file. Because the density is easily computed from the pressure and temperature fields, we do not archive in the GCM output and instead provides a utility to add it as needed. This conservative approach to logging output allows for the minimization of disk space and speed-up post processing.
-
-
-```bash
-(amesCAP)>$ MarsVars.py 00000.atmos_average.nc -add rho
-```
-
-We can see that `rho` was added by calling `MarsVars` with no argument as before:
-
-```bash
-(amesCAP)>$ MarsVars.py 00000.atmos_average.nc
->
-> ===================DIMENSIONS==========================
-> ['bnds', 'time', 'lat', 'lon', 'pfull', 'scalar_axis', 'phalf']
-> (etc)
-> ====================CONTENT==========================
-> pfull : ('pfull',)= (30,), ref full pressure level [Pa]
-> temp : ('time', 'pfull', 'lat', 'lon')= (4, 30, 180, 360), temperature [K]
-> rho : ('time', 'pfull', 'lat', 'lon')= (4, 30, 180, 360), density (added postprocessing) [kg/m3]
-```
-
-The `help` (`-h`) option provides information on available variables and needed fields for each operation.
-
-
-
-`MarsVars` also offers the following variable operations:
-
-
-| Command | flag| action|
-|-----------|-----|-------|
-|add | -add | add a variable to the file|
-|remove |-rm| remove a variable from a file|
-|extract |-extract | extract a list of variables to a new file |
-|col |-col | column integration, applicable to mixing ratios in [kg/kg] |
-|zdiff |-zdiff |vertical differentiation (e.g. compute gradients)|
-|zonal_detrend |-zd | zonally detrend a variable|
-|edit |-edit | change a variable's name, attributes or scale|
-
-This is an example of how one can edit a Netcdf's variable using CAP.
-
-```bash
-(AmesCAP)>$ MarsVars.py *.atmos_average.nc --edit temp -rename airtemp
-(AmesCAP)>$ MarsVars.py *.atmos_average.nc --edit ps -multiply 0.01 -longname 'new pressure' -unit 'mbar'
-```
-
-
-[Back to Top](#cheat-sheet)
-***
-
-# 4. `MarsInterp.py` - Interpolating the Vertical Grid
-
-Native MGCM output files use a terrain-following pressure coordinate as the vertical coordinate (`pfull`), which means the geometric heights and the actual mid-layer pressure of atmospheric layers vary based on the location (i.e. between adjacent grid points). In order to do any rigorous spatial averaging, it is therefore necessary to interpolate each vertical column to a same standard pressure (`_pstd`) grid:
-
-
-
-*Pressure interpolation from the reference pressure grid to a standard pressure grid*
-
-`MarsInterp` is used to perform the vertical interpolation from *reference* (`pfull`) layers to *standard* (`pstd`) layers:
-
-```bash
-(amesCAP)>$ MarsInterp.py 00000.atmos_average.nc
-```
-
-An inspection of the file shows that the pressure level axis which was `pfull` (30 layers) has been replaced by a standard pressure coordinate `pstd` (36 layers), and all 3- and 4-dimensional variables reflect the new shape:
-
-```bash
-(amesCAP)>$ MarsInterp.py 00000.atmos_average.nc
-(amesCAP)>$ MarsVars.py 00000.atmos_average_pstd.nc
->
-> ===================DIMENSIONS==========================
-> ['bnds', 'time', 'lat', 'lon', 'scalar_axis', 'phalf', 'pstd']
-> ====================CONTENT==========================
-> pstd : ('pstd',)= (36,), pressure [Pa]
-> temp : ('time', 'pstd', 'lat', 'lon')= (4, 36, 180, 360), temperature [K]
-```
-
-`MarsInterp` support 3 types of vertical interpolation, which may be selected by using the `--type` (`-t` for short) flag:
-
-| file type | description | low-level value in a deep crater
-|-----------|-----------|--------|
-|_pstd | standard pressure [Pa] (default) | 1000Pa
-|_zstd | standard altitude [m] | -7000m
-|_zagl | standard altitude above ground level [m] | 0 m
-
-***
-
-**Use of custom vertical grids**
-
-`MarsInterp` uses default grids for each of the interpolation listed above but it is possible for the user to specify the layers for the interpolation. This is done by editing a **hidden** file `.amescap_profile`( note the dot '`.`' ) in your home directory.
-
-For the first use, you will need to copy a template of `amescap_profile` to your /home directory:
-
-```bash
-(amesCAP)>$ cp ~/amesCAP/mars_templates/amescap_profile ~/.amescap_profile # Note the dot '.' !!!
-```
-You can open `~/.amescap_profile` with any text editor:
-
-```
-> <<<<<<<<<<<<<<| Pressure definitions for pstd |>>>>>>>>>>>>>
-
->p44=[1.0e+03, 9.5e+02, 9.0e+02, 8.5e+02, 8.0e+02, 7.5e+02, 7.0e+02,
-> 6.5e+02, 6.0e+02, 5.5e+02, 5.0e+02, 4.5e+02, 4.0e+02, 3.5e+02,
-> 3.0e+02, 2.5e+02, 2.0e+02, 1.5e+02, 1.0e+02, 7.0e+01, 5.0e+01,
-> 3.0e+01, 2.0e+01, 1.0e+01, 7.0e+00, 5.0e+00, 3.0e+00, 2.0e+00,
-> 1.0e+00, 5.0e-01, 3.0e-01, 2.0e-01, 1.0e-01, 5.0e-02, 3.0e-02,
-> 1.0e-02, 5.0e-03, 3.0e-03, 5.0e-04, 3.0e-04, 1.0e-04, 5.0e-05,
-> 3.0e-05, 1.0e-05]
->
->phalf_mb=[50]
-```
-In the example above, the user custom-defined two vertical grids, one with 44 levels (named `p44`) and one with a single layer at 50 Pa =0.5mbar(named `phalf_mb`)
-
-You can use these by calling `MarsInterp` with the `-level` (`-l`) argument followed by the name of the new grid defined in `.amescap_profile`.
-
-```bash
-(amesCAP)>$ MarsInterp.py 00000.atmos_average.nc -t pstd -l p44
-```
-[Back to Top](#cheat-sheet)
-***
-
-# 5. `MarsPlot.py` - Plotting the Results
-
-
-
-The last component of CAP is the plotting routine, `MarsPlot`, which accepts a modifiable template (`Custom.in`) containing a list of plots to create. `MarsPlot` is useful for creating plots from MGCM output quickly, and it is designed specifically for use with the `netCDF` output files (`daily`, `diurn`, `average`, `fixed`).
-
-The following figure shows the three components of MarsPlot:
-- *MarsPlot.py*, opened in **a terminal** to inspect the netcdf files and ingest the Custom.in template
-- *Custom.in* , a template opened in **a text editor**
-- *Diagnostics.pdf*, refreshed in a **pdf viewer**
-
-
-
-
-Within the terminal, MarsPlot's `--inspect` (`-i` for short) command is used to display the content of the netCDF file and select variables to be plotted.
-
-```bash
-(amesCAP)> MarsPlot.py -i 07180.atmos_average.nc
-
-> ===================DIMENSIONS==========================
-> ['lat', 'lon', 'pfull', 'phalf', 'zgrid', 'scalar_axis', 'time']
-> [...]
-> ====================CONTENT==========================
-> pfull : ('pfull',)= (24,), ref full pressure level [Pa]
-> temp : ('time', 'pfull', 'lat', 'lon')= (10, 24, 36, 60), temperature [K]
-> ucomp : ('time', 'pfull', 'lat', 'lon')= (10, 24, 36, 60), zonal wind [m/sec]
-> [...]
-```
-> Note that the `-i` method works with any netCDF file, not just the ones generated by CAP
-
-In the command listed above, we can see that the 4-dimensional arrays `temp` and `ucomp` are available in the output file. The choices of variables and the type of cross-sections to be plotted for the analysis are made through the use of a template.
-
-The default template, Custom.in, can be created by passing the `-template` argument to `MarsPlot`. Custom.in is pre-populated to draw two plots on one page: a topographical plot from the fixed file and a cross-section of the zonal wind from the average file. Creating the template and passing it into `MarsPlot` creates a PDF containing the plots:
-
-```
-(amesCAP)>$ MarsPlot.py -template
-> /path/to/simulation/run_name/history/Custom.in was created
-(amesCAP)>$
-(amesCAP)>$ MarsPlot.py Custom.in
-> Reading Custom.in
-> [----------] 0 % (2D_lon_lat :fixed.zsurf)
-> [#####-----] 50 % (2D_lat_lev :atmos_average.ucomp, Ls= (MY 2) 252.30, zonal avg)
-> [##########]100 % (Done)
-> Merging figures...
-> /path/to/simulation/run_name/history/Diagnostics.pdf was generated
-```
-
-Specifically MarsPlot is designed to generate 2D cross - sections and 1D plots.
-Let's remind ourselves that in order to create such plots from a **multi-dimensional** dataset, we first need to specify the **free** dimensions, meaning the ones that are **not** plotted.
-
-
-
-
-*A refresher on cross-section for multi-dimensional datasets*
-
-The data selection process to make any particular cross section is shown in the decision tree below. If an effort to make the process of generating multiple plots as **streamlined** as possible, MarsPlot selects a number of default settings for the user.
-
-```
-1. Which simulation ┌─
- (e.g. path_to_sim/ directory) │ DEFAULT 1. ref> is current directory
- │ │ SETTINGS
- └── 2. Which XXXXX start date │ 2. latest XXXXX.fixed in directory
- (e.g. 00668, 07180) └─
- │ ┌─
- └── 3. Which type of file │
- (e.g. diurn, average_pstd) │ USER 3. provided by user
- │ │ PROVIDES
- └── 4. Which variable │ 4. provided by user
- (e.g. temp, ucomp) └─
- │ ┌─
- └── 5. Which dimensions │ 5. see rule table below
- (e.g lat =0°,Ls =270°) │ DEFAULT
- │ │ SETTINGS
- └── 6. plot customization │ 6. default settings
- (e.g. colormap) └─
-
-```
-
-The free dimensions are set by default using day-to-day decisions from a climate modeler's perspective:
-
-
-|Free dimension|Statement for default setting|Implementation|
-|--|------|---------------|
-|time |"*I am interested in the most recent events*" |time = Nt (last timestep)|
-|level|"*I am more interested in the surface than any other vertical layer*" |level = sfc|
-|latitude |"*If I have to pick a particular latitude, I would rather look at the equator*" |lat=0 (equator)|
-|longitude |"*I am more interested in a zonal average than any particular longitude*" |lon=all (average over all values)|
-|time of day| "*3pm =15hr Ok, this one is arbitrary. However if I use a diurn file, I have a specific time of day in mind*" |tod=15 |
-
-*Rule table for the default settings of the free dimensions*
-
-In practice, these cases cover 99% of the work typically done so whenever a setting is left to default (`= None` in MarsPlot's syntax) this is what is being used. This allows us to considerably streamline the data selection process.
-
-`Custom.in` can be modified using your preferred text editor (and renamed to your liking). This is an example of the code snippet in `Custom.in` used to generate a lon/lat cross-section. Note that the heading is set to `= True`, so that plot is activated for MarsPlot to process.
-
-```python
-<<<<<<<<<<<<<<| Plot 2D lon X lat = True |>>>>>>>>>>>>>
-Title = None
-Main Variable = atmos_average.temp
-Cmin, Cmax = None
-Ls 0-360 = None
-Level [Pa/m] = None
-2nd Variable = None
-Contours Var 2 = None
-Axis Options : lon = [None,None] | lat = [None,None] | cmap = jet | scale = lin | proj = cart
-
-```
-In the example above, we are plotting the air temperature field `temp` from the *atmos_average.nc* file as a lon/lat map. `temp` is a 4D field *(time, level, lat, lon)* but since we left the time (`Ls 0-360`) and altitude (`Level [Pa/m]`) unspecified (i.e. set to `None`) MarsPlot will show us the *last timestep* in the file and the layer immediately adjacent to the *surface*. Similarly, MarsPlot will generate a *default title* for the figure with the variable's name (`temperature`), unit (`[K]`), selected dimensions (`last timestep, at the surface`), and makes educated choices for the range of the colormap, axis limits etc ... All those options are customizable, if desired. Finally, note the option of adding a secondary variable as **solid contours**. For example, one may set `2nd Variable = fixed.zsurf` to plot the topography (`zsurf`) from the matching *XXXXX.fixed.nc* file.
-
-To wrap-up (the use of `{}` to overwrite default settings is discussed later on), the following two working expressions are strictly equivalent for `Main Variable = ` (shaded contours) or `2nd Variable = ` (solid contours) fields:
-
-```python
- variable variable
- │ SIMPLIFY TO │
-00668.atmos_average@1.temp{lev=1000;ls=270} >>> atmos_average.temp
- │ │ │ │ │
-start file type simulation free dimensions file type
-date directory
-```
-These are the four types of accepted entries for the free dimensions:
-
-
-|Accepted input |Meaning| Example|
-|-- |--- |-- |
-|`None` |Use default settings from the rule table above| `Ls 0-360 = None`|
-|`value`| Return index closest to requested value in the figure'sunit |`Level [Pa/m] = 50 ` (50 Pa)|
-|`Val Min, Val Max`| Return the average between two values |`Lon +/-180 = -30,30`|
-|`all`| `all` is a special keyword that return the average over all values along that dimension |`Latitude = all`|
-
-*Accepted values for the `Ls 0-360`, `Level [Pa/m]` ,`Lon +/-180`, `Latitude` and time of day free dimensions*
-
-> The time of day (`tod`) in diurn files is always specified using brackets`{}`, e.g. : `Main Variable = atmos_diurn.temp{tod=15,18}` for the average between 3pm and 6pm. This has allowed to streamlined all templates by not including the *time of day* free dimension, which is specific to diurn files.
-
-
-
-
-# MarsPlot.py: How to?
-
-This section discusses MarsPlot capabilities. Note that a compact version of these instructions are present as comment at the very top of a new `Custom.in` and can be used as a quick reference:
-```python
-===================== |MarsPlot V3.2|===================
-# QUICK REFERENCE:
-# > Find the matching template for the desired plot type. Do not edit any labels left of any '=' sign
-# > Duplicate/remove any of the <<<< blocks>>>>, skip by setting <<<< block = False >>>>
-# > 'True', 'False' and 'None' are capitalized. Do not use quotes '' anywhere in this file
-etc...
-```
-## Inspect variable content of netCDF files
-
-
-The `--inspect` method in MarsPlot.py can be combined with the `--dump` flag which is most useful to show the content of specific 1D arrays in the terminal.
-```bash
-(amesCAP)>$ MarsPlot.py -i 07180.atmos_average.nc -dump pfull
-> pfull=
-> [8.7662227e-02 2.5499690e-01 5.4266089e-01 1.0518962e+00 1.9545468e+00
-> 3.5580616e+00 6.2466631e+00 1.0509957e+01 1.7400265e+01 2.8756382e+01
-> 4.7480076e+01 7.8348366e+01 1.2924281e+02 2.0770235e+02 3.0938846e+02
-> 4.1609518e+02 5.1308148e+02 5.9254102e+02 6.4705731e+02 6.7754218e+02
-> 6.9152936e+02 6.9731799e+02 6.9994830e+02 7.0082477e+02]
-> ______________________________________________________________________
-```
-
-The `--stat` flag is better suited to inspect large, multi-dimensional arrays. You can also request specific array indexes using quotes and square brackets `'[]'`:
-
-```bash
-(amesCAP)>$ MarsPlot.py -i 07180.atmos_average.nc --stat ucomp 'temp[:,-1,:,:]'
-__________________________________________________________________________
- VAR | MIN | MEAN | MAX |
-__________________________|_______________|_______________|_______________|
- ucomp| -102.98| 6.99949| 192.088|
- temp[:,-1,:,:]| 149.016| 202.508| 251.05|
-__________________________|_______________|_______________|_______________|
-```
-> `-1` refers to the last element in the that axis, following Python's indexing convention
-
-***
-## Disable or add a new plot
-Code blocks set to `= True` instruct `MarsPlot` to draw those plots. Other templates in `Custom.in` are set to `= False` by default, which instructs `MarsPlot` to skip those plots. In total, `MarsPlot` is equipped to create seven plot types:
-
-```python
-<<<<<| Plot 2D lon X lat = True |>>>>>
-<<<<<| Plot 2D lon X time = True |>>>>>
-<<<<<| Plot 2D lon X lev = True |>>>>>
-<<<<<| Plot 2D lat X lev = True |>>>>>
-<<<<<| Plot 2D time X lat = True |>>>>>
-<<<<<| Plot 2D time X lev = True |>>>>>
-<<<<<| Plot 1D = True |>>>>> # Any 1D Plot Type (Dimension x Variable)
-```
-
-## Adjust the color range and colormap
-
-`Cmin, Cmax` (and `Contours Var 2`) are how the contours are set for the shaded (and solid) contours. If only two values are included, MarsPlot use 24 contours spaced between the max and min values. If more than two values are provided, MarsPlot will use those individual contours.
-
-```python
-Main Variable = atmos_average.temp # filename.variable *REQUIRED
-Cmin, Cmax = 240,290 # Colorbar limits (minimum, maximum)
-2nd Variable = atmos_average.ucomp # Overplot U winds
-Contours Var 2 = -200,-100,100,200 # List of contours for 2nd Variable or CMIN, CMAX
-Axis Options : Ls = [None,None] | lat = [None,None] | cmap = jet |scale = lin
-```
-
-Note the option of setting the contour spacing linearly `scale = lin` or logarithmically (`scale = log`) if the range of values spans multiple order of magnitudes.
-
-The default colormap `cmap = jet` may be changed using any Matplotlib colormaps. A selections of those are listed below:
-
-
-
-Finally, note the use of the `_r` suffix (reverse) to reverse the order of the colormaps listed in the figure above. From example, using `cmap = jet` would have colors spanning from *blue* > *red* and `cmap = jet_r` *red* > *blue* instead
-
-*Supported colormaps in Marsplot. The figure was generated using code from [the scipy webpage](https://scipy-lectures.org/intro/matplotlib/auto_examples/options/plot_colormaps.html) .*
-
-
-***
-## Make a 1D-plot
-The 1D plot template is different from the others in a few key ways:
-
-- Instead of `Title`, the template requires a `Legend`. When overplotting several 1D variables on top of one another, the legend option will label them instead of changing the plot title.
-- There is an additional `linestyle` axis option for the 1D plot.
-- There is also a `Diurnal` option. The `Diurnal` input can only be `None` or `AXIS`, since there is syntax for selecting a specific time of day using parenthesis (e.g. `atmos_diurn.temp{tod=15}`) The `AXIS` label tells `MarsPlot` which dimension serves as the X axis. `Main Variable` will dictate the Y axis.
-
-> Some plots like vertical profiles and latitude plots use instead Y as the primary axis and plot the variable on the X axis
-
-```python
-<<<<<<<<<<<<<<| Plot 1D = True |>>>>>>>>>>>>>
-Legend = None # Legend instead of Title
-Main Variable = atmos_average.temp
-Ls 0-360 = AXIS # Any of these can be selected
-Latitude = None # as the X axis dimension, and
-Lon +/-180 = None # the free dimensions can accept
-Level [Pa/m] = None # values as before. However,
-Diurnal [hr] = None # ** Diurnal can ONLY be AXIS or None **
-```
-
-## Customize 1D plots
-`Axis Options` specify the axes limits, and linestyle 1D-plot:
-
-|1D plot option |Usage| Example|
-|----|----|----|
-|`lat,lon+/-180,[Pa/m],sols = [None,None]` |range for X or Y axes limit depending on the plot type|`lat,lon+/-180,[Pa/m],sols = [1000,0.1]`|
- |`var = [None,None]` | range for the plotted variable on the other axis | `var = [120,250]`|
- |`linestyle = - ` |Line style following matplotlib's convention| `linestyle = -ob` (solid line & blue circular markers)|
- |`axlabel = None` | Change the default name for the axis| `axlabel = New Temperature [K]`
-
-Here is a sample of colors, linestyles and marker styles that can be used in 1D-plots
-
-
-
-*Supported styles for 1D plots. This figure was also generated using code from [scipy-lectures.org](https://scipy-lectures.org)*
-
-***
-## Put multiple plots on the same page
-
-You can sandwich any number of plots between the `HOLD ON` and `HOLD OFF` keywords to group figures on the same page.
-
-```
-> HOLD ON
->
-> <<<<<<| Plot 2D lon X lat = True |>>>>>>
-> Title = Surface CO2 Ice (g/m2)
-> .. (etc) ..
->
-> <<<<<<| Plot 2D lon X lat = True |>>>>>>
-> Title = Surface Wind Speed (m/s)
-> .. (etc) ..
->
-> HOLD OFF
-```
-
-By default, MarsPlot will use a default layout for the plots, this can be modified by adding the desired number of lines and number of columns, separated by a comma: `HOLD ON 4,3` will organize the figure with a 4 -lines and 3-column layout.
-
-Note that Custom.in comes with two plots pre-loaded on the same page.
-***
-## Put multiple 1D-plots on the same page
-
-Similarly adding the `ADD LINE` keywords between two (or more) templates can be used to place multiple 1D plots on the same figure.
-
-```
-> <<<<<<| Plot 1D = True |>>>>>>
-> Main Variable = var1
-> .. (etc) ..
->
-> ADD LINE
->
-> <<<<<<| Plot 1D = True |>>>>>>
-> Main Variable = var2
-> .. (etc) ..
-```
-
-> Note that if you combine `HOLD ON/HOLD OFF` and `ADD LINE` to create a 1D figure with several sub-plots on a **multi-figure page**, the 1D plot has to be the LAST (and only 1D-figure with sub-plots) on that page.
-***
-## Use a different start date
-
-If you have run a GCM simulation for a long time, you may have several files of the same type, e.g. :
-
-```
-00000.fixed.nc 00100.fixed.nc 00200.fixed.nc 00300.fixed.nc
-00000.atmos_average.nc 00100.atmos_average.nc 00200.atmos_average.nc 00300.atmos_average.nc
-```
-By default MarsPlot counts the `fixed` files in the directory and run the analysis on the last set of files, `00300.fixed.nc` and `00300.atmos_average.nc` in our example. Even though you may specify the start date for each plot (e.g. `Main Variable = 00200.atmos_average.temp` for the file starting at 200 sols), it is more convenient to leave the start date out of the Custom.in and instead pass the `-date` argument to MarsPlot.
-
-```bash
-MarsPlot.py Custom.in -d 200
-```
-
-> `-date` also accepts a range of sols, e.g. `MarsPlot.py Custom.in -d 100 300` which will run the plotting routine across multiple files.
-
-When creating 1D plots of data spanning multiple years, you can overplot consecutive years on top of the other instead of sequentially by calling `--stack_year` (`-sy`) when submitting the template to `MarsPlot`.
-
-
-
-***
-## Access simulation in a different directory
-At the beginning of `MarsPlot` is the `<<< Simulations >>>` block which, is used to point `MarsPlot` to different directories containing MGCM outputs. When set to `None`, `ref>` (the simulation directory number `@1`, optional in the templates) refers to the **current** directory:
-
-```python
-<<<<<<<<<<<<<<<<<<<<<< Simulations >>>>>>>>>>>>>>>>>>>>>
-ref> None
-2> /path/to/another/sim # another simulation
-3>
-=======================================================
-```
-Only 3 simulations have place holders but you can add additional ones if you would like (e.g. `4> ...` )
-To access a variable from a file in another directory, just point to the correct simulation when calling `Main Variable` (or `2nd Variable`) using the `@` character:
-
-```python
-Main Variable = XXXXX.filename@N.variable`
-```
-
-Where `N` is the number in `<<< Simulations >>>` corresponding the the correct path.
-
-***
-## Overwrite the free dimensions.
-
-By default, MarsPlot uses the free dimensions provided in each template (`Ls 0-360` and `Level [Pa/m]` in the example below) to reduce the data for both the `Main Variable` and the `2nd Variable`. You can overwrite this behavior by using parenthesis `{}`, containing a list of specific free dimensions separated by semi-colons `;` The free dimensions within the `{}` parenthesis will ultimately be the last one selected. In the example below, `Main Variable` (shaded contours) will use a solar longitude of 270° and a pressure of 10 Pa, but the `2nd Variable` (solid contours) will use the average of solar longitudes between 90° and 180° and a pressure of 50 Pa.
-
-```python
-<<<<<<<<<<<<<<| Plot 2D lon X lat = True |>>>>>>>>>>>>>
-...
-Main Variable = atmos_average.var
-...
-Ls 0-360 = 270
-Level [Pa/m] = 10
-2nd Variable = atmos_average.var{ls=90,180;lev=50}
-```
-> Keywords for the dimensions are `ls`, `lev`, `lon`, `lat` and `tod`. Accepted entries are `Value` (closest), `Valmin,Valmax` (average between two values) and `all` (average over all values)
-## Element-wise operations
-
-You can encompass variables between square brackets `[]` to perform element-wise operations, which is useful to compare simulations, apply scaling etc... MarsPlot will first load each variables encompassed with the brackets, and then apply the algebraic expression outside the `[]` before plotting.
-
-These are examples of potential applications:
-
-
-```
- > Main Variable = [fixed.zsurf]/(10.**3) (convert topography from [m] to [km])
- > Main Variable = [atmos_average.taudust_IR]/[atmos_average.ps]*610 (normalize the dust opacity)
- > Main Variable = [atmos_average.temp]-[atmos_average@2.temp] (temp. difference between ref simu and simu 2)
- > Main Variable = [atmos_average.temp]-[atmos_average.temp{lev=10}] (temp. difference between the default (near surface) and the 10 Pa level
-```
-***
-## Code comments and speed-up processing
-
-Comments are preceded by `#`, following python's convention. Each `<<<<| block |>>>>` must stay integral so comments may be inserted between templates or comment all lines of the template (which is why it is generally easier to simply set the `<<<<| block = False |>>>>`) but not within a template.
-
-You will notice the `START` key word at the very beginning of the template.
-```
-=======================================================
-START
-```
-This instructs MarsPlot to start parsing templates at this point. If you are already happy with multiple plots, you can move the `START` keyword further down in the Custom.in to skip those first plots instead of setting those to `<<<<| Plot = False |>>>>` individually. When you are done with your analysis, simply move `START` back to the top to generate a pdf with all the plots.
-
-Similarly, you can use the keyword `STOP` (which is not initially present in Custom.in) to stop the parsing of templates. In this case, the only plots processed would be the ones between `START` and `STOP`.
-
-***
-## Change projections
-
-For `Plot 2D lon X lat` figures, MarsPlot supports 3 types of cylindrical projections : `cart` (cartesian), `robin` (robinson), `moll` (mollweide), and 3 types of azimuthal projections: `Npole` (north polar), `Spole` (south polar) and `ortho` (orthographic).
-
-
-*(Top) cylindrical projection `cart`, `robin` and `moll`. (Bottom) azimuthal projections `Npole`, `Spole` and `ortho`*
-
-The azimuthal projections accept optional arguments as follows:
-
-```
-proj = Npole lat_max # effectively zoom in/out on the North pole
-proj = Spole lat_min # effectively zoom in/out on the South pole
-proj = ortho lon_center, lat_center # rotate the globe
-```
-
-***
-## Figure format, size
-
-* As shown in the `-help` documentation of MarsPlot, the output format for the figure is chosen using the `--output` (`-o`) flag between *pdf* (default, requires the ghostscript software), *png*, or *eps*.
-* The `-pw` (pixel width) flag can be use to change the page width from its default value of 2000 pixels. This is useful to make the labels more readable on multi-panels figure with a large number of plots.
-* The `--vertical` (`-vert`) can be use to make the pages vertical instead of horizontal
-
-***
-## Access CAP libraries and make your own plots
-
-CAP libraries are located (and documented) in `amescap/FV3_utils.py`. Spectral utilities are located in `amescap/Spectral_utils.py`, classes to parse fortran binaries and generate netCDf files are located in `amescap/Ncdf_wrapper.py`
-
-The following code demonstrate how one can access CAP libraries and make plots for its own analysis:
-
-```python3
-#======================= Import python packages ================================
-import numpy as np # for array operations
-import matplotlib.pyplot as plt # python plotting library
-from netCDF4 import Dataset # to read .nc files
-#===============================================================================
-
-# Open a fixed.nc file, read some variables and close it.
-f_fixed=Dataset('/path_to_file/00000.fixed.nc','r')
-lon=f_fixed.variables['lon'][:]
-lat=f_fixed.variables['lat'][:]
-zsurf=f_fixed.variables['zsurf'][:]
-f_fixed.close()
-
-# Open a dataset and read the 'variables' attribute from the NETCDF FILE
-f_average_pstd=Dataset('/path_to_file/00000.atmos_average_pstd.nc','r')
-vars_list =f_average_pstd.variables.keys()
-print('The variables in the atmos files are: ',vars_list)
-
-# Read the 'shape' and 'units' attribute from the temperature VARIABLE
-Nt,Nz,Ny,Nx = f_average_pstd.variables['temp'].shape
-units_txt = f_average_pstd.variables['temp'].units
-print('The data dimensions are Nt,Nz,Ny,Nx=',Nt,Nz,Ny,Nx)
-# Read the pressure, time, and the temperature for an equatorial cross section
-pstd = f_average_pstd.variables['pstd'][:]
-areo = f_average_pstd.variables['areo'][0] #solar longitude for the 1st timestep
-temp = f_average_pstd.variables['temp'][0,:,18,:] #time, press, lat, lon
-f_average_pstd.close()
-
-# Get the latitude of the cross section.
-lat_cross=lat[18]
-
-# Example of accessing functions from the Ames Pipeline if we wanted to plot
-# the data in a different coordinate system (0>360 instead of +/-180 )
-#----
-from amescap.FV3_utils import lon180_to_360,shiftgrid_180_to_360
-lon360=lon180_to_360(lon)
-temp360=shiftgrid_180_to_360(lon,temp)
-
-# Define some contours for plotting
-conts= np.linspace(150,250,32)
-
-#Create a figure with the data
-plt.close('all')
-ax=plt.subplot(111)
-plt.contourf(lon,pstd,temp,conts,cmap='jet',extend='both')
-plt.colorbar()
-# Axis labeling
-ax.invert_yaxis()
-ax.set_yscale("log")
-plt.xlabel('Longitudes')
-plt.ylabel('Pressure [Pa]')
-plt.title('Temperature [%s] at Ls %03i, lat= %.2f '%(units_txt,areo,lat_cross))
-plt.show()
-```
-will produce the following image:
-
-
-
-
-***
-## Debugging
-`MarsPlot` is designed to make plotting MGCM output easier and faster so it handles missing data and many errors by itself. It reports errors both in the terminal and in the generated figures. To by-pass this behavior (when debugging), use the `--debug` option with `MarsPlot` which will raise standard Python errors and stop the execution. One thing to always look for are typo/syntax errors in the template so you may want to cross-check your current plot against a pristine (empty) template.
-> Note that the errors raised with the `--debug` flag may reference to `MarsPlot` internal classes so they may not always be self-explanatory.
-
-
-
-
-
-[Back to Top](#cheat-sheet)
-***
diff --git a/tutorial/README.md b/tutorial/README.md
deleted file mode 100644
index 059ae4d6..00000000
--- a/tutorial/README.md
+++ /dev/null
@@ -1,11 +0,0 @@
-
-
-This directory contains tutorial documents describing the installation and functionality for CAP as well as a set of practice exercises. It is a great place to start for new users.
-
-
-# 1. [Introduction to CAP and documentation of its functionalities](./CAP_lecture.md)
-# 2. [Step-by-step installation](./CAP_Install.md)
-# 3. [Practice exercises](./CAP_Exercises.md)
-
-
-(Practice exercises for the Legacy GCM are also available [on this page](./CAP_Exercises_2021.md))
diff --git a/tutorial/atom.pdf b/tutorial/atom.pdf
deleted file mode 100644
index 99da8988..00000000
Binary files a/tutorial/atom.pdf and /dev/null differ
diff --git a/tutorial/cap_tutorial_exercises_2023.code-workspace b/tutorial/cap_tutorial_exercises_2023.code-workspace
deleted file mode 100644
index 876a1499..00000000
--- a/tutorial/cap_tutorial_exercises_2023.code-workspace
+++ /dev/null
@@ -1,8 +0,0 @@
-{
- "folders": [
- {
- "path": "."
- }
- ],
- "settings": {}
-}
\ No newline at end of file
diff --git a/tutorial/git.pdf b/tutorial/git.pdf
deleted file mode 100644
index 6d58bf6b..00000000
Binary files a/tutorial/git.pdf and /dev/null differ
diff --git a/tutorial/out/CAP_Exercises.html b/tutorial/out/CAP_Exercises.html
deleted file mode 100644
index 1e35856d..00000000
--- a/tutorial/out/CAP_Exercises.html
+++ /dev/null
@@ -1,3475 +0,0 @@
-
-
-
-
-
-
-
-1. MarsPlot's
-
-
-
-
-
-5. Time-Shifting
-
-
-
-
-
-Step 1: Creating the Template (
-
-Step 2: Editing
-
-Using
-Using
-
-
-
-
-
-
-
-
- 
Practice Exercises - Community Analysis Pipeline (CAP)
-
CAP is a Python toolkit designed to simplify post-processing and plotting MGCM output. CAP consists of five Python executables:
--
-
MarsPull.py→ accessing MGCM output
-MarsFiles.py→ reducing the files
-MarsVars.py→ performing variable operations
-MarsInterp.py→ interpolating the vertical grid
-MarsPlot.py→ plotting MGCM output
-
The following exercises are organized into two parts by function. We will go through Part I on Monday Nov. 13 and Part II on Tuesday Nov. 14.
-Part I: File Manipulations → MarsFiles.py, MarsVars.py, & MarsInterp.py
Part II: Plotting with CAP → MarsPlot.py
--We will not be going over
-MarsPull.pybecause it is specifically for retrieving MGCM data from the online MGCM data repository. Instructions forMarsPull.pywas covered in the 2021 Legacy Version Tutorial.
-
Table of Contents
--
-
- Practice Exercises - Community Analysis Pipeline (CAP) - - -
- Part I: File Manipulations - - -
- Optional: Use the Answer Key for Part I -
- CAP Practical Day 2 -
- Part II: Plotting with CAP - - -
- Custom Set 1 of 4: Zonal Mean Surface Plots Over Time -
- Custom Set 2 of 4: Global Mean Column-Integrated Dust Optical Depth Over Time -
- Custom Set 3 of 4: 50 Pa Temperatures at 3 AM and 3 PM -
- Custom Set 4 of 4: Zonal Mean Circulation Cross-Sections -
-
Activating CAP
-Activate the amesCAP virtual environment to use CAP:
(cloud)~$ source ~/amesCAP/bin/activate
-(amesCAP)~$
-Confirm that CAP's executables are accessible by typing:
-(amesCAP)~$ MarsVars.py -h
-The --help [-h] argument prints documentation for the executable to the terminal. Now that we know CAP is configured, make a copy of the file amescap_profile in your home directory, and make it a hidden file:
(amesCAP)~$ cp ~/amesCAP/mars_templates/amescap_profile ~/.amescap_profile
-CAP stores useful settings in amescap_profile. Copying it to our home directory ensures it is not overwritten if CAP is updated or reinstalled.
Following Along with the Tutorial
-Part I covers file manipulations. Some exercises build off of previous exercises so it is important to complete them in order. If you make a mistake or get behind in the process, you can go back and catch up during a break or use the provided answer key before continuing on to Part II.
-Part II demonstrates CAP's plotting routine. There is more flexibility in this part of the exercise.
-We will perform every exercise together.
--- -Feel free to put questions in the chat throughout the tutorial. Another MGCM member can help you as we go.
-
Part I: File Manipulations
-CAP has dozens of post-processing capabilities. We will go over a few of the most commonly used functions in this tutorial. We will cover:
--
-
- Interpolating data to different vertical coordinate systems (
MarsInterp.py)
- - Adding derived variables to the files (
MarsVars.py)
- - Time-shifting data to target local times (
MarsFiles.py)
- - Trimming a file to reduce its size (
MarsFiles.py).
-
The required MGCM output files are already loaded in the cloud environment under tutorial_files/cap_exercises/. Change to that directory and look at the contents:
(amesCAP)~$ cd tutorial_files/cap_exercises
-(amesCAP)~$ ls
-03340.atmos_average.nc 03340.backup.zip part_1_key.sh
-03340.atmos_diurn.nc 03340.fixed.nc part_2_plots.in
-The three MGCM output files have a 5-digit sol number appended to the front of the file name. The sol number indicates the day that a file's record begins. These contain output from the sixth year of a simulation. The zipped file is an archive of these three output files in case you need it.
-The other two files, part_1_key.sh and part_2_plots.sh are discussed later. We can ignore them for now.
--The output files we manipulate in Part I will be used to generating plots in Part II so do not delete any file you create!
-
Let's begin the tutorial.
-1. MarsPlot's --inspect Function
-The inspect function is part of MarsPlot.py and it prints netCDF file contents to the screen.
To use it on the average file, 03340.atmos_average.nc, type the following in the terminal:
(amesCAP)~$ MarsPlot.py -i 03340.atmos_average.nc
--- -This is a good time to remind you that if you are unsure how to use a function, invoke the
---help [-h]argument with any executable to see its documentation (e.g.,MarsPlot.py -h).
-
2. Editing Variable Names and Attributes
-In the previous exercise, --inspect [-i] revealed a variable called opac in 03340.atmos_average.nc. opac is dust opacity per pascal and it is similar to another variable in the file, dustref, which is opacity per (model) level. Let's rename opac to dustref_per_pa to better indicate the relationship between these variables.
We can modify variable names, units, longnames, and even scale variables using the -edit function in MarsVars.py. The syntax for editing the variable name is:
(amesCAP)~$ MarsVars.py 03340.atmos_average.nc -edit opac -rename dustref_per_pa
-03340.atmos_average_tmp.nc was created
-03340.atmos_average.nc was updated
-We can use --inspect [-i] again to confirm that opac was renamed dustref_per_pa:
(amesCAP)~$ MarsPlot.py -i 03340.atmos_average.nc
-The --inspect [-i] function can also print a summary of the values of a variable to the screen. For example:
(amesCAP)~$ MarsPlot.py -i 03340.atmos_average.nc -stat dustref_per_pa
-_________________________________________________________
- VAR | MIN | MEAN | MAX |
-________________|___________|_____________|_____________|
- dustref_per_pa| 0| 0.000384902| 0.0017573|
-________________|___________|_____________|_____________|
-Finally, --inspect [-i] can print the values of a variable to the screen. For example:
(amesCAP)~$ MarsPlot.py -i 03340.atmos_average.nc -dump lat
-lat=
-[-89. -87. -85. -83. -81. -79. -77. -75. -73. -71. -69. -67. -65. -63.
- -61. -59. -57. -55. -53. -51. -49. -47. -45. -43. -41. -39. -37. -35.
- -33. -31. -29. -27. -25. -23. -21. -19. -17. -15. -13. -11. -9. -7.
- -5. -3. -1. 1. 3. 5. 7. 9. 11. 13. 15. 17. 19. 21.
- 1. 25. 27. 29. 31. 33. 35. 37. 39. 41. 43. 45. 47. 49.
- 2. 53. 55. 57. 59. 61. 63. 65. 67. 69. 71. 73. 75. 77.
- 3. 81. 83. 85. 87. 89.]
--
3. Splitting Files in Time
-Next we're going to trim the diurn and average files by L. We'll create files that only contain data around southern summer solstice, L=270. This greatly reduces the file size to make our next post-processing steps more efficient.
Syntax for trimming files by L is:
-(amesCAP)~$ MarsFiles.py 03340.atmos_diurn.nc -split 265 275
-...
-/home/centos/tutorial_files/cap_exercises/03847.atmos_diurn_Ls265_275.nc was created
-(amesCAP)~$ MarsFiles.py 03340.atmos_average.nc -split 265 275
-...
-/home/centos/tutorial_files/cap_exercises/03847.atmos_average_Ls265_275.nc was created
-The trimmed files have the appendix _Ls265_275.nc and the simulation day has changed from 03340 to 03847 to reflect that the first day in the file has changed.
For future steps, we need a fixed file with the same simulation day number as the files we just created, so make a copy of the fixed file and rename it:
(amesCAP)~$ cp 03340.fixed.nc 03847.fixed.nc
--
Break
-Take 15 minutes to stretch, ask questions, or let us know your thoughts on CAP so far!
--
4. Deriving Secondary Variables
-The --add function in MarsVars.py derives and adds secondary variables to MGCM output files provided that the variable(s) required for the derivation are already in the file. We will add the meridional mass streamfunction (msf) to the trimmed average file. To figure out what we need in order to do this, use the --help [-h] function on MarsVars.py:
(amesCAP)~$ MarsVars.py -h
-The help function shows that streamfunction (msf) requires two things: that the meridional wind (vcomp) is in the average file, and that the average file is pressure-interpolated.
First, confirm that vcomp is in 03847.atmos_average_Ls265_275.nc using --inspect [-i]:
(amesCAP)~$ MarsPlot.py -i 03847.atmos_average_Ls265_275.nc
-...
-vcomp : ('time', 'pfull', 'lat', 'lon')= (3, 56, 90, 180), meridional wind [m/sec]
-Second, pressure-interpolate the average file using MarsInterp.py. The call to MarsInterp.py requires:
-
-
- The interpolation type (
--type [-t]), we will use standard pressure coorindates (pstd)
- - The grid to interpolate to (
--level [-l]), we will use the default pressure grid (pstd_default)
-
--All interpolation types are listed in the
---help [-h]documentation forMarsInterp.py. Additional grids are listed in~/.amescap_profile, which accepts user-input grids as well.
We will also specify that only temperature (temp), winds (ucomp and vcomp), and surface pressure (ps) are to be included in this new file using -include. This will reduce the interpolated file size.
Finally, add the --grid [-g] flag at the end of prompt to print out the standard pressure grid levels that we are interpolating to:
(amesCAP)~$ MarsInterp.py 03847.atmos_average_Ls265_275.nc -t pstd -l pstd_default -include temp ucomp vcomp ps -g
-1100.0 1050.0 1000.0 950.0 900.0 850.0 800.0 750.0 700.0 650.0 600.0 550.0 500.0 450.0 400.0 350.0 300.0 250.0 200.0 150.0 100.0 70.0 50.0 30.0 20.0 10.0 7.0 5.0 3.0 2.0 1.0 0.5 0.3 0.2 0.1 0.05
-To perform the interpolation, simply omit the --grid [-g] flag:
(amesCAP)~$ MarsInterp.py 03847.atmos_average_Ls265_275.nc -t pstd -l pstd_default -include temp ucomp vcomp ps
-...
-/home/centos/tutorial_files/cap_exercises/03847.atmos_average_Ls265_275_pstd.nc was created
-Now we have a pressure-interpolated average file with vcomp in it. We can derive and add msf to it using MarsVars.py:
(amesCAP)~$ MarsVars.py 03847.atmos_average_Ls265_275_pstd.nc -add msf
-Processing: msf...
-msf: Done
--
5. Time-Shifting Diurn Files
-The diurn file is organized by time-of-day assuming universal time starting at the Martian prime meridian. The time-shift --tshift [-t] function interpolates the diurn file to uniform local time. This is especially useful when comparing MGCM output to satellite observations in fixed local time orbit.
Time-shifting can only be done on files with a local time dimension (time_of_day_24, i.e. diurn files). By default, MarsFiles.py time shifts all of the data in the file to 24 uniform local times and this generates very large files. To reduce file size and processing time, we will time-shift the data only to the local times we are interested in: 3 AM and 3 PM.
Time-shift the temperature (temp) and surface pressure (ps) in the trimmed diurn file to 3 AM / 3 PM local time like so:
(amesCAP)~$ MarsFiles.py 03847.atmos_diurn_Ls265_275.nc -t '3. 15.' -include temp ps
-...
-/home/centos/tutorial_files/cap_exercises/03847.atmos_diurn_Ls265_275_T.nc was created
-A new diurn file called 03847.atmos_diurn_Ls265_275_T.nc is created. Use --inspect [-i] to confirm that only ps and temp (and their dimensions) are in the file and that the time_of_day dimension has a length of 2:
(amesCAP)~$ MarsPlot.py -i 03847.atmos_diurn_Ls265_275_T.nc
-...
-====================CONTENT==========================
-time : ('time',)= (3,), sol number [days since 0000-00-00 00:00:00]
-time_of_day_02 : ('time_of_day_02',)= (2,), time of day [[hours since 0000-00-00 00:00:00]]
-pfull : ('pfull',)= (56,), ref full pressure level [mb]
-scalar_axis : ('scalar_axis',)= (1,), none [none]
-lon : ('lon',)= (180,), longitude [degrees_E]
-lat : ('lat',)= (90,), latitude [degrees_N]
-areo : ('time', 'time_of_day_02', 'scalar_axis')= (3, 2, 1), areo [degrees]
-ps : ('time', 'time_of_day_02', 'lat', 'lon')= (3, 2, 90, 180), surface pressure [Pa]
-temp : ('time', 'time_of_day_02', 'pfull', 'lat', 'lon')= (3, 2, 56, 90, 180), temperature [K]
-=====================================================
--
6. Pressure-Interpolating the Vertical Axis
-Now we can efficiently interpolate the diurn file to the standard pressure grid. Recall that interpolation is part of MarsInterp.py and requires:
-
-
- Interpolation type (
--type [-t]), and
- - Grid (
--level [-l])
-
As before, we will interpolate to standard pressure (pstd) using the default pressure grid in .amesgcm_profile (pstd_default):
(amesCAP)~$ MarsInterp.py 03847.atmos_diurn_Ls265_275_T.nc -t pstd -l pstd_default
-...
-/home/centos/tutorial_files/cap_exercises/03847.atmos_diurn_Ls265_275_T_pstd.nc was created
---Note: Interpolation could be done before or after time-shifting, the order does not matter.
-
We now have four different diurn files in our directory:
03340.atmos_diurn.nc # Original MGCM file
-03847.atmos_diurn_Ls265_275.nc # + Trimmed to Ls=265-275
-03847.atmos_diurn_Ls265_275_T.nc # + Time-shifted; `ps` and `temp` only
-03847.atmos_diurn_Ls265_275_T_pstd.nc # + Pressure-interpolated
-CAP always adds an appendix to the name of any new file it creates. This helps users keep track of what was done and in what order. The last file we created was trimmed, time-shifted, then pressure-interpolated. However, the same file could be generated by performing the three functions in any order.
- -Optional: Use the Answer Key for Part I
-This concludes Part I of the tutorial! If you messed up one of the exercises somewhere, you can run the part_1_key.sh script in this directory. It will delete the files you've made and performs all 6 Exercises in Part I for you. To do this, follow the steps below.
-
-
- Source the
amesCAPvirtual environment
- - Change to the
tutorial_files/cap_exercises/directory
- - Run the executable: -
(amesCAP)~$ ./part_1_key.sh
-The script will do all of Part I for you. This ensures you can follow along with the plotting routines in Part II.
- -CAP Practical Day 2
-This part of the CAP Practical covers how to generate plots with CAP. We will take a learn-by-doing approach, creating five sets of plots that demonstrate some of CAP's most often used plotting capabilities:
--
-
- Custom Set 1 of 4: Zonal Mean Surface Plots Over Time -
- Custom Set 2 of 4: Global Mean Column-Integrated Dust Optical Depth Over Time -
- Custom Set 3 of 4: 50 Pa Temperatures at 3 AM and 3 PM -
- Custom Set 4 of 4: Zonal Mean Circulation Cross-Sections -
Plotting with CAP is done in 3 steps:
-Step 1: Creating the Template (Custom.in)
As in Part I, we will go through these steps together.
-Part II: Plotting with CAP
-CAP's plotting routine is MarsPlot.py. It works by generating a Custom.in file containing seven different plot templates that users can modify, then reading the Custom.in file to make the plots.
The plot templates in Custom.in include:
| Plot Type | -X, Y Dimensions | -Name in Custom.in |
-
|---|---|---|
| Map | -Longitude, Latitude | -Plot 2D lon x lat |
-
| Time-varying | -Time, Latitude | -Plot 2D time x lat |
-
| Time-varying | -Time, level | -Plot 2D time x lev |
-
| Time-varying | -Longitude, Time | -Plot 2D lon x time |
-
| Cross-section | -Longitude, Level | -Plot 2D lon x lev |
-
| Cross-section | -Latitude, Level | -Plot 2D lat x lev |
-
| Line plot (1D) | -Dimension*, Variable | -Plot 1D |
-
--*Dimension is user-indicated and could be time (
-time), latitude (lat), longitudelon, or level (pfull,pstd,zstd,zagl).
Additionally, MarsPlot.py supports:
-
-
- PDF & image format -
- Landscape & portrait mode -
- Multi-panel plots -
- Overplotting -
- Customizable axes dimensions and contour intervals -
- Adjustable colormaps and map projections -
and so much more. You will learn to plot with MarsPlot.py by following along with the demonstration. We will generate the Custom.in template file, customize it, and pass it back into MarsPlot.py to create plots.
-
Step 1: Creating the Template (Custom.in)
-Generate the template file, Custom.in:
(amesCAP)~$ MarsPlot.py -template
-/home/centos/tutorial_files/cap_exercises/Custom.in was created
-A new file called Custom.in is created in your current working directory.
-
Step 2: Editing Custom.in
-Open Custom.in using vim:
(amesCAP)~$ vim Custom.in
-Scroll down until you see the first two templates shown in the image below:
-
Since all of the templates have a similar structure, we can broadly describe how Custom.in works by going through the templates line-by-line.
Line 1
-# Line 1 ┌ plot type ┌ whether to create the plot
-<<<<<<<<<<<<<<| Plot 2D lon X lat = True |>>>>>>>>>>>>>
-Line 1 indicates the plot type and whether to create the plot when passed into MarsPlot.py.
Line 2
-# Line 2 ┌ file ┌ variable
-Title = None
-Line 2 is where we set the plot title.
-Line 3
-# Line 3 ┌ file ┌ variable
-Main Variable = fixed.zsurf # file.variable
-Main Variable = [fixed.zsurf]/1000 # [] brackets for mathematical operations
-Main Variable = diurn_T.temp{tod=3} # {} brackets for dimension selection
-Line 3 indicates the variable to plot and the file from which to pull the variable.
-Additional customizations include:
--
-
- Element-wise operations (e.g., scaling by a factor) -
- Dimensional selection (e.g., selecting the time of day (
tod) at which to plot from a time-shifted diurn file)
-
Line 4
-# Line 4
-Cmin, Cmax = None # automatic, or
-Cmin, Cmax = -4,5 # contour limits, or
-Cmin, Cmax = -4,-2,0,1,3,5 # explicit contour levels
-Line 4 line defines the color-filled contours for Main Variable. Valid inputs are:
-
-
None(default) enables Python's automatic interpretation of the contours
-min,maxspecifies contour range
-X,Y,Z,...,Ngives explicit contour levels
-
Lines 5 & 6
-# Lines 5 & 6
-Ls 0-360 = None # for 'time' free dimension
-Level Pa/m = None # for 'pstd' free dimension
-Lines 5 & 6 handle the free dimension(s) for Main Variable (the dimensions that are not plot dimensions).
For example, temperature has four dimensions: (time, pstd, lat, lon). For a 2D lon X lat map of temperature, lon and lat provide the x and y dimensions of the plot. The free dimensions are then pstd (Level Pa/m) and time (Ls 0-360).
Lines 5 & 6 accept four input types:
--
-
integerselects the closest value
-min,maxaverages over a range of the dimension
-allaverages over the entire dimension
-None(default) depends on the free dimension:
-
# ┌ free dimension ┌ default setting
-Ls 0-360 = None # most recent timestep
-Level Pa/m = None # surface level
-Lon +/-180 = None # zonal mean over all longitudes
-Latitude = None # equatorial values only
-Lines 7 & 8
-# Line 7 & 8
-2nd Variable = None # no solid contours
-2nd Variable = fixed.zsurf # draw solid contours
-Contours Var 2 = -4,5 # contour range, or
-Contours Var 2 = -4,-2,0,1,3,5 # explicit contour levels
-Lines 7 & 8 (optional) define the solid contours on the plot. Contours can be drawn for Main Variable or a different 2nd Variable.
-
-
- Like
Main Variable,2nd Variableminimally requiresfile.variable
- - Like
Cmin, Cmax,Contours Var 2accepts a range (min,max) or list of explicit contour levels (X,Y,Z,...,N)
-
Line 9
-# Line 9 ┌ X axes limit ┌ Y axes limit ┌ colormap ┌ cmap scale ┌ projection
- Axis Options : lon = [None,None] | lat = [None,None] | cmap = jet | scale = lin | proj = cart
-Finally, Line 9 offers plot customization (e.g., axes limits, colormaps, map projections, linestyles, 1D axes labels).
- --
Step 3: Generating the Plots
-Generate the plots set to True in Custom.in by saving and quitting the editor (:wq) and then passing the template file to MarsPlot.py. The first time we do this, we'll pass the --date [-d] flag to specify that we want to plot from the 03340 average and fixed files:
(amesCAP)~$ MarsPlot.py Custom.in -d 03340
-Plots are created and saved in a file called Diagnostics.pdf.
Viewing Diagnostics.pdf
-To open the file, we need to copy it to our local computer. We'll create an alias for the command that does this so we can easily pull Diagnostics.pdf from the cloud environment.
First, open a new terminal tab (CRTL-t).
Then, change to the directory hosting your token for this tutorial (the token is the file ending in .pem).
Finally, build the secure copy (scp) command OR use sftp.
Using scp(recommended)
-To build your scp command:
-
-
- The name of your
.pemfile (e.g.,mars-clusterXX.pem)
- - The address you used to login to the cloud (something like
centos@YOUR_IP_ADDRESS)
- - The path to the PDF in the cloud:
tutorial_files/cap_exercises/Diagnostics.pdf
-
Putting these together, the secure copy command is:
-(local)~$ scp -i "mars-clusterXX.pem" centos@YOUR_IP_ADDRESS:tutorial_files/cap_exercises/Diagnostics.pdf .
-To make the command into an alias named getpdf:
(local)~$ alias getpdf='scp -i "mars-clusterXX.pem" centos@YOUR_IP_ADDRESS:tutorial_files/cap_exercises/Diagnostics.pdf .'
-Now we can pull the PDF to our local computer with one simple command:
-(local)~$ getpdf # uses scp
-Using sftp
-Alternatively, if scp isn't working for you, you can use sftp. To do this, go to your new terminal tab and type:
(local)~$ sftp -i "mars-clusterXX.pem" centos@YOUR_IP_ADDRESS
-sftp> cd tutorial_files/cap_exercises
-Then when you want to pull the PDF to your local computer, type:
-sftp> get Diagnostics.pdf
--
Summary
-Plotting with MarsPlot.py is done in 3 steps:
(amesCAP)~$ MarsPlot.py -template # generate Custom.in
-(amesCAP)~$ vim Custom.in # edit Custom.in
-(amesCAP)~$ MarsPlot.py Custom.in # pass Custom.in back to MarsPlot
-Now we will go through some examples.
--
Customizing the Plots
-Open Custom.in in the editor:
(amesCAP)~$ vim Custom.in
-Copy the first two templates that are set to True and paste them below the line Empty Templates (set to False). Then, set them to False. This way, we have all available templates saved at the bottom of the script.
We'll preserve the first two plots, but let's define the sol number of the average and fixed files in the template itself so we don't have to pass the --date [-d] argument every time:
# for the first plot (lon X lat topography):
-Main Variable = 03340.fixed.zsurf
-# for the second plot (lat X lev zonal wind):
-Main Variable = 03340.atmos_average.ucomp
-Now we can omit the date (--date [-d]) when we pass Custom.in to MarsPlot.py.
Custom Set 1 of 4: Zonal Mean Surface Plots Over Time
-The first set of plots we'll make are zonal mean surface fields over time: surface temperature, CO ice, and wind stress.
-
For each of the plots, source variables from the non-interpolated average file, 03340.atmos_average.nc.
For the surface temperature plot:
--
-
- Copy/paste the
Plot 2D time X lattemplate above theEmpty Templatesline
- - Set it to
True
- - Edit the title to
Zonal Mean Sfc T [K]
- - Set
Main Variable = 03340.atmos_average.ts
- - Edit the colorbar range:
Cmin, Cmax = 140,270→ 140-270 Kelvin
- - Set
2nd Variable = 03340.atmos_average.ts→ for overplotted solid contours
- - Explicitly define the solid contours:
Contours Var 2 = 160,180,200,220,240,260
-
Let's pause here and pass the Custom.in file to MarsPlot.py.
Type ESC-:wq to save and close the file. Then, pass it to MarsPlot.py:
(amesCAP)~$ MarsPlot.py Custom.in
-Now, go to your local terminal tab and retrieve the PDF:
-(local)~$ getpdf # uses scp
-or
-sftp> get Diagnostics.pdf # uses sftp
-Now we can open it and view our plot.
-Go back to the cloud environment tab to finish generating the other plots on this page. Open Custom.in in vim:
(amesCAP)~$ vim Custom.in
-Write a set of HOLD ON and HOLD OFF arguments around the surface temperature plot. We will paste the other templates within these arguments to tell MarsPlot.py to put these plots on the same page.
Copy/paste the Plot 2D time X lat template plot twice more. Make sure to set the boolean to True.
For the surface CO ice plot:
--
-
- Set the title to
Zonal Mean Sfc CO2 Ice [kg/m2]
- - Set
Main Variable = 03340.atmos_average.co2ice_sfc
- - Edit the colorbar range:
Cmin, Cmax = 0,800→ 0-800 kg/m
- - Set
2nd Variable = 03340.atmos_average.co2ice_sfc→ solid contours
- - Explicitly define the solid contours:
Contours Var 2 = 200,400,600,800
- - Change the colormap on the
Axis Optionsline:cmap = plasma
-
For the surface wind stress plot:
--
-
- Set the title to
Zonal Mean Sfc Stress [N/m2]
- - Set
Main Variable = 03340.atmos_average.stress
- - Edit the colorbar range:
Cmin, Cmax = 0,0.03→ 0-0.03 N/m
-
Save and quit the editor (ESC-:wq) and pass Custom.in to MarsPlot.py:
(amesCAP)~$ MarsPlot.py Custom.in
-In your local terminal tab, retrieve the PDF to view the plots:
-(local)~$ getpdf # uses scp
-or
-sftp> get Diagnostics.pdf # uses sftp
--
Custom Set 2 of 4: Global Mean Column-Integrated Dust Optical Depth Over Time
-Now we'll generate a 1D plot and practice plotting multiple lines on it.
-
Let's start by setting up our 1D plot template:
--
-
- Write a new set of
HOLD ONandHOLD OFFarguments.
- - Copy/paste the
Plot 1Dtemplate between them.
- - Set the template to
True.
-
Create the visible dust optical depth plot first:
--
-
- Set the title:
Area-Weighted Global Mean Dust OD (norm.) [op]
- - Edit the legend:
Visible
-
The input to Main Variable is not so straightforward this time. We want to plot the normalized dust optical depth, which is dervied as follows:
normalized_dust_OD = opacity / surface_pressure * reference_pressure
-The MGCM outputs column-integrated visible dust opacity to the variable taudust_VIS, surface pressure is saved as ps, and we'll use a reference pressure of 610 Pa. Recall that element-wise operations are performed when square brackets [] are placed around the variable in Main Variable. Putting all that together, Main Variable is:
# ┌ norm. OD ┌ opacity ┌ surface pressure ┌ ref. P
-Main Variable = [03340.atmos_average.taudust_VIS]/[03340.atmos_average.ps]*610
-To finish up this plot, tell MarsPlot.py what to do to the dimensions of taudust_VIS (time, lon, lat):
-
-
- Leave
Ls 0-360 = AXISto use 'time' as the X axis dimension.
- - Set
Latitude = all→ average over all latitudes
- - Set
Lon +/-180 = all→ average over all longitudes
- - Set the Y axis label under
Axis Options:axlabel = Optical Depth
-
The infrared dust optical depth plot is identical to the visible dust OD plot except for the variable being plotted, so duplicate the visible plot we just created. Make sure both templates are between HOLD ON and HOLD OFF Then, change two things:
-
-
- Change
Main Variablefromtaudust_VIStotaudust_IR
- - Set the legend to reflect the new variable (
Legend = Infrared)
-
Save and quit the editor (ESC-:wq). pass Custom.in to MarsPlot.py:
(amesCAP)~$ MarsPlot.py Custom.in
-In your local terminal tab, retrieve the PDF to view the plots:
-(local)~$ getpdf # uses scp
-or
-sftp> get Diagnostics.pdf # uses sftp
-Notice we have two separate 1D plots on the same page. This is because of the HOLD ON and HOLD OFF arguments. Without those, these two plots would be on separate pages. But how do we overplot the lines on top of one another?
Go back to the cloud environment, open Custom.in, and type ADD LINE between the two 1D templates.
Save and quit again, pass it through MarsPlot.py, and retrieve the PDF locally. Now we have the overplotted lines we were looking for.
-
Break
-Take 15 minutes to stretch, ask questions, or let us know your thoughts on CAP so far!
--
Custom Set 3 of 4: 50 Pa Temperatures at 3 AM and 3 PM
-The first two plots are 3 AM and 3 PM 50 Pa temperatures at L=270. Below is the 3 PM - 3 AM difference.
-
We'll generate all three plots before passing Custom.in to MarsPlot.py, so copy/paste the Plot 2D lon X lat template three times between a set of HOLD ON and HOLD OFF arguments and set them to True.
For the first plot,
--
-
- Title it for 3 AM temperatures:
3 AM 50 Pa Temperatures [K] @ Ls=270
- - Set
Main Variabletotempand select 3 AM for the time of day using curly brackets:
-
Main Variable = 03847.atmos_diurn_Ls265_275_T_pstd.temp{tod=3}
--
-
- Set the colorbar range:
Cmin, Cmax = 145,290→ 145-290 K
- - Set
Ls 0-360 = 270→ southern summer solstice
- - Set
Level Pa/m = 50→ selects 50 Pa temperatures
- - Set
2nd Variableto be identical toMain Variable
-
Now, edit the second template for 3 PM temperatures the same way. The only differences are the:
--
-
- Title: edit to reflect 3 PM temperatures -
- Time of day selection: for 3 PM,
{tod=15}change this for2nd Variabletoo!
-
For the difference plot, we will need to use square brackets in the input for Main Variable in order to subtract 3 AM temperatures from 3 PM temperatures. We'll also use a diverging colorbar to show temperature differences better.
-
-
- Set the title to
3 PM - 3 AM Temperature [K] @ Ls=270
- - Build
Main Variableby subtracting the 3 AMMain Variableinput from the 3 PMMain variableinput:
-
Main Variable = [03847.atmos_diurn_Ls265_275_T_pstd.temp{tod=15}]-[03847.atmos_diurn_Ls265_275_T_pstd.temp{tod=3}]
--
-
- Center the colorbar at
0by settingCmin, Cmax = -20,20
- - Like the first two plots, set
Ls 0-360 = 270→ southern summer solstice
- - Like the first two plots, set
Level Pa/m = 50→ selects 50 Pa temperatures
- - Select a diverging colormap in
Axis Options:cmap = RdBu_r
-
Save and quit the editor (ESC-:wq). pass Custom.in to MarsPlot.py, and pull it to your local computer:
(amesCAP)~$ MarsPlot.py Custom.in
-# switch to the local terminal...
-(local)~$ getpdf # uses scp
-or
-sftp> get Diagnostics.pdf # uses sftp
--
Custom Set 4 of 4: Zonal Mean Circulation Cross-Sections
-For our final set of plots, we will generate four cross-section plots showing temperature, zonal (U) and meridional (V) winds, and mass streamfunction at L=270.
-
Begin with the usual 3-step process:
--
-
- Write a set of
HOLD ONandHOLD OFFarguments
- - Copy-paste the
Plot 2D lat X levtemplate between them
- - Set the template to
True
-
Since all four plots are going to have the same X and Y axis ranges and time selection, let's edit this template before copying it three more times:
-
-
- Set
Ls 0-360 = 270
- - In
Axis Options, setLat = [-90,90]
- - In
Axis Options, setlevel[Pa/m] = [1000,0.05]
-
Now copy/paste this template three more times. Let the first plot be temperature, the second be mass streamfunction, the third be zonal wind, and the fourth be meridional wind.
-For temperature:
-Title = Temperature [K] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.temp
-Cmin, Cmax = 110,240
-...
-2nd Variable = 03847.atmos_average_Ls265_275_pstd.temp
-For streamfunction, define explicit solid contours under Contours Var 2 and set a diverging colormap.
Title = Mass Stream Function [1.e8 kg s-1] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.msf
-Cmin, Cmax = -110,110
-...
-2nd Variable = 03847.atmos_average_Ls265_275_pstd.msf
-Contours Var 2 = -5,-3,-1,-0.5,1,3,5,10,20,40,60,100,120
-# set cmap = bwr in Axis Options
-For zonal and meridional wind, use the dual-toned colormap PiYG.
Title = Zonal Wind [m/s] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.ucomp
-Cmin, Cmax = -230,230
-...
-2nd Variable = 03847.atmos_average_Ls265_275_pstd.ucomp
-# set cmap = PiYG in Axis Options
-Title = Meridional Wind [m/s] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.vcomp
-Cmin, Cmax = -85,85
-...
-2nd Variable = 03847.atmos_average_Ls265_275_pstd.vcomp
-# set cmap = PiYG in Axis Options
-Save and quit the editor (ESC-:wq). pass Custom.in to MarsPlot.py, and pull it to your local computer:
(amesCAP)~$ MarsPlot.py Custom.in
-# switch to the local terminal...
-(local)~$ getpdf # uses scp
-or
-sftp> get Diagnostics.pdf # uses sftp
--
End Credits
-This concludes the practical exercise portion of the CAP tutorial. Please feel free to use these exercises as a reference when using CAP the future!
-Written by Courtney Batterson, Alex Kling, and Victoria Hartwick. This document was created for the NASA Ames MGCM and CAP Tutorial held virtually November 13-15, 2023.
-Questions, comments, or general feedback? Contact us.
- -
-
-
-
-
-
-
\ No newline at end of file
diff --git a/tutorial/out/CAP_Install.html b/tutorial/out/CAP_Install.html
deleted file mode 100644
index e578859d..00000000
--- a/tutorial/out/CAP_Install.html
+++ /dev/null
@@ -1,3219 +0,0 @@
-
-
-
-
-
-
-
-1. MarsPlot's
-
-
-
-
-5. Time-Shifting
-
-
-
-
-
-Step 1: Creating the Template (
-
-Step 2: Editing
-
-
-
-
-
-
-
-
-
- 
Practice Exercises - Community Analysis Pipeline (CAP)
-
CAP is a Python toolkit designed to simplify post-processing and plotting MGCM output. CAP consists of five Python executables:
--
-
MarsPull.pyfor accessing MGCM output
-MarsFiles.pyfor reducing the files
-MarsVars.pyfor performing variable operations
-MarsInterp.pyfor interpolating the vertical grid
-MarsPlot.pyfor plotting MGCM output
-
The following exercises are organized into two parts by function. We will go through Part I on Tuesday Nov. 14 and Part II on Wednesday Nov. 15.
-Part I: File Manipulations → MarsFiles.py, MarsVars.py, & MarsInterp.py
Part II: Plotting with CAP → MarsPlot.py
--We will not be going over
-MarsPull.pybecause it is specifically for retrieving Legacy MGCM data and this tutorial uses output from the new MGCM.MarsPull.pywas covered in the 2021 Legacy Version Tutorial.
-
Table of Contents
--
-
- Practice Exercises - Community Analysis Pipeline (CAP) - - -
- Part I: File Manipulations - - -
- Optional: Use the Answer Key for Part I -
- CAP Practical Day 2 -
- Part II: Plotting with CAP
-
-
-
- Step 1: Creating the Template (
Custom.in)
- - Step 2: Editing
Custom.in--
-
- Page 5 of 5: Zonal Mean Circulation Cross-Sections -
- Page 1 of 5: Zonal Mean Surface Plots Over Time -
- Page 2 of 5: Zonal Mean Column-Integrated Dust Optical Depth Over Time -
- Page 3 of 5: Global Mean Column-Integrated Dust Optical Depth Over Time -
- Page 4 of 5: 50 Pa Temperatures at 3 AM and 3 PM -
- Step 3: Generating the Plots -
-
- - Step 1: Creating the Template (
-
Activating CAP
-Activate the amesCAP virtual environment to use CAP:
(cloud)~$ source ~/amesCAP/bin/activate # bash
-(amesCAP)~$
-Your prompt will update to reflect that you're in the virtual environment. Before continuing, confirm that CAP's executables are accessible by typing:
-(amesCAP)~$ MarsVars.py -h
-This is the --help [-h] argument, which shows useful documentation for the executable indicated in the prompt. Now that we know CAP is set up correctly, copy the file amescap_profile provided by CAP to your home directory as a hidden file:
(amesCAP)~$ cp ~/amesCAP/mars_templates/amescap_profile ~/.amescap_profile
-CAP stores useful settings in amescap_profile. We make a copy of it in our home directory so that it doesn't get overwritten if CAP is updated or reinstalled in the future.
Following Along with the Tutorial
-We will perform every exercise together.
-Part I covers file manipulations. Some of the exercises build off of previous exercises so it is important to complete them in order. If you make a mistake or get behind in the process, you can go back and catch up during a break or use the provided answer key before continuing on to Part II.
-Part II demonstrates CAP's plotting routine and there is more flexibility in this part of the exercise.
--- -Feel free to put questions in the chat throughout the exercises and another CAP developer can help you out as we go.
-
Part I: File Manipulations
-CAP has dozens of post-processing capabilities and we will go over a few of the most commonly used functions including:
--
-
- Interpolating data to different vertical coordinate systems (
MarsInterp.py)
- - Adding derived variables to the files (
MarsVars.py)
- - Time-shifting data to target local times (
MarsFiles.py)
- - Trimming a file to reduce the size (
MarsFiles.py).
-
The necessary MGCM output files are already loaded in the cloud environment under tutorial_files/. Change to the tutorial_files/ directory and look at the contents:
(amesCAP)~$ cd tutorial_files
-(amesCAP)~$ ls
-03340.atmos_average.nc
-03340.atmos_diurn.nc
-03340.fixed.nc
-These files are from the sixth year of a simulation. MGCM output file names are generated with a 5-digit sol number appended to the front of the file name. The sol number indicates the day that a file's record begins.
---The files we manipulate here will be used to generating the plots in Part II so do not delete anything!
-
1. MarsPlot's --inspect Function
-The average file is 03340.atmos_average.nc and the inspect function is in MarsPlot.py. To use it, type the following in the terminal:
(amesCAP)~$ MarsPlot.py -i 03340.atmos_average.nc
--- -This is a good time to remind you that if you are unsure how to use a function, invoke the
---help [-h]argument with any executable to see its documentation (e.g.,MarsPlot.py -h).
-
2. Editing Variable Names and Attributes
-The --inspect [-i] function shows a variable called opac in 03340.atmos_average.nc. opac is dust opacity per Pascal, and we have another variable dustref that is opacity per (model) level. For the second exercise, we will rename opac to dustref_per_pa to better indicate the relationship between the variables.
The -edit function in MarsVars.py allows us to change variable names, units, and longnames in MGCM output files. The syntax is:
(amesCAP)~$ MarsVars.py 03340.atmos_average.nc -edit opac -rename dustref_per_pa
-03340.atmos_average_tmp.nc was created
-03340.atmos_average.nc was updated
-We can use --inspect [-i] to see that 03340.atmos_average.nc reflects our changes:
(amesCAP)~$ MarsPlot.py -i 03340.atmos_average.nc
-We can also see a summary of the values of dustref_per_pa using -stat with --inspect [-i]:
(amesCAP)~$ MarsPlot.py -i 03340.atmos_average.nc -stat dustref_per_pa
-__________________________________________________________________
- VAR | MIN | MEAN | MAX |
-__________________|_______________|_______________|_______________|
- dustref_per_pa| 0| 0.000307308| 0.00175193|
-__________________|_______________|_______________|_______________|
-and we can print the values of any variable to the terminal by adding an ncdump-like argument to --inspect [-i]. We demonstrate this with latitude (lat) because it is a relatively short 1D array:
(amesCAP)~$ MarsPlot.py -i 03340.atmos_average.nc -dump lat
-lat=
-[-89. -87. -85. -83. -81. -79. -77. -75. -73. -71. -69. -67. -65. -63.
- -61. -59. -57. -55. -53. -51. -49. -47. -45. -43. -41. -39. -37. -35.
- -33. -31. -29. -27. -25. -23. -21. -19. -17. -15. -13. -11. -9. -7.
- -5. -3. -1. 1. 3. 5. 7. 9. 11. 13. 15. 17. 19. 21.
- 1. 25. 27. 29. 31. 33. 35. 37. 39. 41. 43. 45. 47. 49.
- 2. 53. 55. 57. 59. 61. 63. 65. 67. 69. 71. 73. 75. 77.
- 3. 81. 83. 85. 87. 89.]
--
3. Splitting Files in Time
-Next we're going to trim the diurn and average files by L$_s$ to generate a new file that only contains data around southern summer solstice, L$_s$=270. This greatly reduces the size of the file so we can pressure-interpolate it faster later on.
Trim the files like so:
-(amesCAP)~$ MarsFiles.py 03340.atmos_diurn.nc -split 265 275
-...
-/home/centos/tutorial_files/03847.atmos_diurn_Ls265_275.nc was created
-(amesCAP)~$ MarsFiles.py 03340.atmos_average.nc -split 265 275
-...
-/home/centos/tutorial_files/03847.atmos_average_Ls265_275.nc was created
-The trimmed files have the appendix _Ls265_275.nc and the simulation day has changed from 03340 to 03847 to reflect that the first day in the file has changed.
For future steps, we need a fixed file with the same simulation day number as the files we just created, so make a copy of the fixed file and rename it:
(amesCAP)~$ cp 03340.fixed.nc 03847.fixed.nc
--
4. Deriving Secondary Variables
-The --add function in MarsVars.py derives and adds secondary variables to MGCM output files provided that the variable(s) required to derive the secondary variable exist(s) in the file. What variables do we need to derive the meridional mass streamfunction (msf)? We can check with the help function:
(amesCAP)~$ MarsVars.py -h
-The help function shows that streamfunction (msf) requires meridional wind (vcomp) for derivation and that we can only derive streamfunction on a pressure-interpolated file. We can confirm that vcomp is in the 03847.atmos_average_Ls265_275.nc using the --inspect [-i] call to MarsPlot.py:
(amesCAP)~$ MarsPlot.py -i 03847.atmos_average_Ls265_275.nc
-...
-vcomp : ('time', 'pfull', 'lat', 'lon')= (3, 56, 90, 180), meridional wind [m/sec]
-...
-Now we can pressure-interpolate the average file using MarsInterp.py. This is done by specifying the interpolation type (--type [-t]), which is standard pressure (pstd), and the grid (--level [-l]) to interpolate to (pstd_default). Grid options are listed in ~/.amescap_profile.
We will also specify which variables to include in the interpolation using -include. This will reduce the interpolated file size. We will include temperature (temp), winds (ucomp and vcomp), and surface pressure (ps) in the interpolated file.
Before performing the interpolation, we can ask MarsInterp.py to print out the pressure levels of the grid that we are interpolating to by including the -g argument in the call to MarsInterp.py:
We add --grid [-g] in the call to MarsInterp.py to print out the pressure levels of the grid that we are interpolating to:
(amesCAP)~$ MarsInterp.py 03847.atmos_average_Ls265_275.nc -t pstd -l pstd_default -include temp ucomp vcomp ps -g
-1100.0 1050.0 1000.0 950.0 900.0 850.0 800.0 750.0 700.0 650.0 600.0 550.0 500.0 450.0 400.0 350.0 300.0 250.0 200.0 150.0 100.0 70.0 50.0 30.0 20.0 10.0 7.0 5.0 3.0 2.0 1.0 0.5 0.3 0.2 0.1 0.05
-To perform the actual interpolation, omit the --grid [-g] flag:
(amesCAP)~$ MarsInterp.py 03847.atmos_average_Ls265_275.nc -t pstd -l pstd_default -include temp ucomp vcomp ps
-/home/centos/tutorial_files/03847.atmos_average_Ls265_275_pstd.nc was created
-Now that we have a pressure-interpolated file, we can derive and add msf to it using MarsVars.py:
(amesCAP)~$ MarsVars.py 03847.atmos_average_Ls265_275_pstd.nc -add msf
-Processing: msf...
-msf: Done
--
5. Time-Shifting Diurn Files
-The diurn file is organized by time-of-day assuming universal time starts at the Martian prime meridian. The time-shift --tshift [-t] function converts the diurn file to uniform local time, which is useful for comparing MGCM output to observations from satellites in fixed local time orbit, for example. Time-shifting can only be done on files with a local time dimension (time_of_day_24, i.e. diurn files).
By default, MarsFiles.py time shifts all of the data in the file data to 24 uniform local times. This generates very large files. To reduce file size and processing time, there is an option to time-shift data only to user-specified local times. To do so, simply list the desired local times after the call to --tshift [-t].
In this example, we will time-shift temperature (temp) and surface pressure (ps) to 3 AM / 3 PM local time:
(amesCAP)~$ MarsFiles.py 03847.atmos_diurn_Ls265_275.nc -t '3. 15.' -include temp ps
-...
-/home/centos/tutorial_files/03847.atmos_diurn_Ls265_275_T.nc was created
-This created a diurn file with "_T" appended to the file name: 03847.atmos_diurn_Ls265_275_T.nc. Using --inspect [-i], we can confirm that only ps and temp (and their dimensions) are in the file and that the time_of_day dimension has a length of 2:
(amesCAP)~$ MarsPlot.py -i 03847.atmos_diurn_Ls265_275_T.nc
-...
-====================CONTENT==========================
-scalar_axis : ('scalar_axis',)= (1,), none [none]
-pfull : ('pfull',)= (56,), ref full pressure level [mb]
-lat : ('lat',)= (90,), latitude [degrees_N]
-lon : ('lon',)= (180,), longitude [degrees_E]
-time : ('time',)= (7,), sol number [days since 0000-00-00 00:00:00]
-time_of_day_02 : ('time_of_day_02',)= (2,), time of day [[hours since 0000-00-00 00:00:00]]
-areo : ('time', 'time_of_day_02', 'scalar_axis')= (7, 2, 1), areo [degrees]
-ps : ('time', 'time_of_day_02', 'lat', 'lon')= (7, 2, 90, 180), surface pressure [Pa]
-temp : ('time', 'time_of_day_02', 'pfull', 'lat', 'lon')= (7, 2, 56, 90, 180), temperature [K]
-=====================================================
--
6. Pressure-Interpolating the Vertical Axis
-After trimming the file and reducing the number of variables stored in the file, we can efficiently interpolate 03847.atmos_diurn_Ls265_275_T.nc to a standard pressure grid. Recall that interpolation is part of MarsInterp.py and requires two arguments:
-
-
- Interpolation type (
--type [-t]), and
- - Grid (
--level [-l])
-
As before, we will interpolate to the standard pressure grid (pstd_default), this time retaining all variables in the file:
(amesCAP)~$ MarsInterp.py 03847.atmos_diurn_Ls265_275_T.nc -t pstd -l pstd_default
-/home/centos/tutorial_files/03847.atmos_diurn_Ls265_275_T_pstd.nc was created
---Note: Interpolation could be done before or after time-shifting, the order does not matter.
-
We now have four different diurn files in our directory:
03340.atmos_diurn.nc # Original MGCM file
-03847.atmos_diurn_Ls265_275.nc # + Trimmed to L$_s$=240-300
-03847.atmos_diurn_Ls265_275_T.nc # + Time-shifted; `ps` and `temp` only
-03847.atmos_diurn_Ls265_275_T_pstd.nc # + Pressure-interpolated
-CAP always adds an appendix to the name of any new file it creates. This helps users keep track of what was done and in what order. The last file we created was trimmed, time-shifted, then pressure-interpolated. However, the same file could be generated by performing the three functions in any order.
- -Optional: Use the Answer Key for Part I
-This concludes Part I of the tutorial! If you messed up one of the exercises somewhere, you can run a script that performs all 6 Exercises in Part I for you. To do this, follow the steps below.
--
-
- Source the
amesCAPvirtual environment
- - Change to the
tutorial_files/directory
- - Run the executable below -
(amesCAP)~$ ~/cap_backup/part_1_key.sh
-The script will do all of Part I for you. This ensures you can follow along with the plotting routines in Part II.
- -CAP Practical Day 2
-This part of the CAP Practical covers how to generate plots with CAP. We will take a learn-by-doing approach, creating five sets of plots that demonstrate some of CAP's most often used plotting capabilities:
--
-
- Page 5 of 5: Zonal Mean Circulation Cross-Sections -
- Page 1 of 5: Zonal Mean Surface Plots Over Time -
- Page 2 of 5: Zonal Mean Column-Integrated Dust Optical Depth Over Time -
- Page 3 of 5: Global Mean Column-Integrated Dust Optical Depth Over Time -
- Page 4 of 5: 50 Pa Temperatures at 3 AM and 3 PM -
Plotting with CAP is done in 3 steps:
-Step 1: Creating the Template (Custom.in)
As in Part I, we will go through these steps together.
-Part II: Plotting with CAP
-CAP's plotting routine is MarsPlot.py. It works by generating a Custom.in file containing seven different plot templates that users can modify, then reading the Custom.in file to make the plots.
The plot templates in Custom.in include:
| Plot Type | -X, Y Dimensions | -Name in Custom.in |
-
|---|---|---|
| Map | -Longitude, Latitude | -Plot 2D lon x lat |
-
| Time-varying | -Time, Latitude | -Plot 2D time x lat |
-
| Time-varying | -Time, level | -Plot 2D time x lev |
-
| Time-varying | -Longitude, Time | -Plot 2D lon x time |
-
| Cross-section | -Longitude, Level | -Plot 2D lon x lev |
-
| Cross-section | -Latitude, Level | -Plot 2D lat x lev |
-
| Line plot (1D) | -Dimension*, Variable | -Plot 1D |
-
--*Dimension is user-indicated and could be time (
-time), latitude (lat), longitudelon, or level (pfull,pstd,zstd,zagl).
Additionally, MarsPlot.py supports:
-
-
- PDF & image format -
- Landscape & portrait mode -
- Multi-panel plots -
- Overplotting -
- Customizable axes dimensions and contour intervals -
- Adjustable colormaps and map projections -
and so much more. You will learn to plot with MarsPlot.py by following along with the demonstration. We will generate the Custom.in template file, customize it, and pass it back into MarsPlot.py to create plots.
-
Step 1: Creating the Template (Custom.in)
-Generate the template file, Custom.in:
(amesCAP)~$ MarsPlot.py -template
-/home/centos/tutorial_files/Custom.in was created
-A new file called Custom.in is created in your current working directory.
-
Step 2: Editing Custom.in
-Open Custom.in using vim:
(amesCAP)~$ vim Custom.in
-Scroll down until you see the first two templates shown in the image below:
-
Since all of the templates have a similar structure, we can broadly describe how Custom.in works by going through the templates line-by-line.
Line 1
-# Line 1 ┌ plot type ┌ whether to create the plot
-<<<<<<<<<<<<<<| Plot 2D lon X lat = True |>>>>>>>>>>>>>
-Line 1 indicates the plot type and whether to create the plot when passed into MarsPlot.py.
Line 2
-# Line 2 ┌ file ┌ variable
-Main Variable = fixed.zsurf # file.variable
-Main Variable = [fixed.zsurf]/1000 # [] brackets for mathematical operations
-Main Variable = diurn_T.temp{tod=3} # {} brackets for dimension selection
-Line 2 indicates the variable to plot and the file from which to pull the variable.
-Additional customizations include:
--
-
- Element-wise operations (e.g., scaling by a factor) -
- Dimensional selection (e.g., selecting the time of day (
tod) at which to plot from a time-shifted diurn file)
-
Line 3
-# Line 3
-Cmin, Cmax = None # automatic, or
-Cmin, Cmax = -4,5 # contour limits, or
-Cmin, Cmax = -4,-2,0,1,3,5 # explicit contour levels
-Line 3 line defines the color-filled contours for Main Variable. Valid inputs are:
-
-
None(default) enables Python's automatic interpretation of the contours
-min,maxspecifies contour range
-X,Y,Z,...,Ngives explicit contour levels
-
Lines 4 & 5
-# Lines 4 & 5
-Ls 0-360 = None # for 'time' free dimension
-Level Pa/m = None # for 'pstd' free dimension
-Lines 4 & 5 handle the free dimension(s) for Main Variable (the dimensions that are not plot dimensions).
For example, temperature has 4 dimensions: (time, pstd, lat, lon). For a 2D lon X lat map of temperature, lon and lat provide the x and y dimensions of the plot. The free dimensions are then pstd (Level Pa/m) and time (Ls 0-360).
Lines 4 & 5 accept four input types:
--
-
integerselects the closest value
-min,maxaverages over a range of the dimension
-allaverages over the entire dimension
-None(default) depends on the free dimension:
-
# ┌ free dimension ┌ default setting
-Ls 0-360 = None # most recent timestep
-Level Pa/m = None # surface level
-Lon +/-180 = None # zonal mean over all longitudes
-Latitude = None # equatorial values only
-Lines 6 & 7
-# Line 6 & 7
-2nd Variable = None # no solid contours
-2nd Variable = fixed.zsurf # draw solid contours
-Contours Var 2 = -4,5 # contour range, or
-Contours Var 2 = -4,-2,0,1,3,5 # explicit contour levels
-Lines 6 & 7 (optional) define the solid contours on the plot. Contours can be drawn for Main Variable or a different 2nd Variable.
-
-
- Like
Main Variable,2nd Variableminimally requiresfile.variable
- - Like
Cmin, Cmax,Contours Var 2accepts a range (min,max) or list of explicit contour levels (X,Y,Z,...,N)
-
Line 8
-# Line 8 ┌ X axes limit ┌ Y axes limit ┌ colormap ┌ cmap scale ┌ projection
- Axis Options : lon = [None,None] | lat = [None,None] | cmap = jet | scale = lin | proj = cart
-Finally, Line 8 offers plot customization (e.g., axes limits, colormaps, map projections, linestyles, 1D axes labels).
- --
Step 3: Generating the Plots
-Generate the plots set to True in Custom.in by saving and quitting the editor (:wq) and then passing the template file to MarsPlot.py:
(amesCAP)~$ MarsPlot.py Custom.in
-Plots are created and saved in a file called Diagnostics.pdf. Open the file to view the plots!
-
Summary
-Plotting with MarsPlot.py is done in 3 steps:
(amesCAP)~$ MarsPlot.py -template # generate Custom.in
-(amesCAP)~$ vim Custom.in # edit Custom.in
-(amesCAP)~$ MarsPlot.py Custom.in # pass Custom.in back to MarsPlot
-Now we will go through some examples.
--
Customizing the Plots
-Open Custom.in in the editor:
(amesCAP)~$ vim Custom.in
-Copy the first two templates that are set to True and paste them below the line Empty Templates (set to False). Then, set them to False. This way, we have all available templates saved at the bottom of the script.
Page 1 of 5: Zonal Mean Surface Plots Over Time
-The first set of plots we'll make are zonal mean surface fields over time: surface temperature, CO$_2$ ice, and wind stress.
-
We will always do three things when we create a new plot:
--
-
- Write a set of
HOLD ONandHOLD OFFarguments
- - Copy/paste the
Plot 2D time X lattemplate three times between them
- - Set all three templates to
True
-
For each of the plots, source variables from the non-interpolated average file, 03340.atmos_average.nc.
For the surface temperature plot:
--
-
- Set the title to
Zonal Mean Sfc T [K]
- - Set
Main Variableand2nd Variabletots
- - Set the colorbar range to
140-270K
- - Set
Contours Var 2 = 160,180,200,220,240,260
-
For the surface CO$_2$ ice plot:
--
-
- Set the title to
Zonal Mean Sfc CO2 Ice [kg/m2]
- - Set
Main Variableand2nd Variabletoco2ice_sfc
- - Set the colorbar range to
0-800kg/m2
- - Set
Contours Var 2 = 200,400,600,800
-
For the surface wind stress plot:
--
-
- Set the title to
Zonal Mean Sfc Stress [N/m2]
- - Set
Main Variableand2nd Variabletostress
- - Set the colorbar range to
0-0.03N/m2
-
Optionally, you can adjust any of the following Axis Options as you like. Leave some of the values to the default None to see what happens.
-
-
- Adjust the latitude (y axis) range (
lat = [None,None])
- - Adjust the time (x axis) range (
Ls = [None,None])
- - Change the colormap (
cmap; options includeSpectral_r,nipy_spectral,RdBu_r,jet,rainbow)
-
Make the plots by saving Custom.in (:wq) and passing it to MarsPlot.py:
(amesCAP)~$ MarsPlot.py Custom.in
--
Page 2 of 5: Zonal Mean Column-Integrated Dust Optical Depth Over Time
-The next set of plots are very similar to the first: zonal mean visible (taudust_VIS) and infrared (taudust_IR) dust optical depth over time. The difference is that the normalized dust optical depth has to be calculated from the dust opacity, so we'll use square brackets [] for element-wise operations.
Start with the 3-step process we did before:
--
-
- Write a set of
HOLD ONandHOLD OFFarguments
- - Copy/paste the
Plot 2D time X lattemplate two times between them
- - Set all three templates to
True
-
For both plots, source dust opacities from the non-interpolated average file, 03340.atmos_average.nc.
Use square brackets [] around the input for Main Variable to calculate the normalized dust optical depth:
optical depth = [opacity] / [surface pressure] * (reference pressure)
where opacity is taudust_VIS, surface pressure is ps, and the reference pressure is 610 Pa. For the visible dust optical depth, then, Main Variable is:
Main Variable = [03340.atmos_average.taudust_VIS]/[03340.atmos_average.ps]*610
--
-
- Set
Main Variablefor the IR dust optical depth plot (taudust_IR) accordingly.
- - Set
2nd Variableto the same value asMain Variable.
- - Set the colorbar range to
0,1.
-
Save and quit Custom.in (:wq) and pass it to MarsPlot.py:
(amesCAP)~$ MarsPlot.py Custom.in
--
Page 3 of 5: Global Mean Column-Integrated Dust Optical Depth Over Time
-Now we'll look at the global dust optical depth over time in a 1D plot.
-
Begin as usual: copy/paste the Plot 1D template twice between a set of HOLD ON and HOLD OFF arguments and set them to True.
-
-
- Title the plots
Area-Weighted Global Mean Dust Optical Depth (norm.) [op]
- - Assign
VisibleandIRtoLegendaccordingly
- Main Variablewill be the same as in the previous plots, so copy and paste those values here.
-- Set
Ls 0-360 = AXISto use 'time' as the X axis.
- - To calculate the global mean dust optical depth, set the remaining free dimensions (
Latitude&Lon +/-180) toall:
-
Ls 0-360 = AXIS
-Latitude = all
-Lon +/-180 = all
-Level [Pa/m] = None # taudust_* vars are column-integrated
-Diurnal [hr] = None
-If we were to run this through CAP now, we would end up with two separate 1D plots on the same page. To overplot both lines on the same plot instead, include ADD LINE between the templates.
Save and quit Custom.in (:wq) and pass it to MarsPlot.py:
(amesCAP)~$ MarsPlot.py Custom.in
--
Page 4 of 5: 50 Pa Temperatures at 3 AM and 3 PM
-This set of plots shows 50 Pa temperatures during southern summer solstice at 3 AM and 3 PM. As well as the difference between them.
-
As usual, copy/paste the Plot 2D lon X lat template three times between a set of HOLD ON and HOLD OFF arguments and set them to True.
For each of the three plots:
--
-
- Title the plots -
- Set
Ls 0-360 = 270
- - Set
Level Pa/m = 50(50 Pa)
-
For the AM and PM temperature plots:
--
-
Main Variableistempfrom03847.atmos_diurn_Ls265_275_T_pstd.nc, the trimmed, time-shifted, and pressure-interpolated diurnal file we made yesterday
-- Set the colorbar range:
Cmin, Cmax = 145,290(145-290 K)
- - Request the 3 AM & 3 PM times of day from the
diurn_Tfile by specifying the time of day (tod) dimension using curly brackets{}in the call toMain Variable:
-
Main Variable = 03847.atmos_diurn_Ls265_275_T_pstd.temp{tod=3} # for 3 AM
-Main Variable = 03847.atmos_diurn_Ls265_275_T_pstd.temp{tod=15} # for 3 PM
-For the difference plot, subtract Main Variable from the 3 PM and 3 AM lines. Since we're performing a mathematical operation on the values of temp, use square brackets [] around each variable like so:
Main Variable = [03847.atmos_diurn_Ls265_275_T_pstd.temp{tod=15}]-[03847.atmos_diurn_Ls265_275_T_pstd.temp{tod=3}]
--
-
- Use a diverging colormap for the difference plot (e.g.,
RdBu_r,bwr,PiYG,Spectral) for the difference plot
- - Center the colorbar at
0by settingCmin, Cmax = -20,20.
-
Save and quit Custom.in (:wq) and pass it to MarsPlot.py:
(amesCAP)~$ MarsPlot.py Custom.in
--
Page 5 of 5: Zonal Mean Circulation Cross-Sections
-Finally, we will make a set of cross-sectional plots showing temperature, U and V winds, and mass streamfunction during southern summer.
-
Begin with the usual 3-step process:
--
-
- Write a
HOLD ONHOLD OFFset
- - Copy-paste the
Plot 2D lat X levtemplate four times
- - Set every plot to
True
-
Set Main Variable to the variable to be plotted and Title the plot accordingly:
# temperature
-Title = Temperature [K] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.temp
-Cmin, Cmax = 110,240
-Ls 0-360 = 270
-
-# mass streamfunction
-Title = Mass Stream Function [1.e8 kg s-1] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.msf
-Cmin, Cmax = -110,110
-Ls 0-360 = 270
-
-# zonal wind
-Title = Zonal Wind [m/s] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.ucomp
-Cmin, Cmax = -230,230
-Ls 0-360 = 270
-
-# meridional wind
-Title = Meridional Wind [m/s] (Ls=270)
-Main Variable = 03847.atmos_average_Ls265_275_pstd.vcomp
-Cmin, Cmax = -85,85
-Ls 0-360 = 270
-For mass streamfunction, add solid contours to the plot and specify the contour levels as follows:
-2nd Variable = 03847.atmos_average_Ls265_275_pstd.msf
-Contours Var 2 = -5,-3,-1,-0.5,1,3,5,10,20,40,60,100,120
-Change the colormap for each plot. I like to use:
--
-
rainbowfortemp
-bwrformsf
-PiYGfor the windsucompandvcomp
-
Finally, set the latitude and level limits explicitly under Axis Options:
Axis Options : Lat = [-90,90] | level[Pa/m] = [1000,0.05] | cmap = rainbow |scale = lin
---We are plotting from the pressure-interpolated (
-pstd) file so the vertical grid is pressure in Pascal andlevel [Pa/m]defines the axes limits in Pascal. If we were using the non-interpolated file, we would specify the axes limits in meters.
Save and quit Custom.in (:wq) and pass it to MarsPlot.py:
(amesCAP)~$ MarsPlot.py Custom.in
-End Credits
-This concludes the practical exercise portion of the CAP tutorial. Please feel free to use these exercises as a reference when using CAP the future!
-This document was completed in October 2023. Written by Courtney Batterson, Alex Kling, and Victoria Hartwick. Feedback can be directed to Alex Kling at alexandre.m.kling@nasa.gov
- --
-
-
-
-
-
-
\ No newline at end of file
diff --git a/tutorial/out/CAP_lecture.html b/tutorial/out/CAP_lecture.html
deleted file mode 100644
index 57b9be82..00000000
--- a/tutorial/out/CAP_lecture.html
+++ /dev/null
@@ -1,3621 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-Using
-
-Using
-
-
-
-Install
-
-
-
- 
-
Installing the Community Analysis Pipeline (CAP)
-Welcome!
-This document contains the instructions for installing the NASA Ames MCMC's Community Analysis Pipeline (CAP). We ask that you come to the MGCM Tutorial on November 2-4 with CAP installed on your machine so that we can jump right into using it! On the second day of the tutorial (November 3rd), we will be using CAP to analyze MGCM output.
-Installing CAP is fairly straightforward. We will create a Python virtual environment, download CAP, and then install CAP in the virtual environment. That's it!
-A quick overview of what is covered in this installation document:
--
-
- Creating the Virtual Environment -
- Installing CAP -
- Testing & Using CAP -
- Practical Tips -
- Do This Before Attending the Tutorial -
-
1. Creating the Virtual Environment
-We begin by creating a virtual environment in which to install CAP. The virtual environment is an isolated Python environment cloned from an existing Python distribution. The virtual environment consists of the same directory trees as the original environment, but it includes activation and deactivation scripts that are used to move in and out of the virtual environment. Here's an illustration of how the two Python environments might differ:
- anaconda3 virtual_env3/
- ├── bin ├── bin
- │ ├── pip (copy) │ ├── pip
- │ └── python3 >>>> │ ├── python3
- └── lib │ ├── activate
- │ ├── activate.csh
- │ └── deactivate
- └── lib
-
- ORIGINAL ENVIRONMENT VIRTUAL ENVIRONMENT
- (untouched) (vanishes when deactivated)
-We can install and upgrade packages in the virtual environment without breaking the main Python environment. In fact, it is safe to change or even completely delete the virtual environment without breaking the main distribution. This allows us to experiment freely in the virtual environment, making it the perfect location for installing and testing CAP.
--
Step 1: Identify Your Preferred Python Distribution
-If you are already comfortable with Python's package management system, you are welcome to install the pipeline on top any python3 distribution already present on your computer. Jump to Step #2 and resolve any missing package dependency.
-For all other users, we highly recommend using the latest version of the Anaconda Python distribution. It ships with pre-compiled math and plotting packages such as numpy and matplotlib as well as pre-compiled libraries like hdf5 headers for reading netCDF files (the preferred filetype for analysing MGCM output).
You can install the Anaconda Python distribution via the command-line or using a graphical interface (scroll to the very bottom of the page for all download options). You can install Anaconda at either the System/ level or the User/ level (the later does not require admin-priviledges). The instructions below are for the command-line installation and installs Anaconda in your home directory, which is the recommended location. Open a terminal and type the following:
(local)>$ chmod +x Anaconda3-2021.05-MacOSX-x86_64.sh # make the .sh file executable (actual name may differ)
-(local)>$ ./Anaconda3-2021.05MacOSX-x86_64.sh # runs the executable
-Which will return:
-> Welcome to Anaconda3 2021.05
->
-> In order to continue the installation process, please review the license agreement.
-> Please, press ENTER to continue
-> >>>
-Read (ENTER) and accept (yes) the terms, choose your installation location, and initialize Anaconda3:
(local)>$ [ENTER]
-> Do you accept the license terms? [yes|no]
-> >>>
-(local)>$ yes
-> Anaconda3 will now be installed into this location:
-> /Users/username/anaconda3
->
-> - Press ENTER to confirm the location
-> - Press CTRL-C to abort the installation
-> - Or specify a different location below
->
-> [/Users/username/anaconda3] >>>
-(local)>$ [ENTER]
-> PREFIX=/Users/username/anaconda3
-> Unpacking payload ...
-> Collecting package metadata (current_repodata.json):
-> done
-> Solving environment: done
->
-> ## Package Plan ##
-> ...
-> Preparing transaction: done
-> Executing transaction: -
-> done
-> installation finished.
-> Do you wish the installer to initialize Anaconda3 by running conda init? [yes|no]
-> [yes] >>>
-(local)>$ yes
---For Windows users, we recommend installing the pipeline in a Linux-type environment using Cygwin. This will enable the use of CAP command line tools. Simply download the Windows version of Anaconda on the Anaconda website and follow the instructions from the installation GUI. When asked about the installation location, make sure you install Python under your emulated-Linux home directory (
-/home/username) and not in the default location (/cygdrive/c/Users/username/anaconda3). From the installation GUI, the path you want to select is something like:C:/Program Files/cygwin64/home/username/anaconda3. Also be sure to check YES when prompted to "Add Anaconda to myPATHenvironment variable."
Confirm that your path to the Anaconda Python distribution is fully actualized by closing out of the current terminal, opening a new terminal, and typing:
-(local)>$ python[TAB]
-If this returns multiple options (e.g. python, python2, python 3.7, python.exe), then you have more than one version of Python sitting on your system (an old python2 executable located in /usr/local/bin/python, for example). You can see what these versions are by typing:
(local)>$ python3 --version # Linux/MacOS
-(local)>$ python.exe --version # Cygwin/Windows
-Check your version of pip the same way, then find and set your $PATH environment variable to point to the Anaconda Python and Anaconda pip distributions. If you are planning to use Python for other projects, you can update these paths like so:
# with bash:
-(local)>$ echo 'export PATH=/Users/username/anaconda3/bin:$PATH' >> ~/.bash_profile
-# with csh/tsch:
-(local)>$ echo 'setenv PATH $PATH\:/Users/username/anaconda3/bin\:$HOME/bin\:.' >> ~/.cshrc
-Confirm these settings using the which command:
(local)>$ which python3 # Linux/MacOS
-(local)>$ which python.exe # Cygwin/Windows
-which hopefully returns a Python executable that looks like it was installed with Anaconda, such as:
-> /username/anaconda3/bin/python3 # Linux/MacOS
-> /username/anaconda3/python.exe # Cygwin/Windows
-If which points to either of those locations, you are good to go and you can proceed from here using the shorthand path to your Anaconda Python distribution:
(local)>$ python3 # Linux/MacOS
-(local)>$ python.exe # Cygwin/Windows
-If, however, which points to some other location, such as /usr/local/bin/python, or more than one location, proceed from here using the full path to the Anaconda Python distribution:
(local)>$ /username/anaconda3/bin/python3 # Linux/MacOS
-(local)>$ /username/anaconda3/python.exe # Cygwin/Windows
--
Step 2: Set Up the Virtual Environment:
-Python virtual environments are created from the command line. Create an environment called amesCAP by typing:
(local)>$ python3 -m venv --system-site-packages amesCAP # Linux/MacOS Use FULL PATH to python if needed
-(local)>$ python.exe -m venv –-system-site-packages amesCAP # Cygwin/Windows Use FULL PATH to python if needed
-First, find out if your terminal is using bash or a variation of C-shell (.csh, .tsch...) by typing:
-(local)>$ echo $0
-> -bash
-Depending on the answer, you can now activate the virtual environment with one of the options below:
-(local)>$ source amesCAP/bin/activate # bash
-(local)>$ source amesCAP/bin/activate.csh # csh/tcsh
-(local)>$ source amesCAP/Scripts/activate.csh # Cygwin/Windows
-(local)>$ conda amesCAP/bin/activate # if you used conda
---In Cygwin/Windows, the
-/bindirectory may be named/Scripts.
You will notice that after sourcing amesCAP, your prompt changed indicate that you are now inside the virtual environment (i.e. (local)>$ changed to (amesCAP)>$).
We can verify that which python and which pip unambiguously point to amesCAP/bin/python3 and amesCAP/bin/pip, respectively, by calling which within the virtual environment:
(amesCAP)>$ which python3 # in bash, csh
-> amesCAP/bin/python3
-(amesCAP)>$ which pip
-> amesCAP/bin/pip
-
-(amesCAP)>$ which python.exe # in Cygwin/Windows
-> amesCAP/Scripts/python.exe
-(amesCAP)>$ which pip
-> amesCAP/Scripts/pip
-There is therefore no need to reference the full paths while inside the virtual environment.
--
2. Installing CAP
-Now we can download and install CAP in amesCAP. CAP was provided to you in the tarfile AmesCAP-master.zip that was sent along with these instructions. Download AmesCAP-master.zip. You can leave the file in Downloads/, or, if you encounter any permission issue, move it to a temporary location like your /home or /Desktop directories.
Using pip
-Open a terminal window, activate the virtual environment, and untar the file or install from the github:
-(local)>$ source ~/amesCAP/bin/activate # bash
-(local)>$ source ~/amesCAP/bin/activate.csh # cshr/tsch
-(local)>$ source ~/amesCAP/Scripts/activate.csh # Cygwin/Windows
-(local)>$ conda amesCAP/bin/activate # if you used conda
-# FROM AN ARCHIVE:
-(amesCAP)>$ tar -xf AmesCAP-master.zip
-(amesCAP)>$ cd AmesCAP-master
-(amesCAP)>$ pip install .
-# OR FROM THE GITHUB:
-(amesCAP)>$ pip install git+https://github.com/NASA-Planetary-Science/AmesCAP.git
---Please follow the instructions to upgrade pip if recommended during that steps. Instructions relevant the conda package manager are listed at the end of this section
-
That's it! CAP is installed in amesCAP and you can see the MarsXXXX.py executables stored in ~/amesCAP/bin/:
(local)>$ ls ~/amesCAP/bin/
-> Activate.ps1 MarsPull.py activate.csh nc4tonc3 pip3
-> MarsFiles.py MarsVars.py activate.fish ncinfo pip3.8
-> MarsInterp.py MarsViewer.py easy_install normalizer python
-> MarsPlot.py activate easy_install-3.8 pip python3
---Shall you need to modify any code, note that when you access the
-Marstools above, those are not executed from theAmesCAP-master/folder in your/Downloadsdirectory, but instead from theamesCAPvirtual environment where they were installed by pip. You can safely move AmesCAP-master.zip and the AmesCAP-master directory to a different location on your system.
Double check that the paths to the executables are correctly set in your terminal by exiting the virtual environment:
-(amesCAP)>$ deactivate
-then reactivating the virtual environment:
-(local)>$ source ~/amesCAP/bin/activate # bash
-(local)>$ source ~/amesCAP/bin/activate.csh # csh/tsch
-(local)>$ source ~/amesCAP/Scripts/activate.csh # cygwin
-(local)>$ conda amesCAP/bin/activate # if you used conda
-and checking the documentation for any CAP executable using the --help option:
(amesCAP)>$ MarsPlot.py --help
-(amesCAP)>$ MarsPlot.py -h
-or using full paths:
-(amesCAP)>$ ~/amesCAP/bin/MarsPlot.py -h # Linux/MacOS
-(amesCAP)>$ ~/amesCAP/Scripts/MarsPlot.py -h # Cygwin/Windows
-If the pipeline is installed correctly, --help will display documentation and command-line arguments for MarsPlot in the terminal.
--If you have either purposely or accidentally installed the
-amescappackage on top of your main python distribution (e.g. in~/anaconda3/lib/python3.7/site-packages/or~/anaconda3/bin/) BEFORE setting-up theamesCAPvirtual environment, theMars*.pyexecutables may not be present in the~/amesCAP/bin/directory of the virtual environment (~/amesCAP/Scripts/on Cygwin). Because on Step 2 we created the virtual environment using the--system-site-packagesflag, python will consider thatamescapis already installed when creating the new virtual environment and pull the code from that location, which may change the structure of the~/amesCAP/bindirectory within the virtual environment. If that is the case, the recommended approach is to exit the virtual environment (deactivate), runpip uninstall amescapto remove CAP from the main python distribution, and start over at Step 2.
This completes the one-time installation of CAP in your virtual environment, amesCAP, which now looks like:
amesCAP/
-├── bin
-│ ├── MarsFiles.py
-│ ├── MarsInterp.py
-│ ├── MarsPlot.py
-│ ├── MarsPull.py
-│ ├── MarsVars.py
-│ ├── activate
-│ ├── activate.csh
-│ ├── deactivate
-│ ├── pip
-│ └── python3
-├── lib
-│ └── python3.7
-│ └── site-packages
-│ ├── netCDF4
-│ └── amescap
-│ ├── FV3_utils.py
-│ ├── Ncdf_wrapper.py
-│ └── Script_utils.py
-├── mars_data
-│ └── Legacy.fixed.nc
-└── mars_templates
- ├──amescap_profile
- └── legacy.in
--
Using conda
-If you prefer using the conda package manager for setting up your virtual environment instead of pip, you may use the following commands to install CAP.
First, verify (using conda info or which conda) that you are using the intented conda executable (two or more versions of conda might be present if both Python2 and Python3 are installed on your system). Then, create the virtual environment with:
(local)>$ conda create -n amesCAP
-Activate the virtual environment, then install CAP:
-(local)>$ conda activate amesCAP
-(amesCAP)>$ conda install pip
-# FROM AN ARCHIVE:
-(amesCAP)>$ cd ~/Downloads
-(amesCAP)>$ tar -xf AmesCAP-master.zip
-(amesCAP)>$ cd AmesCAP-master
-(amesCAP)>$ pip install .
-# OR FROM THE GITHUB:
-(amesCAP)>$ pip install git+https://github.com/NASA-Planetary-Science/AmesCAP.git
-The source code will be installed in:
-/path/to/anaconda3/envs/amesCAP/
-and the virtual environment may be activated and deactivated with conda:
(local)>$ conda activate amesCAP
-(amesCAP)>$ conda deactivate
-(local)>$
---Note: CAP requires the following Python packages, which were automatically installed with CAP:
--matplotlib # the MatPlotLib plotting library -numpy # math library -scipy # math library and input/output for fortran binaries -netCDF4 Python # handling netCDF files -requests # downloading GCM output from the MCMC Data Portal -
-
Removing CAP
-To permanently remove CAP, activate the virtual environment and run the uninstall command:
(local)>$ source amesCAP/bin/activate # bash
-(local)>$ source amesCAP/bin/activate.csh # csh/tcsh
-(local)>$ source amesCAP/Scripts/activate.csh # Cygwin/Windows
-(amesCAP)>$ pip uninstall amescap
-You may also delete the amesCAP virtual environment directory at any time. This will uninstall CAP, remove the virtual environment from your machine, and will not affect your main Python distribution.
-
3. Testing & Using CAP
-Whenever you want to use CAP, simply activate the virtual environment and all of CAP's executables will be accessible from the command line:
-(local)>$ source amesCAP/bin/activate # bash
-(local)>$ source amesCAP/bin/activate.csh # csh/tcsh
-(local)>$ source amesCAP/Scripts/activate.csh # Cygwin/Windows
-You can check that the tools are installed properly by typing Mars and then pressing the TAB key. No matter where you are on your system, you should see the following pop up:
(amesCAP)>$ Mars[TAB]
-> MarsFiles.py MarsInterp.py MarsPlot.py MarsPull.py MarsVars.py
-If no executables show up then the paths have not been properly set in the virtual environment. You can either use the full paths to the executables:
-(amesCAP)>$ ~/amesCAP/bin/MarsPlot.py
-Or set up aliases in your ./bashrc or .cshrc:
# with bash:
-(local)>$ echo alias MarsPlot='/Users/username/amesCAP/bin/MarsPlot.py' >> ~/.bashrc
-(local)>$ source ~/.bashrc
-
-# with csh/tsch
-(local)>$ echo alias MarsPlot /username/amesCAP/bin/MarsPlot >> ~/.cshrc
-(local)>$ source ~/.cshrc
--
4. Practical Tips for Later Use During the Tutorial
-Install ghostscript to Create Multiple-Page PDFs When Using MarsPlot
-Installing ghostscript on your local machine allows CAP to generate a multiple-page PDF file instead of several individual PNGs when creating several plots. Without ghostcript, CAP defaults to generating multiple .png files instead of a single PDF file, and we therefore strongly recommend installing ghostscript to streamline the plotting process.
First, check whether you already have ghostscript on your machine. Open a terminal and type:
(local)>$ gs -version
-> GPL Ghostscript 9.54.0 (2021-03-30)
-> Copyright (C) 2021 Artifex Software, Inc. All rights reserved.
-If ghostscript is not installed, follow the directions on the ghostscript website to install it.
--If
-gs -versionreturns a 'command not found error' but you are able to locate thegsexecutable on your system (e.g. /opt/local/bin/gs) you may need to add that specific directory (e.g. /opt/local/bin/) to your search $PATH as done for Python and pip in Step 1
Enable Syntax Highlighting for the Plot Template
-The MarsPlot executable requires an input template with the .in file extension. We recommend using a text editor that provides language-specific (Python) syntax highlighting to make keywords more readable. A few options include: Atom and vim (compatible with MacOS, Windows, Linux), notepad++ (compatible with Windows), or gedit (compatible with Linux).
The most commonly used text editor is vim. Enabling proper syntax-highlighting for Python in vim can be done by adding the following lines to ~/.vimrc:
syntax on
-colorscheme default
-au BufReadPost *.in set syntax=python
--
5. Do This Before Attending the Tutorial
-In order to follow along with the practical part of the MGCM Tutorial, we ask that you download several MGCM output files beforehand. You should save these on the machine you'll be using during the tutorial.
-We'll use CAP to retrieve these files from the MGCM Data Portal. To begin, activate the virtual environment:
-(local)>$ source amesCAP/bin/activate # bash
-(local)>$ source amesCAP/bin/activate.csh # csh/tcsh
-Choose a directory in which to store these MGCM output files on your machine. We will also create two sub- directories, one for an MGCM simulation with radiatively inert clouds (RIC) and one for an MGCM simulation with radiatively active clouds (RAC):
-(amesCAP)>$ mkdir CAP_tutorial
-(amesCAP)>$ cd CAP_tutorial
-(amesCAP)>$ mkdir INERTCLDS ACTIVECLDS
-Then, download the corresponding data in each directory:
-(amesCAP)>$ cd INERTCLDS
-(amesCAP)>$ MarsPull.py -id INERTCLDS -ls 255 285
-(amesCAP)>$ cd ../ACTIVECLDS
-(amesCAP)>$ MarsPull.py -id ACTIVECLDS -ls 255 285
-Finally, check for files integrity using the disk use command:
cd ..
-du -h INERTCLDS/fort.11*
-du -h ACTIVECLDS/fort.11*
-> 433M fort.11_0719
-[...]
-The files should be 433Mb each. That's it! CAP_tutorial now holds the necessary fort.11 files from the radiatively active and inert MGCM simulations:
CAP_tutorial/
-├── INERTCLDS/
-│ └── fort.11_0719 fort.11_0720 fort.11_0721 fort.11_0722 fort.11_0723
-└── ACTIVECLDS/
- └── fort.11_0719 fort.11_0720 fort.11_0721 fort.11_0722 fort.11_0723
-You can now deactivate the virtual environment:
-(amesCAP)>$ deactivate
---If you encounter an issue during the download process or if the files are not 433Mb, please verify the files availability on the MCMC Data Portal and try again later. You can re-attempt to download specific files as follows:
-MarsPull.py -id ACTIVECLDS -f fort.11_0720 fort.11_0723(make sure to navigate to the appropriate simulation directory first), or simply download the 10 files listed above manually from the website.
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/tutorial/out/README.html b/tutorial/out/README.html
deleted file mode 100644
index 6eaff69a..00000000
--- a/tutorial/out/README.html
+++ /dev/null
@@ -1,2882 +0,0 @@
-
-
-
-
-
-
-
-
-1.
-
-2.
-
-
-
-
-
-
-
-3.
-
-
-
-
-
-4.
-
-
-
-
-
-5.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Table of Contents
--
-
- Introducing the Community Analysis Pipeline (CAP) -
- Cheat sheet -
- The big question... How do I do this? > Ask for help! -
- 1.
MarsPull.py- Downloading Raw MGCM Output
- - 2.
MarsFiles.py- Reducing the Files
- - 3.
MarsVars.py- Performing Variable Operations
- - 4.
MarsInterp.py- Interpolating the Vertical Grid
- - 5.
MarsPlot.py- Plotting the Results
- - MarsPlot.py: How to?
-
-
-
- Inspect the content of netCDF files -
- Disable or add a new plot -
- Adjust the color range and colormap -
- Make a 1D-plot -
- Customize 1D plots -
- Put multiple plots on the same page -
- Put multiple 1D-plots on the same page -
- Use a different epoch -
- Access simulation in a different directory -
- Overwrite the free dimensions. -
- Element-wise operations -
- Code comments and speed-up processing -
- Change projections -
- Figure format, size -
- Access CAP libraries and make your own plots -
- Debugging -
-
-
Introducing the Community Analysis Pipeline (CAP)
-CAP is a toolkit designed to simplify the post-processing of MGCM output. CAP is written in Python and works with existing Python libraries, allowing any Python user to install and use CAP easily and free of charge. Without CAP, plotting MGCM output requires that a user provide their own scripts for post-processing, including code for interpolating the vertical grid, computing and adding derived variables to files, converting between file types, and creating diagnostic plots. In other words, a user would be responsible for the entire post-processing effort as illustrated in Figure 1.
-
Such a process requires that users be familiar with Fortran files and be able to write (or provide) script(s) to perform file manipulations and create plots. CAP standardizes the post-processing effort by providing executables that can perform file manipulations and create diagnostic plots from the command line. This enables users of almost any skill level to post-process and plot MGCM data (Figure 2).
-
As a foreword, we will list a few design characteristics of CAP:
--
-
- CAP is written in Python, an open-source programming language with extensive scientific libraries available -
- CAP is installed within a Python virtual environment, which provides cross-platform support (MacOS, Linux and Windows), robust version control (packages updated within the main Python distribution will not affect CAP), and is not intrusive as it disappears when deactivated -
- CAP is composed of a set of libraries (functions), callable from a user's own scripts and a collection of five executables, which allows for efficient processing of model outputs from the command-line. -
- CAP uses the netCDF4 data format, which is widely use in the climate modeling community and self-descriptive (meaning that a file contains explicit information about its content in term of variables names, units etc...) -
- CAP uses a convention for output formatting inherited from the GFDL Finite-Volume Cubed-Sphere Dynamical Core, referred here as "FV3 format": outputs may be binned and averaged in time in various ways for analysis. -
- CAP long-term goal is to offer multi-model support. At the time of the writing, both the NASA Ames Legacy GCM and the NASA Ames GCM with the FV3 dynamical core are supported. Efforts are underway to offer compatibility to others Global Climate Models (e.g. eMARS, LMD, MarsWRF). -
Specifically, CAP consists of five executables:
--
-
MarsPull.pyAccess MGCM output
-MarsFiles.pyReduce the files
-MarsVars.pyPerform variable operations
-MarsInterp.pyInterpolate the vertical grid
-MarsPlot.pyVisualize the MGCM output
-
These executables and their commonly-used functions are illustrated in the cheat sheet below in the order in which they are most often used. You should feel free to reference during and after the tutorial.
-Cheat sheet
-
CAP is designed to be modular. For example, a user could post-process and plot MGCM output exclusively with CAP or a user could employ their own post-processing routine and then use CAP to plot the data. Users are free to selectively integrate CAP into their own analysis routine to the extent they see fit.
--
The big question... How do I do this? > Ask for help!
-Use the --help (-h for short) option on any executable to display documentation and examples.
(amesGCM3)>$ MarsPlot.py -h
-> usage: MarsPlot.py [-h] [-i INSPECT_FILE] [-d DATE [DATE ...]] [--template]
-> [-do DO] [-sy] [-o {pdf,eps,png}] [-vert] [-dir DIRECTORY]
-> [--debug]
-> [custom_file]
--
1. MarsPull.py - Downloading Raw MGCM Output
-MarsPull is a utility for accessing MGCM output files hosted on the MCMC Data portal. MGCM data is archived in 1.5 hour intervals (16x/day) and packaged in files containing 10 sols. The files are named fort.11_XXXX in the order they were produced, but MarsPull maps those files to specific solar longitudes (Ls, in °). This allows users to request a file at a specific Ls or for a range of Ls using the -ls flag. Additionally the identifier (-id) flag is used to route MarsPull through a particular simulation. The filename (-f) flag can be used to parse specific files within a particular directory.
MarsPull.py -id INERTCLDS -ls 255 285
-MarsPull.py -id ACTIVECLDS -f fort.11_0720 fort.11_0723
--
2. MarsFiles.py - Reducing the Files
-MarsFiles provides several tools for file manipulations, including code designed to create binned, averaged, and time-shifted files from MGCM output. The -fv3 flag is used to convert fort.11 binaries to the Netcdf data format (you can select one or more of the file format listed below):
(amesGCM3)>$ MarsFiles.py fort.11* -fv3 fixed average daily diurn
-These are the file formats that MarsFiles can create from the fort.11 MGCM output files.
Primary files
-| File name | -Description | -Timesteps for 10 sols x 16 output/sol | -Ratio to daily file (430Mb) | -
|---|---|---|---|
| atmos_daily.nc | -continuous time series | -(16 x 10)=160 | -1 | -
| atmos_diurn.nc | -data binned by time of day and 5-day averaged | -(16 x 2)=32 | -x5 smaller | -
| atmos_average.nc | -5-day averages | -(1 x 2) = 2 | -x80 smaller | -
| fixed.nc | -statics variable such as surface albedo and topography | -static | -few kB | -
Secondary files
-| File name | -description | -
|---|---|
| daily**_lpf**,_hpf,_bpf | -low, high and band pass filtered | -
| diurn**_T** | -uniform local time (same time of day at all longitudes) | -
| diurn**_tidal** | -tidally-decomposed files into harmonics | -
| daily**_to_average** _to_diurn | -custom re-binning of daily files | -
-
-
MarsFilescan concatenate like-files together along the time dimension using the-combine(-c) flag.
-
> 07180.atmos_average.nc 07190.atmos_average.nc 07200.atmos_average.nc # 3 files with 10 days of output each
-(amesGCM3)>$ MarsFiles.py *atmos_average.nc -c
-> 07180.atmos_average.nc # 1 file with 30 days of output
-
-3pm surface temperature before (left) and after (right) processing a diurn file with MarsFile to uniform local time (diurn_T.nc)
-
3. MarsVars.py - Performing Variable Operations
-MarsVars provides several tools relating to variable operations such as adding and removing variables, and performing column integrations. With no other arguments, passing a file to MarsVars displays file content, much like ncdump:
(amesGCM3)>$ MarsVars.py 00000.atmos_average.nc
->
-> ===================DIMENSIONS==========================
-> ['bnds', 'time', 'lat', 'lon', 'pfull', 'scalar_axis', 'phalf']
-> (etc)
-> ====================CONTENT==========================
-> pfull : ('pfull',)= (30,), ref full pressure level [Pa]
-> temp : ('time', 'pfull', 'lat', 'lon')= (4, 30, 180, 360), temperature [K]
-> (etc)
-A typical option of MarsVars would be to add the atmospheric density rho to a file. Because the density is easily computed from the pressure and temperature fields, we do not archive in in the GCM output and instead provides a utility to add it as needed. This conservative approach to logging output allows to minimize disk space and speed-up post processing.
(amesGCM3)>$ MarsVars.py 00000.atmos_average.nc -add rho
-We can see that rho was added by calling MarsVars with no argument as before:
(amesGCM3)>$ MarsVars.py 00000.atmos_average.nc
->
-> ===================DIMENSIONS==========================
-> ['bnds', 'time', 'lat', 'lon', 'pfull', 'scalar_axis', 'phalf']
-> (etc)
-> ====================CONTENT==========================
-> pfull : ('pfull',)= (30,), ref full pressure level [Pa]
-> temp : ('time', 'pfull', 'lat', 'lon')= (4, 30, 180, 360), temperature [K]
-> rho : ('time', 'pfull', 'lat', 'lon')= (4, 30, 180, 360), density (added postprocessing) [kg/m3]
-The help (-h) option provides information on available variables and needed fields for each operation.
MarsVars also offers the following variable operations:
| Command | -flag | -action | -
|---|---|---|
| add | --add | -add a variable to the file | -
| remove | --rm | -remove a variable from a file | -
| extract | --extract | -extract a list of variables to a new file | -
| col | --col | -column integration, applicable to mixing ratios in [kg/kg] | -
| zdiff | --zdiff | -vertical differentiation (e.g. compute gradients) | -
| zonal_detrend | --zd | -zonally detrend a variable | -
-
4. MarsInterp.py - Interpolating the Vertical Grid
-Native MGCM output files use a terrain-following pressure coordinate as the vertical coordinate (pfull), which means the geometric heights and the actual mid-layer pressure of atmospheric layers vary based on the location (i.e. between adjacent grid points). In order to do any rigorous spatial averaging, it is therefore necessary to interpolate each vertical column to a same (standard) pressure grid (_pstd grid):
Pressure interpolation from the reference pressure grid to a standard pressure grid
-MarsInterp is used to perform the vertical interpolation from reference (pfull) layers to standard (pstd) layers:
(amesGCM3)>$ MarsInterp.py 00000.atmos_average.nc
-An inspection of the file shows that the pressure level axis which was pfull (30 layers) has been replaced by a standard pressure coordinate pstd (36 layers), and all 3- and 4-dimensional variables reflect the new shape:
(amesGCM3)>$ MarsInterp.py 00000.atmos_average.nc
-(amesGCM3)>$ MarsVars.py 00000.atmos_average_pstd.nc
->
-> ===================DIMENSIONS==========================
-> ['bnds', 'time', 'lat', 'lon', 'scalar_axis', 'phalf', 'pstd']
-> ====================CONTENT==========================
-> pstd : ('pstd',)= (36,), pressure [Pa]
-> temp : ('time', 'pstd', 'lat', 'lon')= (4, 36, 180, 360), temperature [K]
-MarsInterp support 3 types of vertical interpolation, which may be selected by using the --type (-t for short) flag:
| file type | -description | -low-level value in a deep crater | -
|---|---|---|
| _pstd | -standard pressure [Pa] (default) | -1000Pa | -
| _zstd | -standard altitude [m] | --7000m | -
| _zagl | -standard altitude above ground level [m] | -0 m | -
-
Use of custom vertical grids
-MarsInterp uses default grids for each of the interpolation listed above but it is possible for the user to specify the layers for the interpolation. This is done by editing a hidden file .amesgcm_profile(note the dot '.) in your home directory.
For the first use, you will need to copy a template of amesgcm_profile to your /home directory:
(amesGCM3)>$ cp ~/amesGCM3/mars_templates/amesgcm_profile ~/.amesgcm_profile # Note the dot '.' !!!
-You can open ~/.amesgcm_profile with any text editor:
> <<<<<<<<<<<<<<| Pressure definitions for pstd |>>>>>>>>>>>>>
-
->p44=[1.0e+03, 9.5e+02, 9.0e+02, 8.5e+02, 8.0e+02, 7.5e+02, 7.0e+02,
-> 6.5e+02, 6.0e+02, 5.5e+02, 5.0e+02, 4.5e+02, 4.0e+02, 3.5e+02,
-> 3.0e+02, 2.5e+02, 2.0e+02, 1.5e+02, 1.0e+02, 7.0e+01, 5.0e+01,
-> 3.0e+01, 2.0e+01, 1.0e+01, 7.0e+00, 5.0e+00, 3.0e+00, 2.0e+00,
-> 1.0e+00, 5.0e-01, 3.0e-01, 2.0e-01, 1.0e-01, 5.0e-02, 3.0e-02,
-> 1.0e-02, 5.0e-03, 3.0e-03, 5.0e-04, 3.0e-04, 1.0e-04, 5.0e-05,
-> 3.0e-05, 1.0e-05]
->
->phalf_mb=[50]
-In the example above, the user custom-defined two vertical grids, one with 44 levels (named p44) and one with a single layer at 50 Pa =0.5mbar(named phalf_mb)
You can use these by calling MarsInterp with the -level (-l) argument followed by the name of the new grid defined in .amesgcm_profile.
(amesGCM3)>$ MarsInterp.py 00000.atmos_average.nc -t pstd -l p44
--
5. MarsPlot.py - Plotting the Results
-The last component of CAP is the plotting routine, MarsPlot, which accepts a modifiable template (Custom.in) containing a list of plots to create. MarsPlot is useful for creating plots from MGCM output quickly, and it is designed specifically for use with the netCDF output files (daily, diurn, average, fixed).
The following figure shows the three components of MarsPlot:
--
-
- MarsPlot.py, opened in a terminal to inspect the netcdf files and ingest the Custom.in template -
- Custom.in , a template opened in a text editor -
- Diagnostics.pdf, refreshed in a pdf viewer -
The default template, Custom.in, can be created by passing the -template argument to MarsPlot. Custom.in is pre-populated to draw two plots on one page: a topographical plot from the fixed file and a cross-section of the zonal wind from the average file. Creating the template and passing it into MarsPlot creates a PDF containing the plots:
(amesGCM3)>$ MarsPlot.py -template
-> /path/to/simulation/run_name/history/Custom.in was created
-(amesGCM3)>$
-(amesGCM3)>$ MarsPlot.py Custom.in
-> Reading Custom.in
-> [----------] 0 % (2D_lon_lat :fixed.zsurf)
-> [#####-----] 50 % (2D_lat_lev :atmos_average.ucomp, Ls= (MY 2) 252.30, zonal avg)
-> [##########]100 % (Done)
-> Merging figures...
-> /path/to/simulation/run_name/history/Diagnostics.pdf was generated
-Specifically MarsPlot is designed to generate 2D cross - sections and 1D plots. -Let's remind ourselves that in order to create such plots from a multi-dimensional dataset, we first need to specify the free dimensions, meaning the ones that are not plotted.
-
A refresher on cross-section for multi-dimensional datasets
-The data selection process to make any particular cross section is shown in the decision tree below. If an effort to make the process of generating multiple plots as streamlined as possible, MarsPlot selects a number of default settings for the user.
-1. Which simulation ┌─
- (e.g. ACTIVECLDS directory) │ DEFAULT 1. ref> is current directory
- │ │ SETTINGS
- └── 2. Which XXXXX epoch │ 2. latest XXXXX.fixed in directory
- (e.g. 00668, 07180) └─
- │ ┌─
- └── 3. Which type of file │
- (e.g. diurn, average_pstd) │ USER 3. provided by user
- │ │ PROVIDES
- └── 4. Which variable │ 4. provided by user
- (e.g. temp, ucomp) └─
- │ ┌─
- └── 5. Which dimensions │ 5. see rule table below
- (e.g lat =0°,Ls =270°) │ DEFAULT
- │ │ SETTINGS
- └── 6. plot customization │ 6. default settings
- (e.g. colormap) └─
-
-The free dimensions are set by default using day-to-day decisions from a climate modeler's perspective:
-| Free dimension | -Statement for default setting | -Implementation | -
|---|---|---|
| time | -"I am interested in the most recent events" | -time = Nt (last timestep) | -
| level | -"I am more interested in the surface than any other vertical layer" | -level = sfc | -
| latitude | -"If I have to pick a particular latitude, I would rather look at the equator" | -lat=0 (equator) | -
| longitude | -"I am more interested in a zonal average than any particular longitude" | -lon=all (average over all values) | -
| time of day | -"3pm =15hr Ok, this one is arbitrary. However if I use a diurn file, I have a specific time of day in mind" | -tod=15 | -
Rule table for the default settings of the free dimensions
-In practice, these cases cover 99% of the work typically done so whenever a setting is left to default (= None in MarsPlot's syntax) this is what is being used. This allows to considerably streamline the data selection process.
Custom.in can be modified using your preferred text editor (and renamed to your liking). This is an example of the code snippet in Custom.in used to generate a lon/lat cross-section. Note that the heading is set to = True, so that plot is activated for MarsPlot to process.
<<<<<<<<<<<<<<| Plot 2D lon X lat = True |>>>>>>>>>>>>>
-Title = None
-Main Variable = atmos_average.temp
-Cmin, Cmax = None
-Ls 0-360 = None
-Level [Pa/m] = None
-2nd Variable = None
-Contours Var 2 = None
-Axis Options : lon = [None,None] | lat = [None,None] | cmap = jet | scale = lin | proj = cart
-
-In the example above, we are plotting the air temperature field temp from the atmos_average.nc file as a lon/lat map. temp is a 4D field (time, level, lat, lon) but since we left the time (Ls 0-360) and altitude (Level [Pa/m]) unspecified (i.e. set to None) MarsPlot will show us the last timestep in the file and the layer immediately adjacent to the surface. Similarly, MarsPlot will generate a default title for the figure with the variable's name (temperature), unit ([K]), selected dimensions (last timestep, at the surface), and makes educated choices for the range of the colormap, axis limits etc ... All those options are customizable, if desired. Finally, note the option of adding a secondary variable as solid contours. For example, one may set 2nd Variable = fixed.zsurf to plot the topography (zsurf) from the matching XXXXX.fixed.nc file.
To wrap-up (the use of {} to overwrite default settings is discussed later on), the following two working expressions are strictly equivalent for Main Variable = (shaded contours) or 2nd Variable = (solid contours) fields:
variable variable
- │ SIMPLIFY TO │
-00668.atmos_average@1.temp{lev=1000;ls=270} >>> atmos_average.temp
- │ │ │ │ │
-epoch file type simulation free dimensions file type
- directory
-These are the four types of accepted entries for the free dimensions:
-| Accepted input | -Meaning | -Example | -
|---|---|---|
None |
-Use default settings from the rule table above | -Ls 0-360 = None |
-
value |
-Return index closest to requested value in the figure'sunit | -Level [Pa/m] = 50 (50 Pa) |
-
Val Min, Val Max |
-Return the average between two values | -Lon +/-180 = -30,30 |
-
all |
-all is a special keyword that return the average over all values along that dimension |
-Latitude = all |
-
Accepted values for the Ls 0-360, Level [Pa/m] ,Lon +/-180, Latitude and time of day free dimensions
--The time of day (
-tod) in diurn files is always specified using brackets{}, e.g. :Main Variable = atmos_diurn.temp{tod=15,18}for the average between 3pm and 6pm. This has allowed to streamlined all templates by not including the time of day free dimension, which is specific to diurn files.
MarsPlot.py: How to?
-This section discusses MarsPlot capabilities. Note that a compact version of these instructions is present as comment at the very top of a new Custom.in and can be used as a quick reference:
===================== |MarsPlot V3.2|===================
-# QUICK REFERENCE:
-# > Find the matching template for the desired plot type. Do not edit any labels left of any '=' sign
-# > Duplicate/remove any of the <<<< blocks>>>>, skip by setting <<<< block = False >>>>
-# > 'True', 'False' and 'None' are capitalized. Do not use quotes '' anywhere in this file
-etc...
-Inspect the content of netCDF files
-A handy function is MarsPlot's --inspect (-i for short) command which displays the content of a netCDF file:
(amesGCM3)> MarsPlot.py -i 07180.atmos_average.nc
-
-> ===================DIMENSIONS==========================
-> ['lat', 'lon', 'pfull', 'phalf', 'zgrid', 'scalar_axis', 'time']
-> [...]
-> ====================CONTENT==========================
-> pfull : ('pfull',)= (24,), ref full pressure level [Pa]
-> temp : ('time', 'pfull', 'lat', 'lon')= (10, 24, 36, 60), temperature [K]
-> ucomp : ('time', 'pfull', 'lat', 'lon')= (10, 24, 36, 60), zonal wind [m/sec]
-> [...]
---Note that the
--imethod works with any netCDF file, not just the ones generated by CAP
The --inspect method can be combined with the --dump flag which is most useful to show the content of specific 1D arrays in the terminal.
(amesGCM3)>$ MarsPlot.py -i 07180.atmos_average.nc -dump pfull
-> pfull=
-> [8.7662227e-02 2.5499690e-01 5.4266089e-01 1.0518962e+00 1.9545468e+00
-> 3.5580616e+00 6.2466631e+00 1.0509957e+01 1.7400265e+01 2.8756382e+01
-> 4.7480076e+01 7.8348366e+01 1.2924281e+02 2.0770235e+02 3.0938846e+02
-> 4.1609518e+02 5.1308148e+02 5.9254102e+02 6.4705731e+02 6.7754218e+02
-> 6.9152936e+02 6.9731799e+02 6.9994830e+02 7.0082477e+02]
-> ______________________________________________________________________
-The --stat flag is better suited to inspect large, multi-dimensional arrays. You can also request specific array indexes using quotes and square brackets '[]':
(amesGCM3)>$ MarsPlot.py -i 07180.atmos_average.nc --stat ucomp 'temp[:,-1,:,:]'
-__________________________________________________________________________
- VAR | MIN | MEAN | MAX |
-__________________________|_______________|_______________|_______________|
- ucomp| -102.98| 6.99949| 192.088|
- temp[:,-1,:,:]| 149.016| 202.508| 251.05|
-__________________________|_______________|_______________|_______________|
----
-1refers to the last element in the that axis, following Python's indexing convention
-
Disable or add a new plot
-Code blocks set to = True instruct MarsPlot to draw those plots. Other templates in Custom.in are set to = False by default, which instructs MarsPlot to skip those plots. In total, MarsPlot is equipped to create seven plot types:
<<<<<| Plot 2D lon X lat = True |>>>>>
-<<<<<| Plot 2D lon X time = True |>>>>>
-<<<<<| Plot 2D lon X lev = True |>>>>>
-<<<<<| Plot 2D lat X lev = True |>>>>>
-<<<<<| Plot 2D time X lat = True |>>>>>
-<<<<<| Plot 2D time X lev = True |>>>>>
-<<<<<| Plot 1D = True |>>>>> # Any 1D Plot Type (Dimension x Variable)
-Adjust the color range and colormap
-Cmin, Cmax (and Contours Var 2) are how the contours are set for the shaded (and solid) contours. If only two values are included, MarsPlot use 24 contours spaced between the max and min values. If more than two values are provided, MarsPlot will use those individual contours.
Main Variable = atmos_average.temp # filename.variable *REQUIRED
-Cmin, Cmax = 240,290 # Colorbar limits (minimum, maximum)
-2nd Variable = atmos_average.ucomp # Overplot U winds
-Contours Var 2 = -200,-100,100,200 # List of contours for 2nd Variable or CMIN, CMAX
-Axis Options : Ls = [None,None] | lat = [None,None] | cmap = jet |scale = lin
-Note the option of setting the contour spacing linearly scale = lin or logarithmically (scale = log) if the range of values spans multiple order of magnitudes.
The default colormap cmap = jet may be changed using any Matplotlib colormaps. A selections of those are listed below:
Finally, note the use of the _r suffix (reverse) to reverse the order of the colormaps listed in the figure above. From example, using cmap = jet would have colors spanning from blue > red and cmap = jet_r red > blue instead
Supported colormaps in Marsplot. The figure was generated using code from the scipy webpage .
--
Make a 1D-plot
-The 1D plot template is different from the others in a few key ways:
--
-
- Instead of
Title, the template requires aLegend. When overploting several 1D variables on top of one another, the legend option will label them instead of changing the plot title.
- - There is an additional
linestyleaxis option for the 1D plot.
- - There is also a
Diurnaloption. TheDiurnalinput can only beNoneorAXIS, since there is syntax for selecting a specific time of day using parenthesis (e.g.atmos_diurn.temp{tod=15}) TheAXISlabel tellsMarsPlotwhich dimension serves as the X axis.Main Variablewill dictate the Y axis.
-
--Some plots like vertical profiles and latitude plots use instead Y as the primary axis and plot the variable on the X axis
-
<<<<<<<<<<<<<<| Plot 1D = True |>>>>>>>>>>>>>
-Legend = None # Legend instead of Title
-Main Variable = atmos_average.temp
-Ls 0-360 = AXIS # Any of these can be selected
-Latitude = None # as the X axis dimension, and
-Lon +/-180 = None # the free dimensions can accept
-Level [Pa/m] = None # values as before. However,
-Diurnal [hr] = None # ** Diurnal can ONLY be AXIS or None **
-Customize 1D plots
-Axis Options specify the axes limits, and linestyle 1D-plot:
| 1D plot option | -Usage | -Example | -
|---|---|---|
lat,lon+/-180,[Pa/m],sols = [None,None] |
-range for X or Y axes limit depending on the plot type | -lat,lon+/-180,[Pa/m],sols = [1000,0.1] |
-
var = [None,None] |
-range for the plotted variable on the other axis | -var = [120,250] |
-
linestyle = - |
-Line style following matplotlib's convention | -linestyle = -ob (solid line & blue circular markers) |
-
axlabel = None |
-Change the default name for the axis | -axlabel = New Temperature [K] |
-
Here is a sample of colors, linestyles and marker styles that can be used in 1D-plots
-
Supported styles for 1D plots. This figure was also generated using code from scipy-lectures.org
--
Put multiple plots on the same page
-You can sandwich any number of plots between the HOLD ON and HOLD OFF keywords to group figures on the same page.
> HOLD ON
->
-> <<<<<<| Plot 2D lon X lat = True |>>>>>>
-> Title = Surface CO2 Ice (g/m2)
-> .. (etc) ..
->
-> <<<<<<| Plot 2D lon X lat = True |>>>>>>
-> Title = Surface Wind Speed (m/s)
-> .. (etc) ..
->
-> HOLD OFF
-By default, MarsPlot will use a default layout for the plots, this can be modified by adding the desired number of lines and number of columns, separated by a comma: HOLD ON 4,3 will organize the figure with a 4 -lines and 3-column layout.
Note that Custom.in comes with two plots pre-loaded on the same page.
--
Put multiple 1D-plots on the same page
-Similarly adding the ADD LINE keywords between two (or more) templates can be used to place multiple 1D plots on the same figure.
> <<<<<<| Plot 1D = True |>>>>>>
-> Main Variable = var1
-> .. (etc) ..
->
-> ADD LINE
->
-> <<<<<<| Plot 1D = True |>>>>>>
-> Main Variable = var2
-> .. (etc) ..
---Note that if you combine
-HOLD ON/HOLD OFFandADD LINEto create a 1D figure with several sub-plots on a multi-figure page, the 1D plot has to be the LAST (and only 1D-figure with sub-plots) on that page.
-
Use a different epoch
-If you have run a GCM simulation for a long time, you may have several files of the same type, e.g. :
-00000.fixed.nc 00100.fixed.nc 00200.fixed.nc 00300.fixed.nc
-00000.atmos_average.nc 00100.atmos_average.nc 00200.atmos_average.nc 00300.atmos_average.nc
-By default MarsPlot counts the fixed files in the directory and run the analysis on the last set of files, 00300.fixed.nc and 00300.atmos_average.nc in our example. Even though you may specify the epoch for each plot (e.g. Main Variable = 00200.atmos_average.temp for the file starting at 200 sols), it is more convenient to leave the epoch out of the Custom.in and instead pass the -date argument to MarsPlot.
MarsPlot.py Custom.in -d 200
----
-datealso accepts a range of sols, e.g.MarsPlot.py Custom.in -d 100 300which will run the plotting routine across multiple files.
When creating 1D plots of data spanning multiple years, you can overplot consecutive years on top of the other instead of sequentially by calling --stack_year (-sy) when submitting the template to MarsPlot.
-
Access simulation in a different directory
-At the beginning of MarsPlot is the <<< Simulations >>> block which, is used to point MarsPlot to different directories containing MGCM outputs. When set to None, ref> (the simulation directory number @1, optional in the templates) refers to the current directory:
<<<<<<<<<<<<<<<<<<<<<< Simulations >>>>>>>>>>>>>>>>>>>>>
-ref> None
-2> /path/to/another/sim # another simulation
-3>
-=======================================================
-Only 3 simulations have place holders but you can add additional ones if you would like (e.g. 4> ... )
-To access a variable from a file in another directory, just point to the correct simulation when calling Main Variable (or 2nd Variable) using the @ character:
Main Variable = XXXXX.filename@N.variable`
-Where N is the number in <<< Simulations >>> corresponding the the correct path.
-
Overwrite the free dimensions.
-By default, MarsPlot uses the free dimensions provided in each template (Ls 0-360 and Level [Pa/m] in the example below) to reduce the data for both the Main Variable and the 2nd Variable. You can overwrite this behavior by using parenthesis {}, containing a list of specific free dimensions separated by semi-colons ; The free dimensions within the {} parenthesis will ultimately be the last one selected. In the example below, Main Variable (shaded contours) will use a solar longitude of 270° and a pressure of 10 Pa, but the 2nd Variable (solid contours) will use the average of solar longitudes between 90° and 180° and a pressure of 50 Pa.
<<<<<<<<<<<<<<| Plot 2D lon X lat = True |>>>>>>>>>>>>>
-...
-Main Variable = atmos_average.var
-...
-Ls 0-360 = 270
-Level [Pa/m] = 10
-2nd Variable = atmos_average.var{ls=90,180;lev=50}
---Keywords for the dimensions are
-ls,lev,lon,latandtod. Accepted entries areValue(closest),Valmin,Valmax(average between two values) andall(average over all values)
Element-wise operations
-You can encompass variables between square brackets [] to perform element-wise operations, which is useful to compare simulations, apply scaling etc... MarsPlot will first load each variables encompassed with the brackets, and then apply the algebraic expression outside the [] before plotting.
These are examples of potential applications:
- > Main Variable = [fixed.zsurf]/(10.**3) (convert topography from [m] to [km])
- > Main Variable = [atmos_average.taudust_IR]/[atmos_average.ps]*610 (normalize the dust opacity)
- > Main Variable = [atmos_average.temp]-[atmos_average@2.temp] (temp. difference between ref simu and simu 2)
- > Main Variable = [atmos_average.temp]-[atmos_average.temp{lev=10}] (temp. difference between the default (near surface) and the 10 Pa level
--
Code comments and speed-up processing
-Comments are preceded by #, following python's convention. Each <<<<| block |>>>> must stay integral so comments may be inserted between templates or comment all lines of the template (which is why it is generally easier to simply set the <<<<| block = False |>>>>) but not within a template.
You will notice the START key word at the very beginning of the template.
=======================================================
-START
-This instructs MarsPlot to start parsing templates at this point. If you are already happy with multiple plots, you can move the START keyword further down in the Custom.in to skip those first plots instead of setting those to <<<<| Plot = False |>>>> individually. When you are done with your analysis, simply move START back to the top to generate a pdf with all the plots.
Similarly, you can use the keyword STOP (which is not initially present in Custom.in) to stop the parsing of templates. In this case, the only plots processed would be the ones between START and STOP.
-
Change projections
-For Plot 2D lon X lat figures, MarsPlot supports 3 types of cylindrical projections : cart (cartesian), robin (robinson), moll (mollweide), and 3 types of azimuthal projections: Npole (north polar), Spole (south polar) and ortho (orthographic).
-(Top) cylindrical projection cart, robin and moll. (Bottom) azimuthal projections Npole, Spole and ortho
The azimuthal projections accept optional arguments as follows:
-proj = Npole lat_max # effectively zoom in/out on the North pole
-proj = Spole lat_min # effectively zoom in/out on the South pole
-proj = ortho lon_center, lat_center # rotate the globe
--
Figure format, size
--
-
- As shown in the
-helpdocumentation of MarsPlot, the output format for the figure is chosen using the--output(-o) flag between pdf (default, requires the ghostscript software), png, or eps.
- - The
-pw(pixel width) flag can be use to change the page width from its default value of 2000 pixels.
- - The
--vertical(-vert) can be use to make the pages vertical instead of horizontal
-
-
Access CAP libraries and make your own plots
-CAP libraries are located (and documented) in FV3_utils.py. Spectral utilities are located in Spectral_utils.py, classes to parse fortran binaries and generate netCDf files are located in Ncdf_wrapper.py
The following code demonstrate how one can access CAP libraries and make plots for its own analysis:
-#======================= Import python packages ================================
-import numpy as np # for array operations
-import matplotlib.pyplot as plt # python plotting library
-from netCDF4 import Dataset # to read .nc files
-#===============================================================================
-
-# Open a fixed.nc file, read some variables and close it.
-f_fixed=Dataset('/path_to_file/00000.fixed.nc','r')
-lon=f_fixed.variables['lon'][:]
-lat=f_fixed.variables['lat'][:]
-zsurf=f_fixed.variables['zsurf'][:]
-f_fixed.close()
-
-# Open a dataset and read the 'variables' attribute from the NETCDF FILE
-f_average_pstd=Dataset('/path_to_file/00000.atmos_average_pstd.nc','r')
-vars_list =f_average_pstd.variables.keys()
-print('The variables in the atmos files are: ',vars_list)
-
-# Read the 'shape' and 'units' attribute from the temperature VARIABLE
-Nt,Nz,Ny,Nx = f_average_pstd.variables['temp'].shape
-units_txt = f_average_pstd.variables['temp'].units
-print('The data dimensions are Nt,Nz,Ny,Nx=',Nt,Nz,Ny,Nx)
-# Read the pressure, time, and the temperature for an equatorial cross section
-pstd = f_average_pstd.variables['pstd'][:]
-areo = f_average_pstd.variables['areo'][0] #solar longitude for the 1st timestep
-temp = f_average_pstd.variables['temp'][0,:,18,:] #time, press, lat, lon
-f_average_pstd.close()
-
-# Get the latitude of the cross section.
-lat_cross=lat[18]
-
-# Example of accessing functions from the Ames Pipeline if we wanted to plot
-# the data in a different coordinate system (0>360 instead of +/-180 )
-#----
-from amesgcm.FV3_utils import lon180_to_360,shiftgrid_180_to_360
-lon360=lon180_to_360(lon)
-temp360=shiftgrid_180_to_360(lon,temp)
-
-# Define some contours for plotting
-conts= np.linspace(150,250,32)
-
-#Create a figure with the data
-plt.close('all')
-ax=plt.subplot(111)
-plt.contourf(lon,pstd,temp,conts,cmap='jet',extend='both')
-plt.colorbar()
-# Axis labeling
-ax.invert_yaxis()
-ax.set_yscale("log")
-plt.xlabel('Longitudes')
-plt.ylabel('Pressure [Pa]')
-plt.title('Temperature [%s] at Ls %03i, lat= %.2f '%(units_txt,areo,lat_cross))
-plt.show()
-will produce the following image:
-
-
Debugging
-MarsPlot is designed to make plotting MGCM output easier and faster so it handles missing data and many errors by itself. It reports errors both in the terminal and in the generated figures. To by-pass this behavior (when debugging), use the --debug option with MarsPlot which will raise standard Python errors and stop the execution. One thing to always look for are typo/syntax errors in the template so you may want to cross-check your current plot against a pristine (empty) template.
-- -Note that the errors raised with the
---debugflag may reference toMarsPlotinternal classes so they may not always be self-explanatory.
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/tutorial/tutorial_files/CAP_Exercises.pdf b/tutorial/tutorial_files/CAP_Exercises.pdf
deleted file mode 100644
index 8b87b172..00000000
Binary files a/tutorial/tutorial_files/CAP_Exercises.pdf and /dev/null differ
diff --git a/tutorial/tutorial_files/CAP_Install.pdf b/tutorial/tutorial_files/CAP_Install.pdf
deleted file mode 100644
index db774e04..00000000
Binary files a/tutorial/tutorial_files/CAP_Install.pdf and /dev/null differ
diff --git a/tutorial/tutorial_files/CAP_lecture.pdf b/tutorial/tutorial_files/CAP_lecture.pdf
deleted file mode 100644
index 71ab3b92..00000000
Binary files a/tutorial/tutorial_files/CAP_lecture.pdf and /dev/null differ
diff --git a/tutorial/tutorial_files/KEY.zip b/tutorial/tutorial_files/KEY.zip
deleted file mode 100644
index 8c2c1848..00000000
Binary files a/tutorial/tutorial_files/KEY.zip and /dev/null differ
diff --git a/tutorial/tutorial_images/.DS_Store b/tutorial/tutorial_images/.DS_Store
deleted file mode 100644
index 5008ddfc..00000000
Binary files a/tutorial/tutorial_images/.DS_Store and /dev/null differ
-
-
This directory contains tutorial documents describing the installation and functionality for CAP as well as a set of practise exercises. It is a great place to start for new users.
-