AC_tools

Module for working with global/regional Chemical Transport Model (CTM) output and observations

https://github.com/tsherwen/AC_tools

Keywords

Keywords from Contributors

Repository

Module for working with global/regional Chemical Transport Model (CTM) output and observations

README.rst

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! `_

Installation
------------

**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. 


Quick Start
-----------

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 

.. code:: python

    import AC_tools as AC
    folder = ''
    # 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).

.. code:: python

    import AC_tools as AC
    folder = ''
    # 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))
    
    
Usage
------------

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

For more information, please visit the AC_tools_wiki_.


License
-------

Copyright (c) 2015 `Tomas Sherwen`_

This work is licensed under a permissive MIT License.

Contact
-------

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

.. _`Tomas Sherwen`: http://github.com/tsherwen
.. _conda: http://conda.pydata.org/docs/
.. _dask: http://dask.pydata.org/
.. _licensed: LICENSE
.. _GEOS-Chem: http://www.geos-chem.org
.. _xarray: http://xarray.pydata.org/
.. _pandas: https://pandas.pydata.org/
.. _gcpy: https://github.com/geoschem/gcpy
.. _PyGChem: https://github.com/benbovy/PyGChem
.. _xbpch: https://github.com/darothen/xbpch
.. _iris: https://scitools.org.uk/iris/docs/latest/
.. _bpch2netCDF: https://github.com/tsherwen/AC_tools/blob/master/Scripts/bpch2netCDF.py
.. _AC_tools_wiki: https://github.com/tsherwen/AC_tools/wiki

Owner

GitHub Events

Committers

Last synced: 11 months ago

Issues and Pull Requests

Last synced: 10 months ago

Packages