Using custom regions with the IMI
=================================

.. include:: <isonum.txt>

The IMI supports regions within the following domains:

* Africa: 37\ |deg|\ S-40\ |deg|\ N, 20\ |deg|\ W-53\ |deg|\ E
* Asia: 11\ |deg|\ S-55\ |deg|\ N, 60\ |deg|\ E-150\ |deg|\ E
* Europe: 33\ |deg|\ N-61\ |deg|\ N, 30\ |deg|\ W-70\ |deg|\ E
* Middle East: 12\ |deg|\ N-44\ |deg|\ N, 20\ |deg|\ W-70\ |deg|\ E
* North America: 10\ |deg|\ N-70\ |deg|\ N, 140\ |deg|\ W-40\ |deg|\ W
* South America: 59\ |deg|\ S-16\ |deg|\ N, 88\ |deg|\ W-31\ |deg|\ W
* Oceania: 50\ |deg|\ S-5\ |deg|\ N, 110\ |deg|\ E-180\ |deg|\ E (0.25\ |deg| x 0.3125\ |deg| only)
* Russia: 41\ |deg|\ N-83\ |deg|\ N, 19\ |deg|\ E-180\ |deg|\ E (0.25\ |deg| x 0.3125\ |deg| only)
  
These are the regional windows used in GEOS-Chem for which pre-cut meteorological files are available at 0.125\ |deg| x 0.15625\ |deg| and 0.25\ |deg| x 0.3125\ |deg| resolution. You may apply the
IMI to other regions, but this requires either using global meteorological fields which can be 
computationally expensive (not recommended) or cropping global meteorological fields via
a pre-processing step.

To facilite cropping global meteorological fields at at 0.25\ |deg| x 0.3125\ |deg| resolution, a sample script (`crop_met.sh <https://github.com/geoschem/integrated_methane_inversion/tree/main/src/utilities/crop_met.sh>`_) has been included with
the IMI. This script utilizes the `Climate Data Operators (CDO) <https://code.mpimet.mpg.de/projects/cdo>`_.
It also includes an option to first download global meteorological fields
at 0.25\ |deg| x 0.3125\ |deg| resolution. The global files are large (approx. 300G per month),
so when using that option it is recommend that you process short periods at a time and delete the
global files before processing additional periods.

In a text editor, modify the user settings section in ``crop_met.sh``. The region
defined in ``crop_met.sh`` should be the same or larger than the domain defined for your
IMI in `config.yml <../getting-started/config-file.html#region-of-interest>`.

.. list-table::
   :widths: 30, 70
   :class: tight-table

   * - ``RegionID``
     - Two-letter string to identify region (e.g. ``SA`` for South America). This should match the value of ``RegionID`` in ``config.yml``.
   * - ``LonMin``
     - Minimum longitude edge of the region of interest. 
   * - ``LonMax``
     - Maximum longitude edge of the region of interest.
   * - ``LatMin``
     - Minimum latitude edge of the region of interest.
   * - ``LatMax``
     - Maximum latitude edge of the region of interest.
   * - ``DownloadGlobalMet``
     - Boolean for downloading global 0.25\ |deg| x 0.3125\ |deg| meteorology fields for cropping. Default is ``true``. Set to ``false`` if you already have these files on your system.
   * - ``RemoveGlobalMet``
     - Boolean for deleting global meteorology files after cropping. Default is ``false``. Set to ``true`` once you are sure the cropped meteorology files are working properly in the IMI and you do not plan to generate cropped files for additional regions.
   * - ``InDir``
     - Directory containing the global high-resolution meteorology fields.
   * - ``OutDir``
     - Directory where the cropped meteorology files will be placed. We recommend specifying this as ``[YOUR_DATA_PATH]/GEOS_0.25x0.3125_${RegionID}/GEOS_FP``. Where you replace ``[YOUR_DATA_PATH]`` with the same path specified for ``DataPath`` in the IMI's config.yml.
     
The cropped meteorology files can be generated by then executing ``./crop_met.sh`` at the
command line or submitting the script to your cluster's scheduler if available. Headers for the
SLURM scheduler are included at the top of the script, but you can modify or remove those as needed.

To utilize the cropped meteorology files in the IMI, you will need to create a new IMI directory. Modify ``config.yml``
so that ``RegionID`` matches the value set in ``crop_met.sh``. This will automatically
add the region ID string in the appropriate locations in the ``HEMCO_Config.rc`` files utilized
by GEOS-Chem. 

If you have regional emissions that you would like to use, please see :doc:`modifying prior emission estimates <../advanced/custom-prior-emissions-hemco>`.

Finally, you can run the :doc:`IMI preview <../user-guide/imi-preview>` to quickly check that the IMI is working as expected for your custom region. 

Generating 0.125\ |deg| x 0.15625\ |deg| for other regions is not supported at this time. This is an involved process requiring download of C720 mass flux fields from NASA GMAO, converting those to derived winds, and regridding from the cubed-sphere grid to the lat-lon grid. To request other regions, please contact the `IMI Development Team <mailto:integrated-methane-inversion@g.harvard.edu>`_.