:orphan:

Examples
========



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

Get System Ready
----------------

The first step to running examples is to prepare the computer on. The examples
can be run on Linux, Mac (OS X), or Windows machines. Some of the instructions
will assume you are in a terminal (Linux or Mac), but can be adapted to Windows
Command Prompt or PowerShell.

Steps:

1. Download examples folder.
2. Setup a python version
    * Either with a system Python
    * Or mamba.
3. Get CAMx tutorial files.

Once you have done all these steps, you should will be ready to run example
scripts. The scripts use file paths to "point" to files assuming a relative
folder structure. Each python script (eg, `run_gridemiss_01_perturb.py`)
will be run using python from within its folder (eg, `examples/gridemiss/`).
So, it is important that the folder structure is as expected or you edit
the paths in the scripts.

So, if you were done preparing the system (steps 1-3), you would run an
example script like this on Linux or Mac:

.. code::

    cd ~
    cd examples/gridemiss
    python run_gridemiss_01_perturb.py


Or Windows PowerShell

.. code::

    cd ~
    cd examples/gridemiss
    py.exe run_gridemiss_01_perturb.py

As an alternative, you can run these script by pasting sections of them into an
interactive Python console. For example, on Linux/Mac:

.. code::

    cd ~/examples/gridemiss
    python
    >>> # paste commands here

Or in Windows PowerShell:

.. code::

    cd ~/examples/gridemiss
    py.exe
    >>> # paste commands here

Remember, this will not work until you complete the preparation steps:

1. Getting the examples folder done in `Get Examples Folder`
2. Preparing the python executable is described in the `Preparing Python Environment` (or in the `Using Mamba to get Python`).
3. Getting the CAMx tutorial data is described in the `Getting CAMx Files` example.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The section describes how to get all the examples as python files.">

.. only:: html

  .. image:: /auto_examples/prep/images/thumb/sphx_glr_ex_prep_01_examples_thumb.png
    :alt:

  :doc:`/auto_examples/prep/ex_prep_01_examples`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Get Examples Folder</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The basic steps are:">

.. only:: html

  .. image:: /auto_examples/prep/images/thumb/sphx_glr_ex_prep_02_setup_thumb.png
    :alt:

  :doc:`/auto_examples/prep/ex_prep_02_setup`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Preparing Python Environment</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="::NOTE:: If the previous python setup worked, do not do this example. ::NOTE:: This is just a backup.">

.. only:: html

  .. image:: /auto_examples/prep/images/thumb/sphx_glr_ex_prep_03_mamba_thumb.png
    :alt:

  :doc:`/auto_examples/prep/ex_prep_03_mamba`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Using Mamba to get Python</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip=" Option 1: Get and run the CAMx testcase  Option 2: Get a small .tar.gz">

.. only:: html

  .. image:: /auto_examples/prep/images/thumb/sphx_glr_ex_prep_04_downloadcamx_thumb.png
    :alt:

  :doc:`/auto_examples/prep/ex_prep_04_downloadcamx`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Getting CAMx Files</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Gridded Emission Examples
-------------------------

There are currently two gridded emission examples:

* Scale gridded emissions across the whole domain.
* Scale gridded emissions in a specific region.

*Caveat*:
The "specific region" can be modified to be very specific, but has limits.
The examples work from emissions that have already been gridded, speciated,
and often merged across many "sectors." When trying to make very specific
updates (e.g, a single SCC), sometimes this approach will fall short.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Apply a constant factor to a subset of emission variables in a file.">

.. only:: html

  .. image:: /auto_examples/gridemiss/images/thumb/sphx_glr_run_gridemiss_01_perturb_thumb.png
    :alt:

  :doc:`/auto_examples/gridemiss/run_gridemiss_01_perturb`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Domain-wide Gridded Emission Scaling</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Apply a constant factor to selected emission variables within a region.The region can be as simple as a rectangular box, a circle, or any geographic shape you can define.">

.. only:: html

  .. image:: /auto_examples/gridemiss/images/thumb/sphx_glr_run_gridemiss_02_perturbbox_thumb.png
    :alt:

  :doc:`/auto_examples/gridemiss/run_gridemiss_02_perturbbox`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Region-specific Gridded Emission Scaling</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Point Source Emission Examples
------------------------------

There are currently two point source examples:

* Make a single representative source file.
* Perturb a facilities based on latitude/longitude.

*Caveat*:
These point source examples can be adapted to do many things, but there are
limitations. For example, sometimes "point source emissions" are split between
the amount subject to plume rise and the rest may be merged with the gridded.
In that case, scaling the point source file is not equivalent to scaling a
facility.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example averages all other sources to create a single hypothetical source. It also reports all variables that are in the file, which makes direct modification easy.">

.. only:: html

  .. image:: /auto_examples/ptsrce/images/thumb/sphx_glr_run_ptsrce_01_singlesource_thumb.png
    :alt:

  :doc:`/auto_examples/ptsrce/run_ptsrce_01_singlesource`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Create a Hypothetical Source</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Point sources may be facilities or individual stacks. This example demonstrates how to apply a scaling factor to all sources in some region. The region can be as simple as a rectangular box, a circle, or any geographic shape you can define.">

