AC_tools: Atmospheric Chemistry (AC) tools ====================================== .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.4789901.svg :target: https://doi.org/10.5281/zenodo.4789901

Atmospheric Chemistry Tools (AC_Tools) contains functions and scripts used for working with atmospheric model output and observational data. Many functions are included for working with global and regional chemical transport model (CTM) ouput from the GEOS-Chem model.

This package started as a just collection of scripts that were found to be useful for work in atmospheric chemistry and now simply aims to contain functionality outside the remit of the more specialised community packages (e.g PyGChem, xbpch, and gcpy) and use the existing Python stack (e.g. dask, xarray, pandas). Please raise any questions/comments or bugs as issues here on GitHub and pull requests are welcome!

AC_Tools is currently only installable from source. To do this, you can either install directly via pip (recommended and this includes any dependencies):

$ pip install git+https://github.com/tsherwen/AC_tools.git

or (not recommended), clone the source directory and manually install:

$ git clone https://github.com/tsherwen/AC_tools.git
$ cd AC_tools
$ python setup.py install

If you specifically wish to use the legacy "bpch to NetCDF" (bpch2netCDF) capability, you will need to run AC_tools in a Python2 environment due to use of an iris backend via PyGChem. In this specific case, please install using the later method and ensure that you have iris (version 1.13.0) installed. You will also need to install PyGChem (version 0.3.0) by the same route.

Functions within AC_Tools can be used for various tasks for handling model output and observations.

An example would be importing NetCDF files or converting ctm.bpch files from a directory of GEOS-Chem output (with tracerinfo.dat and diaginfo.dat files). Or using GEOS-Chem NetCDF output to make a quick plot of surface ozone.

If using within a python3 environment and GEOS-Chem

import AC_tools as AC
folder = '<folder containing GEOS-Chem output>'
# Get the GEOS-Chem NetCDF output as a xarray dataset object
# NOTE: this is just a wrapper of get_GEOSChem_files_as_ds, which can retrieve GEOS-Chem NetCDFs as a dataset
ds = AC.GetSpeciesConcDataset(wd=folder)
# Average dataset over time
ds = ds.mean(dim='time')   
# Select the surface level
ds = ds.sel( lev=ds.lev[0] )      
# Select ozone and do plot basic plot
spec = 'O3' 
#ds['SpeciesConc_'+spec].plot() # very simple plot
AC.quick_map_plot( ds, var2plot='SpeciesConc_'+spec) # basic lat-lon plot
plt.show()
# Get global average surface CO 
spec = 'CO'
ratio = (ds['SpeciesConc_'+spec] * ds['AREA']).sum() / ds['AREA'].sum()
ratio = float(ratio.values) 
# Make a formatted string and then print using this to screen
prt_str = "The global average surface mixing ratio of {spec} (ppbv) is: {ratio}" 
print(prt_str.format(spec=spec, ratio=ratio*1E9))

If using within a python2 environment, the below example is a way of accessing GEOS-Chem data. The data is converted from bpch to NetCDF by default via an iris backend through PyGChem (using bpch2netCDF.py).

import AC_tools as AC
folder = '<folder containing GEOS-Chem output>'
# Get the atmospheric ozone burden in Gg O3 as a np.array
array = AC.get_O3_burden_bpch(folder)
print( "The ozone burden is: {burden}".format(burden=array.sum()))
# Get surface area for resolution 
s_area = get_surface_area(res)[..., 0]  # m2 land map
# Get global average surface CO 
spec = 'CO'
array = AC.get_GC_output(wd=folder, vars=['IJ_AVG_S__{}'.format(spec)])
ratio = AC.get_2D_arr_weighted_by_X(array, res='4x5', s_area=s_area) 
# Make a formatted string and then print using this to screen
prt_str = "The global average surface mixing ratio of {spec} (ppbv) is: {ratio}"
print( prt_str.format(spec=spec, ratio=ratio*1E9))

Example analysis code for using AC_tools is available in the scripts folder.

For more information, please visit the AC_tools_wiki.

Copyright (c) 2015 Tomas Sherwen

This work is licensed under a permissive MIT License.

Tomas Sherwen - tomas.sherwen@york.ac.uk