README file for bayesian-osse-R source code (sample version with inputs)
Author: Lewis Kunik (lewiskunik@gmail.com)
University of Utah LAIR group

-------------------------
Overview of inverse model code
-------------------------

This Bayesian inverse model code is based loosely on NOAA CarbonTracker-Lagrange
software (see https://www.esrl.noaa.gov/gmd/ccgg/carbontracker-lagrange/), but
written in the R programming language. This particular set-up performs an Observing
System Simulation Experiment (OSSE), meaning that a set of "true" emissions are
defined so as to generate synthetic enhancements which serve as the model data,
in hopes of recovering the "true" emissions in the posterior/optimized result.
This framework is equipped with random-normal (Gaussian) perturbations in the
synthetic data in order to simulate the presence of model-data mismatch errors
in the observations.


Code can be downloaded and run as-is, provided that the proper input files are supplied.
See the config.r file in inversion/ directory for sample naming conventions of input files.

Required input files should be placed in the include/ directory:
  prior_emiss.nc
  true_emiss.nc
  prior_uncert.nc
  lonlat_domain.rds

The following packages must be installed to successfully run the model code:
  "ncdf4"
  "lubridate"
  "geosphere"
  "data.table"

In addition, netCDF library library version 4.1 or later is required, as well as
R version 3.1.0 or later

After inputs are supplied, the program may be run from the inversion/ directory.
If running in the R programming environment (R or Rstudio),
run by typing: source("run_all.r")
If running directly from the terminal, run by typing: Rscript run_all.r

NOTE: input NetCDF files (prior_emiss.nc, prior_uncert.nc, true_emiss.nc) should exist
in (lon x lat x time) format, with lon/lat values indicating center-of-grid-cell,
and time values expressed as beginning of time-step in either POSIX time or seconds
since R epoch (1970-01-01 00:00:00 UTC).


In addition, footprint files must be supplied in the footprints/ directory.
Files should be in NetCDF format with dimensions (lon x lat x time). Source code
is designed to work with files matching output format from STILT-R
(https://uataq.github.io/stilt/).  This inversion code works with files that
abide by the naming convention where the first 10 characters of the filename indicate
the start time of the footprint in format: YYYYmmddHH (i.e. year, month, day, hour). There
is no required naming convention after 10 characters (the rest of the filename can be
whatever you want).

Note that this source code uses the bayesian-osse-R Github repository as "upstream"
source code. Original source code is primarily maintained by that repository,
then merged into this one.