acgc API documentation

# acgc

Data analysis programs from the ACGC research group

# Installation

For conda users:

`conda install -c conda-forge acgc`

For pip users:

`pip install acgc`

### For developers

If you plan to modify or improve the acgc package, an editable installation may be better: `pip install -e git+https://github.com/cdholmes/acgc-python` Your local files can then be managed with git, including keeping up-to-date with the github source repository (e.g. `git pull`).

# Get started

Submodules within `acgc` contain all the capabilities of the package. Submodules are imported via `import acgc.<submodule>` or `from acgc import <submodule>`.

## Better looking figures (example)

The default appearance of figures from Matplotlib doesn't meet the standards of most scientific journals (high-resolution, Helvetica-like font). With the `acgc.figstyle` module, figures meet these criteria. Simply use `from acgc import figstyle` before creating your figures.

## Bivariate statistics (example)

The `BivariateStatistics` class makes it easy to compute and display a large number of bivariate statistics, including line fitting and weighted statistics. Results can be easily formatted into tables or inset in figures. Use `from acgc.stats import BivariateStatistics` See `acgc.stats.bivariate.BivariateStatistics` for documentation.

## Standard major axis (SMA) line fitting (example)

SMA line fitting (also called reduced major axis or RMA) quantifies the linear relationship between variables in which neither one depends on the other. It is available via `from acgc.stats import sma`.

# Demos

The demo folder contains examples of how to accomplish common data analysis and visualization tasks. The examples include uses of the `acgc` library as well as other libraries for geospatial data analysis.

# Quick summary of submodules

## Key submodules

- `acgc.figstyle`
  Style settings for matplotlib, for publication-ready figures. demo

- `acgc.stats`
  Collection of statistical methods. demo

## Other submodules

- `acgc.erroranalysis`
  Propagation of error through complex numerical models

- `acgc.geoschem` or `acgc.gc`
  Tools for GEOS-Chem grids (e.g. indexing, remapping, interpolating)

- `acgc.hysplit`
  Read HYSPLIT output and write HYSPLIT CONTROL files

- `acgc.icartt`
  Read and write ICARTT format files

- `acgc.igra`
  Read IGRA radiosonde data files

- `acgc.mapping`
  Distance calculation, scale bar for display on maps

- `acgc.met`
  Miscelaneous functions for PBL properties

- `acgc.modetools`
  Visualization of eigenmode systems

- `acgc.netcdf`
  High-level functions for reading and writing netCDF files. Legacy code. `acgc.netcdf.write_geo_nc` is still useful for concisely creating netCDF files, but xarray is better for reading netCDF.

- `acgc.solar`
  Solar zenith angle, azimuth, declination, equation of time

- `acgc.time`
  Functions for manimulating times and dates. Legacy code.

View Source

      1'''Data analysis programs from the ACGC research group
      2
      3# Installation
      4
      5For conda users:
      6
      7 `conda install -c conda-forge acgc`
      8
      9For pip users:
     10
     11 `pip install acgc`
     12
     13### For developers
     14If you plan to modify or improve the acgc package, an editable installation may be better:
     15`pip install -e git+https://github.com/cdholmes/acgc-python`
     16Your local files can then be managed with git, including keeping up-to-date with the
     17github source repository (e.g. `git pull`).
     18
     19<!-- ----------------------- SECTION BREAK ----------------------- -->
     20
     21# Get started
     22
     23Submodules within `acgc` contain all the capabilities of the package.
     24Submodules are imported via `import acgc.<submodule>` or `from acgc import <submodule>`.
     25
     26## Better looking figures ([example](https://github.com/cdholmes/acgc-python/blob/main/demo/demo_figstyle.ipynb))
     27
     28
     29The default appearance of figures from Matplotlib doesn't meet the standards of most
     30scientific journals (high-resolution, Helvetica-like font). With the `acgc.figstyle` module,
     31figures meet these criteria. Simply use `from acgc import figstyle` before creating your figures.
     32
     33## Bivariate statistics ([example](https://github.com/cdholmes/acgc-python/blob/main/demo/demo_stats.ipynb))
     34
     35The `BivariateStatistics` class makes it easy to compute and display a large number of
     36bivariate statistics, including line fitting and weighted statistics.
     37Results can be easily formatted into tables or inset in figures. Use `from acgc.stats import BivariateStatistics`
     38See `acgc.stats.bivariate.BivariateStatistics` for documentation.
     39
     40## Standard major axis (SMA) line fitting ([example](https://github.com/cdholmes/acgc-python/blob/main/demo/demo_sma.ipynb))
     41
     42SMA line fitting (also called reduced major axis or RMA) quantifies the linear relationship
     43between variables in which neither one depends on the other.
     44It is available via `from acgc.stats import sma`.
     45
     46<!-- ----------------------- SECTION BREAK ----------------------- -->
     47
     48# Demos
     49The [demo](https://github.com/cdholmes/acgc-python/blob/main/demo)
     50folder contains examples of how to accomplish common data analysis and visualization tasks.
     51The examples include uses of the `acgc` library as well as other libraries for
     52geospatial data analysis.
     53
     54<!-- ----------------------- SECTION BREAK ----------------------- -->
     55
     56# Quick summary of submodules
     57
     58## Key submodules
     59
     60- `acgc.figstyle`
     61Style settings for matplotlib, for publication-ready figures.
     62[demo](https://github.com/cdholmes/acgc-python/blob/main/demo/demo_figstyle.ipynb)
     63
     64- `acgc.stats`
     65Collection of statistical methods.
     66[demo](https://github.com/cdholmes/acgc-python/blob/main/demo/demo_stats.ipynb)
     67
     68## Other submodules
     69
     70- `acgc.erroranalysis`
     71Propagation of error through complex numerical models
     72
     73- `acgc.geoschem` or `acgc.gc`
     74Tools for GEOS-Chem grids (e.g. indexing, remapping, interpolating)
     75
     76- `acgc.hysplit`
     77Read HYSPLIT output and write HYSPLIT CONTROL files
     78
     79- `acgc.icartt`
     80Read and write ICARTT format files
     81
     82- `acgc.igra`
     83Read IGRA radiosonde data files
     84
     85- `acgc.mapping`
     86Distance calculation, scale bar for display on maps
     87
     88- `acgc.met`
     89Miscelaneous functions for PBL properties
     90
     91- `acgc.modetools`
     92Visualization of eigenmode systems
     93
     94- `acgc.netcdf`
     95High-level functions for reading and writing netCDF files. Legacy code.
     96`acgc.netcdf.write_geo_nc` is still useful for concisely creating netCDF files,
     97but xarray is better for reading netCDF.
     98
     99- `acgc.solar`
    100Solar zenith angle, azimuth, declination, equation of time
    101
    102- `acgc.time`
    103Functions for manimulating times and dates. Legacy code.
    104'''
    105
    106def _package_version(package_name):
    107    '''Find version string for package name'''
    108    from importlib.metadata import version, PackageNotFoundError
    109    try:
    110        result = version(package_name)
    111    except PackageNotFoundError:
    112        result = "unknown version"
    113    return result
    114
    115__version__ = _package_version('acgc')
    116
    117__all__ = [
    118    'erroranalysis',
    119    'figstyle',
    120    'gc',
    121    'geoschem',
    122    'hysplit',
    123    'icartt',
    124    'igra',
    125    'mapping',
    126    'met',
    127    'modetools',
    128    'netcdf',
    129    'stats',
    130    'solar',
    131    'time'
    132]