.. only:: html

  .. image:: /auto_examples/ptsrce/images/thumb/sphx_glr_run_ptsrce_02_editlonlatbox_thumb.png
    :alt:

  :doc:`/auto_examples/ptsrce/run_ptsrce_02_editlonlatbox`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Modify a Selected Source</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Rerun CAMx
----------

- Edit run script to use edited emission files.
- Run CAMx as you normally would.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The basic steps are:">

.. only:: html

  .. image:: /auto_examples/interlude/images/thumb/sphx_glr_ex_camxrerun_thumb.png
    :alt:

  :doc:`/auto_examples/interlude/ex_camxrerun`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Rerun CAMx with Updated Emissions</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Model Performance Evaluation
----------------------------

There are currently two model performance examples. These are meant to be
instructive and do not cover all possibilities. These examples use EPA's
RSIG to aquire AirNow or AQS observations, which is useful for rapid
evaluation and retrospective evalaution.

* Compare CAMx to hourly NO2.
* Compare CAMx to Ozone Maximum Daily 8-hour Average.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Evaluate CAMx by comparing to AirNow or AQS hourly observations.">

.. only:: html

  .. image:: /auto_examples/mpe/images/thumb/sphx_glr_run_mpe_01_no2_thumb.png
    :alt:

  :doc:`/auto_examples/mpe/run_mpe_01_no2`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Compare Model to Hourly Observations</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Evaluate CAMx by comparing to AirNow or AQS Ozone observations using the 2015 Ozone NAAQS definition of the maximum daily 8-hour average metric.">

.. only:: html

  .. image:: /auto_examples/mpe/images/thumb/sphx_glr_run_mpe_02_o3mda8_thumb.png
    :alt:

  :doc:`/auto_examples/mpe/run_mpe_02_o3mda8`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Compare Model to Daily MDA8 Observations</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Satellite Comparison
--------------------

There are currently two satellite processing examples.

* OMI NO2 comparison without updating the model prior, and
* TropOMI NO2 comparison with an updated model prior.

Satellite NO2 use modeled NO2 (eg, GMI or TM5) to quantify the vertical
distribution of NO2, which allows for a quantitative translation from
measurements with differential vertical sensitivity to a best estimate
assuming equal sensitivity. Using your own model as the vertical
distribution ensures an apples to apples comparison.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example compares CAMx to the Ozone Monitoring Instrument (OMI) for NO2 tropospheric vertical column densitities (tropNO2). OMI&#x27;s tropNO2 is derived from a measurement along the path light from the sun and reflected off the surface of the earth. The original measurement is called a slant column density (SCD). The SCD is split into tropospheric and stratospheric parts, based on a model profile (a priori). The a priori and slant path are combined with a sensitivity vector (scattering weight) to convert the tropospheric SCD to tropNO2 [molecules/cm2]. CAMx can output mixing ratios at all levels, which can be converted to molecules/cm2 and summed to make a tropNO2 product. Note, however, that the CAMx tropNO2 inherently assumes a different model profile. A more complete comparison would adjust OMI to use CAMx&#x27;s profile, or adjust CAMx to use OMI&#x27;s profile. Each has strengths and weaknesses.">

.. only:: html

  .. image:: /auto_examples/satellite/images/thumb/sphx_glr_run_satellite_01_simpleomi_thumb.png
    :alt:

  :doc:`/auto_examples/satellite/run_satellite_01_simpleomi`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Simple OMI</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example pairs CAMx 3D data with TropOMI NO2 columns using the CMAQ Satellite Processors (cmaqsatproc). This includes (1) downloading TropOMI data from NASA&#x27;s Distribution and Active Archive Centers (DAAC), (2) regridding TropOMI to the CAMx grid, (3) subseting CAMx to just overpass times, (4) filtering CAMx to valid retrieval pixels/layers, and (5) applying the CAMx a priori shape to the TropOMI retrieval.">

.. only:: html

  .. image:: /auto_examples/satellite/images/thumb/sphx_glr_run_satellite_02_tropomiak_thumb.png
    :alt:

  :doc:`/auto_examples/satellite/run_satellite_02_tropomiak`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Pair CAMx with TropOMI NO2</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Making CAMx Maps
----------------

- Compare originally run CAMx to new run with new emissions.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example compares the standard CAMx v7.3 tutorial simulation to one with updated emissions. The updated emissions come from earlier examples. Those examples adjusted NOx in four ways:">

.. only:: html

  .. image:: /auto_examples/maps/images/thumb/sphx_glr_run_maps_01_compare_thumb.png
    :alt:

  :doc:`/auto_examples/maps/run_maps_01_compare`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Compare Two CAMx Runs</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /auto_examples/prep/index.rst
   /auto_examples/gridemiss/index.rst
   /auto_examples/ptsrce/index.rst
   /auto_examples/interlude/index.rst
   /auto_examples/mpe/index.rst
   /auto_examples/satellite/index.rst
   /auto_examples/maps/index.rst


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download all examples in Python source code: auto_examples_python.zip </auto_examples/auto_examples_python.zip>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download all examples in Jupyter notebooks: auto_examples_jupyter.zip </auto_examples/auto_examples_jupyter.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_