Overlay map tutorial

index.rst

@@ -35,6 +35,7 @@ quickly with pyaerocom.
 - `Basic data analysis <getting_started_analysis.html>`__ | *getting_started_analysis.ipynb*
 - `Using pyaerocom to create colocated data objects where colocation was done outside of pyaerocom <making_a_colocated_data_object_with_pyaerocom.html>`__ | *making_a_colocated_data_object_with_pyaerocom.ipynb*
 - `Reading EMEP data into PyAerocom<intro_emep.html>`__ | *intro_emep.ipynb*
+- `Using overlay (pixel) maps<overlay_maps.html>`__ | *overlay_maps.ipynb*
 
 
 Evaluations

overlay_maps.ipynb

@@ -0,0 +1,91 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Using overlay plots (pixel maps)\n",
+    "Lewis Blake\n",
+    "[email protected]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here we present a basic tutorial on how to add overlay plots (AKA pixel maps) to an evaluation on Aeroval. Pyaerocom offers both the ability to plot model and observations as pixel maps amd/or contour maps as of version 0.25.0. These selcetions can be made specific to each model and observation.\n",
+    "\n",
+    "Let's say I have an evaluation where I want to compare EMEP model data with TROPOMI satellite data. Moreover, let's assume that the resolution of each of these data is so large that I do not want to have the standard Aeroval evaluation as that is computationally prohibitive. (Keep in mind that by default each collocated pixel is treated as a single station, and so all statistics are computed over th4ese `StationData` objects.) Rather, what I want is to just show the maps of both the EMEP and TROPOMI data. I need to make the following adjustments in my `CFG` dict.\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Model Maps\n",
+    "only_model_maps=True,\n",
+    "pages = (\"maps\",), \n",
+    "plot_types={\n",
+    "    \"TROPOMI\": [\"overlay\"],\n",
+    "    \"EMEP\": [\"overlay\"],\n",
+    "},\n",
+    "boundaries={\"west\": -50, \"east\": 90, \"south\": 25.0, \"north\": 85.0},\n",
+    "right_menu = (\"TROPOMI\",),\n",
+    "overlay_save_format = \"png\",\n",
+    "maps_freq = \"monthly\", "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Explanation of these arguments:\n",
+    "\n",
+    "- `only_model_map=True`: tells pyaerocom to only produce maps and not do collocation\n",
+    "- `pages = (\"maps\",)`: tells the Aeroval webpage that the only page to show is the maps. corresponds to contents of `data/contour` in the pyaeroval output\n",
+    "- `plot_types`: This is a dictionary where each key is a model or observation provided elsehwere in the config file, and the values are a list, set, or tuple, of the types of plots you which to have. THe options are `\"overlay\"` and `\"contour\"`. If not provided, the default is to make contour plots for all models.\n",
+    "- `boundaries`: Can be passed as a dictionary but is of type `BoundingBox`. Keys are `\"west\"`, `\"east\"`, `\"north\"`, `\"south\"` and the values are the bounding box edges in degrees. Note that this must be consistent across all models and observation networks.\n",
+    "- `right_menu`: Tell Aeroval which of the model or observations to play in the right menu when comparing the maps. In this case the EMEP model maps will appear on the left and the TROPOMI data will appear on the right.\n",
+    "- `overlay_save_format`: Overlay maps can be saved as wither png files or webp files. The options are `\"webp\"` and `\"png\"` and the default is `\"webp\"`.\n",
+    "- `maps_freq`: This is the frequency of which to sample the data the make the maps, either overlay or contour. The default is `\"coarsest\"`, but it is recommended to set this explictly.\n",
+    "\n",
+    "\n",
+    "NB: Pyaerocom will save overlay maps in grayscale, and then Aeroval will apply color to them dynamically on the web."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}