Ginput command line interface

If you installed ginput using:

the make install command,
the install.sh script, or
you ran the install-runscript.sh script with the proper Conda environment active,

then there will be a run_ginput.py script in the root directory of the ginput repo. This is the main entry point to run ginput from the command line. To see all the possible options, call it as ./run_ginput.py --help from the root directory of the ginput repo.

Starting from v1.6, installing with pip or the various conda-type installers will also create a ginput_cli script in your environment’s bin directory. This means that as long as you either (a) have that environment active or (b) linked this ginput_cli script to somewhere on your regular PATH, you can call ginput_cli from anywhere to run ginput.

Note

ginput_cli and ./run_ginput.py are completely interchangeable. The rest of the documentation uses the latter in examples since, historically, most users have used that entry point. However, you can replace ./run_ginput.py with ginput_cli in any example in the rest of this documentation, and it will work the same!

This prints out all the possible subcommands:

$ ./run_ginput.py --help

usage: run_ginput.py [-h] {oco,acos,geocarb,update_hourly,mod,tccon-mod,rlmod,tccon-rlmod,vmr,rlvmr,getg5,get-rl-g5,map,sample-model} ...

Call various pieces of ginput

positional arguments:
  {oco,acos,geocarb,update_hourly,mod,tccon-mod,rlmod,tccon-rlmod,vmr,rlvmr,getg5,get-rl-g5,map,sample-model}
                        The following subcommands execute different parts of ginput
    oco                 Generate .h5 file for input into the OCO algorithm
    acos                Generate .h5 file for input into the GOSAT algorithm
    geocarb             Generate .h5 file for input into the GeoCarb algorithm
    update_hourly       Update monthly input CO2 files with new NOAA hourly data
    mod                 Generate .mod (model) files for GGG
    tccon-mod           Generate .mod (model) files appropriate for use with TCCON GGG2020 retrievals.
    rlmod               Generate .mod (model) files for spectra enumerated in a runlog
    tccon-rlmod         Generate .mod (model) files appropriate for use with TCCON GGG2020 retrievals for spectra enumerated in a runlog.
    vmr                 Generate full .vmr files for GGG
    rlvmr               Generate .vmr files from a runlog
    getg5               Download GEOS5 FP or FP-IT data
    get-rl-g5           Download GEOS5 FP or FP-IT data for spectra in a runlog
    map                 Generate .map (a priori) files.

In the above example, run_ginput.py is called as ./run_ginput.py and not python run_ginput.py. This is because when run_ginput.py is created it is given a shebang that points to the Python executable in the correct Conda environment. That’s why you can run it as ./run_ginput.py without activating the Conda environment that ginput was installed it first, whereas if you tried to call it as python run_ginput.py you would have to activate the right environment.

Note

The command line help is more likely to be up-to-date than this page. If you notice a discrepancy between the command line help and this page, please open an issue.

Each subcommand represents one action that ginput can perform. You can get command line help for any subcommand, by calling the subcommand with the --help argument, e.g.:

$ ./run_ginput getg5 --help

usage: run_ginput.py getg5 [-h] [--mode {FP,FPIT,GEOSIT}] [--path PATH] [-t {met,chm}] [-l {surf,p,eta}] [-g {L,C}] date_range

Download GEOSFP or GEOSFP-IT reanalysis met data

positional arguments:
  date_range            The range of dates to get, in YYYYMMDD-YYYYMMDD format. The second date may be omitted, in which case the end date will be one day after the first date. The end date is not included in the
                        range.

options:
  -h, --help            show this help message and exit
  --mode {FP,FPIT,GEOSIT}
                        Which GEOS product to get. The default is FP. Note that to retrieve FP-IT data requires a subscription with NASA (https://gmao.gsfc.nasa.gov/GMAO_products/)
  --path PATH           Where to download the GEOS data to, "." by default. Data will be placed in Np, Nv, and Nx subdirectories automatically created in this directory.
  -t {met,chm}, --filetypes {met,chm}
                        Which file types to download. Works in conjunction with --levels to determine which files to download.
  -l {surf,p,eta}, --levels {surf,p,eta}
                        Which level type to download. Note that only "eta" levels are available for the "chm" file type.
  -g {L,C}, --gridtypes {L,C}
                        used to specify the grid type when downloading GEOS-IT files, L for lat-lon and C for cubed-sphere

If both --filetypes and --levels are omitted, then the legacy behavior is to download met data for the surface and on fixed pressure levels. However, if one is given, then both must be given.

These subcommands can be divided into several groups.

Downloading met data

The getg5 and get-rl-g5 subcommands help to download the GEOS-5 meteorology data the ginput ingests to produce met and a priori trace gas profile files. getg5 allows you to download files for specific dates, while get-rl-g5 allows users running GGG to download the met files required for a GGG runlog (login required).

For more information, see Downloading met files.

Generating model files

In GGG, the meteorology data must be converted to .mod files, which store the met variable profiles in a simple text format that GGG can read. There are four subcommands for generating these file:

tccon-mod - generate these files for date ranges using standard settings to generate TCCON-GGG2020-style priors.
mod - generate these files for date ranges with more flexibility in options.
tccon-rlmod - similar to tccon-mod, but generates the model files needed by a GGG runlog instead of for a given set of dates.
rlmod - similar to mod, but generates the model files needed by a GGG runlog instead of for a given set of dates.

For more information, see Making model files.

Generating VMR files

In GGG, a priori trace gas profiles must be written to .vmr files, which like the .mod files, store these profiles in a simple text format for GGG to read. This step requires that the .mod files for the times you are generating files for exist. There are two subcommands related to generating .vmr files:

vmr - generate these files for a specific date range
rlvmr - generate these files for the times needed by a GGG runlog instead of a given set of dates.

For more information, see Making VMR files.

Generating .map files

In contrast to the .mod and .vmr files, .map files are not inputs to GGG but were traditionally output by the post processing. These contain the key trace gas a priori profiles used by GGG. Because some groups rely on these files, ginput includes the capability to generate them without needing to run the gsetup and write_aux programs within GGG. There is only one subcommand related to writing these files, map.

See Making .map and .map.nc files for more information.

Updating input NOAA data

ginput relies on timeseries of CO2, N2O, and CH4 from NOAA observatories in Mauna Loa, Hawaii, USA and American Samoa to capture the atmospheric growth of these gases. The repo includes flask files for these gases from 2018 and has the capability to extrapolate forward in time; however, extrapolation will have larger errors than using more recent flask or in situ data. This tool allows users to update files using more rapidly delivered data from NOAA.

See Updating NOAA input data for more information.

Warning

The version of the CO2 flask data included in ginput v1.1.7 is still on the X2007 scale. If you need to switch to the X2019 scale, see this section in the Updating NOAA input data page.