Merge remote-tracking branch 'origin/dev'

docs/source/getting-started/IMI-glossary.rst

@@ -0,0 +1,27 @@
+IMI Glossary
+============
+Glossary of commonly used terms in the Integrated Methane Inversion (IMI) workflow.
+
+
+.. list-table::
+   :widths: 30, 70
+   :class: tight-table
+
+   * - ``Period of interest``
+     - The period for which the IMI will optimize mean emissions based on TROPOMI observations. Specified by start and end dates. Only observations made during the period are considered. The period of interest can be split into shorter sub-periods (to be optimized sequentially) through the IMI Kalman filter feature.
+   * - ``Region of interest``
+     - The region over which the IMI will optimize mean emissions at up to 0.25°×0.3125° (≈25-km) resolution. Specified by rectilinear latitude/longitude bounds, shapefile, or interactively through the Integral Earth user interface. The region of interest can be rectilinear or irregular in shape.
+   * - ``Inversion domain``
+     - The region of interest and a surrounding buffer region. The inversion domain is always rectilinear in shape.
+   * - ``Buffer emission elements``
+     - The 2D emission elements that make the buffer region. Default number is 8.
+   * - ``Emission state vector``
+     - The collection of 2D emission elements (up to 0.25°×0.3125° resolution) to be optimized in the inversion. Includes elements within the region of interest and buffer elements.
+   * - ``Prior emission estimate``
+     - Best estimate of emissions before performing the inversion, based on a bottom-up inventory.
+   * - ``Posterior emission estimate``
+     - Best estimate of emissions after performing the inversion.
+   * - ``Averaging kernel sensitivity``
+     - Estimates how sensitive the posterior solution for a given state vector (emission) element is to observations as opposed to the prior estimate. An emission element with averaging kernel sensitivity 0 is not quantified by the observations at all, and the inversion returns the prior value for that element. An emission element with averaging kernel sensitivity 1 is fully quantified by the observations, and the inversion results for that element are independent of the prior estimate. 
+   * - ``Degrees of freedom for signal (DOFS)``
+     - The sum of the averaging kernel sensitivities for the region of interest. Measures the information content of the observations towards optimizing the state vector; represents the number of independent pieces of information on the state vector that the observations can quantify.

docs/source/getting-started/best-practices.rst

@@ -0,0 +1,50 @@
+IMI Best Practices
+===================
+
+Choosing an inversion time period
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* The IMI can be applied to any period of interest beginning 1 May 2018, when the TROPOMI methane record begins.
+* Common choices for the length of the inversion period are one year, one season (~3-6 months), one month, or one week.
+* We recommend choosing time periods of one week or more to ensure there are enough satellite observations for a successful inversion.
+* The `IMI Preview feature <../getting-started/imi-preview.html>`_ can be used to refine the choice of inversion period.
+
+Defining a region of interest
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* The IMI can be applied to any region of interest, from the global scale down to small focus areas such as cities, oil and gas basins, and agricultural areas.
+* The region of interest can be specified in several ways:
+* Setting latitude/longitude bounds for a rectangular domain.
+* Using a shapefile.
+* Interactively in the Integral Earth web user interface.
+* We recommend users select regions of interest larger than about 10,000 km\ :sup:`2` (100x100 km\ :sup:`2`) to ensure there are enough satellite observations for a successful inversion.
+* Larger regions of interest require more computational resources. This can be mitigated by optimally reducing the effective resolution of the inversion via `smart state vector clustering <../advanced/using-clustering-options.html>`_.
+
+Configuring the inversion domain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Regional inversions focus on a region of interest within a larger rectilinear inversion domain.
+* The inversion domain includes both the region of interest and an external buffer region.
+* The buffer region is broken into a collection of buffer emission elements representing emissions outside the region of interest.
+* We recommend using ≥ 8 buffer elements to pad the region of interest by ≥ 2°. The default number is 8.
+
+Reducing the dimension of the state vector for large regions of interest
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Inversions for large regions of interest at the IMI native 0.25°x0.3125° grid resolution can be computationally expensive.
+* This can be mitigated by reducing the dimension of the state vector using the state vector clustering options.
+* Smart state vector clustering combines 0.25°x0.3125° into coarser grid elements where the prior emission estimates are low and/or where TROPOMI provides few observations
+
+Interpreting the IMI Preview
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Examine the expected information content for the region and period of interest. This includes the map of expected averaging kernel sensitivities and the expected degrees of freedom for signal (DOFS).
+    * The averaging kernel sensitivities should be higher where the prior emission estimates are higher and where more observations are available.
+    * DOFS > 0.5 is a bare minimum to achieve any solid information about emissions.
+    * DOFS < 2 is marginal for most applications.
+* If the expected information content is low, consider:
+    * Increasing the inversion period to incorporate more observations.
+    * Increasing the prior error estimate.
+
+Choosing the TROPOMI data product for the inversion
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* The IMI supports inversions with two versions of the TROPOMI methane record:
+    * The operational TROPOMI retrieval product developed by the SRON Netherlands Institute for Space Research.
+    * The Blended TROPOMI+GOSAT retrieval product developed by `Balasus et al. (2023) <https://amt.copernicus.org/articles/16/3787/2023/>`_ to mitigate retrieval artifacts in the operational product.
+* Choosing a product depends on the application. The operational product is updated every few days. The blended product is updated intermittently and is currently available through 2023.
+* We recommend using the blended product when available (currently until 2024-01-01) to mitigate retrieval artifacts.

