README

README file for bayesian-osse-R source code
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, etc) 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).