docs/source/getting-started/faqs.rst

@@ -0,0 +1,66 @@
+IMI FAQs
+========
+
+This page documents frequently asked questions about the IMI.
+
+What is the IMI?
+~~~~~~~~~~~~~~~~~
+* The IMI is an open-source software tool for quantifying methane emissions at up to 0.25°x0.3125° (≈25-km) and weekly resolution using satellite observations from the `TROPOspheric Monitoring Instrument <https://www.tropomi.eu/>`_ (TROPOMI), a prior estimate of emissions (e.g., a bottom-up emission inventory), and the `GEOS-Chem chemical transport model <https://geoschem.github.io/index.html>`_.
+* It uses an analytical Bayesian inversion method that starts from the prior estimate of emissions and improves it with information from the satellite observations to produce a posterior estimate with full error characterization.
+* It can be applied to any region and period of interest.
+
+How do I access the IMI?
+~~~~~~~~~~~~~~~~~~~~~~~~~
+* There are several ways to access the IMI:
+    * Use the free IMI product on the `Amazon Web Services (AWS) Marketplace <https://aws.amazon.com/marketplace/pp/prodview-hkuxx4h2vpjba>`_.
+    * Download the `IMI source code <https://github.com/geoschem/integrated_methane_inversion>`_ and run it locally.
+    * Use the `Integral Earth web user interface <https://integralearth.github.io/>`_ for the IMI.
+
+How do I cite the IMI?
+~~~~~~~~~~~~~~~~~~~~~~~
+* You can cite the IMI with the corresponding research paper for your application: `IMI 1.0 paper <https://doi.org/10.5194/gmd-15-5787-2022>`_ and/or `IMI 2.0 paper <https://doi.org/10.5194/egusphere-2024-2700>`_.
+
+How much does it cost to use the IMI?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Running the IMI on AWS incurs fees for using AWS compute resources. 
+* The typical cost for a 500x500 km\ :sup:`2` domain (e.g., the Permian Basin) for 1 month is about $20. 
+* Cost scales with duration and domain size. Costs for larger domains can be effectively mitigated using the smart clustering capability available through the IMI.
+
+Where is the IMI documented?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* The IMI is documented at `imi.readthedocs.io <../index.html>`_.
+
+What is the IMI Preview?
+~~~~~~~~~~~~~~~~~~~~~~~~~
+* The `IMI Preview <../getting-started/imi-preview.html>`_ is a feature for evaluating an IMI configuration without actually running an inversion. With the IMI Preview you will:
+* Visualize the TROPOMI observations, bottom-up emission inventories, and point source data to be used in the inversion. 
+* Estimate the information content (degrees of freedom for signal, called DOFS) of the inversion.
+* Estimate the USD cost of running the inversion on AWS.
+* The IMI Preview has no significant costs, and we strongly recommend using it to ensure that the proposed IMI configuration will lead to a successful inversion.
+
+Does the IMI support continuous emission monitoring?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Yes. Users can continuously monitor emissions for a region of interest using the `IMI Kalman filter <../advanced/kalman-filter-mode.html>`_ feature.
+
+Does the IMI support use of custom prior emission inventories?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Yes. Users can override the default IMI prior emission inventories with their own by following `these instructions <../advanced/custom-prior-emissions-hemco.html>`_.
+
+Can I get information on individual point sources from the IMI?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* No. The IMI gives you total emissions in 25x25 km\ :sup:`2` grid cells, including all sources. However, it scrapes point source observations from other databases to improve the prior estimate (optional) and to put the total emission results in context.
+
+Can I get sectoral information from the IMI?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Yes. The IMI uses prior sectoral information to allocate the posterior emission estimates to specific sectors.
+
+Can I detect offshore emissions with the IMI?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Yes. Although the satellite observations are mainly over land, the IMI has the option to use glint observations over water. Offshore emissions can also be quantified from observations of the plume advected over land by onshore flow.
+
+What can I get from the IMI that's different from point source data providers (GHGSat, Carbon Mapper, Kayrros...)?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* The IMI is a completely different product. It provides total gridded continuous emissions, not snapshot emissions from specific point sources as from point source data providers. 
+* The two are complementary. The IMI information is most useful for emission reporting, for understanding contributions from different sectors, for monitoring emission trends, and for quantifying long-term averages.
+
+

docs/source/index.rst

@@ -31,6 +31,9 @@ local compute cluster either manually building the environment or using a docker
    getting-started/imi-config-file.rst
    getting-started/imi-preview.rst
    getting-started/minimizing-cost-tips.rst
+   getting-started/best-practices.rst
+   getting-started/IMI-glossary.rst
+   getting-started/faqs.rst
 
 .. toctree::
    :maxdepth: 1