Geoschem-gcpy

Added
- Added example script `gcpy/examples/hemco/make_hemco_sa_spec.py` (creates the HEMCO standalone configuration file `HEMCO_sa_Spec.rc`)
- Added module `benchmark_gcclassic_stats.py` for scraping statistics from GEOS-Chem Classic cloud benchmarks
- Added dry deposition velocity comparison plots in 1-month cloud benchmarks
- Added `gcpy/benchmark/modules/benchmark_species_changes.py` to compute the table of species changes between versions
- Added `gcpy/kpp/` folder containing scripts to plot output from the KPP-Standalone box model
- Added ReadTheDocs documentation for plotting output from the KPP-Standalone box model

Changed
- Changed format of `% diff` column from `12.3e` to `12.3f` in benchmark timing tables
- Updated `gcpy/benchmark/modules/emission_species.yml` file with emission species for GEOS-Chem 14.5.0
- Updated `gcpy/benchmark/modules/benchmark_categories.yml` with the latest categories for GEOS-Chem 14.5.0
- Updated `gcpy/benchmark/modules/lumped_species.yml` with speciations for GEOS-Chem 14.5.0
- Add `DryDep` to list of collections included in benchmark summary table
- Updated `checkout` GitHub action to v4
- Updated `CodeQL` GitHub action to v3
- Updated `publish-python` GitHub action to v5
- In environment files `gcpy_environment.yml` and `gcpy_requirements.txt`:
- Update `python` to 3.12.0
- Update `xesmf` to 0.8.5
- Update `esmf` and `esmpy` to 8.6.1
- In environment files `read_the_docs_environment.yml` and `read_the_docs_requirements.txt`
- Update `jinja` to 3.1.5 (fixes a security issue)
- Update `gcpy/setup.py` with the new Python package version numbers
- Updated code in `gcpy/benchmark/modules/` to replace whitespace in Ref and Dev labels with underscores

Fixed
- Fixed formatting error in `.github/workflows/stale.yml` that caused the Mark Stale Issues action not to run
- Now flag differences greater than +/- 10% in benchmark timing table outputs
- Fixed error in computation of dynamic ratio plot min & max values in `plot/six_plot.py`
- Fixed erroneous species classification in `gcpy/benchmark/modules/benchmark_categories.yml`
- Fixed type errors in `calc_rectilinear_lon_edge` and `calc_rectangular_lat_edge` by casting the length of the output array from `float` to `int`

Removed
- Removed `gcpy/benchmark/modules/species_database.yml` file and corresponding code pointing to this

Added
- Script `gcpy/benchmark/modules/benchmark_utils.py`, with common benchmark utility functions
- Script `gcpy/benchmark/modules/benchmark_drydep.py`, with code to create drydep velocity plots
- YAML tag `plot_drydep` in `gcpy/benchmark/config/*.yml` files
- Badge for `build-gcpy-environment` GitHub Action in `README.md`
- Badges in `docs/source/index.rst`
- GitHub action to push GCPy releases to PyPi
- Script `./release/changeVersionNumbers.sh`, used to update version numbers in various files before release
- Mamba/Conda enviroment file `docs/environment_files/read_the_docs_environment.yml`, for building ReadTheDocs documentation
- Environment files `docs/environment_files/gcpy_requirements.txt` and `docs/environment_files/read_the_docs_requirements.txt`
- New benchmark script `gcpy/benchmark/modules/benchmark_models_vs_sondes.py`
- Added fixed level budget diagnostic to budget operations table
- Function `rename_speciesconc_to_speciesconcvv` in `gcpy/benchmark/modules/benchmark_utils.py`
- Function `copy_file_to_dir` in `gcpy/util.py`. This is a wrapper for `shutil.copyfile`.
- GitHub Action config file `.github/workflows/stale.yml`, which replaces StaleBot
- Added `gcpy/community/format_hemco_data.py` from hannahnesser
- Added `gcpy/examples/hemco/format_hemco_demo.py` from hannahnesser
- Added HCl to `gcpy/benchmark/modules/emission_species.yml` and GTChlorine to `gcpy/benchmark/modules/emission_inventories.yml` for GEOS-Chem 14.4.0
- Example script `gcpy/examples/working_with_files/make_mask_file.py`
- Convenience function `replace_whitespace` in `gcpy/util.py`
- Benchmark script `gcpy/benchmark/modules/benchmark_scrape_gcclassic_timers.py`
- Benchmark script `gcpy/benchmark/modules/benchmark_scrape_gchp_timers.py`
- 1-year benchmark scripts now produce GCC vs GCC and GCHP vs GCHP timing tables
- Functions `gcc_vs_gcc_dirs`, `gchp_vs_gcc_dirs`, `gchp_vs_gchp_dirs`, and `get_log_filepaths` in `gcpy/benchmark/modules/benchmark_utils.py`
- Script `gcpy/benchmark/modules/benchmark_mass_cons_table.py`, with code to create mass conservation tables
- Expanded statistics output in benchmark mass conservation tables
- Function `get_datetimes_from_filenames` in `gcpy/benchmark/modules/benchmark_utils.py`
- Function `replace_whitespace` in `gcpy/util.py`

Changed
- Bump pip from 23.2.1 to 23.3 (dependabot suggested this)
- Bump pypdf from 3.16.1 to 3.17.0 (dependabot suggested this)
- YAML tag `operations_budget` is now `ops_budget_table` in `gcpy/benchmark/config/1yr_tt_benchmark.yml`
- Now require `matplotlib=3.8.0` in `docs/environment_files/environment.yml` (with other pegged versions)
- Now run the `stale` GitHub action at 00:00 UTC on the 1st of each month
- Renamed `docs/environment_files/environment.yml` to `gcpy_environment.yml`
- `environment.yml` links to `docs/environment_files/gcpy_environment.yml`
- `requirements.txt` links to `docs/environment_files/requirements.txt`
- Python packages for RTD documenation builds from `docs/environment_files/environment.yml`
- Script `benchmark_model_vs_obs.py` now uses grid inquiry functions from `grid.py` to return data nearest to a (lat,lon) location
- Moved routine `get_geoschem_level_metadata` to `gcpy/benchmark/modules/benchmark_utils.py`
- Refactored `get_vert_grid.py` (in `gcpy/grid.py`) to accept the `p_sfc` argument; Also never-nested the if-block logic.
- `benchmark_slurm.sh` script now saves output to a log file with the same base name as the YAML config file
- `benchmark_models_vs_obs.py` now reads the observational data paths and metadata from `1yr_fullchem_benchmark.yml`
- Moved benchmark code from `gcpy/` to `gcpy/benchmark/modules/`
- Benchmark functions now call `rename_speciesconc_to_speciesconcvv`
- Create radionuclide, STE flux, and mass conservation tables for Ref and Dev versions in TransportTracers benchmarks
- Use new function `copy_file_to_dir` to copy the benchmark script and configuration file to the benchmark results folders
- Updated GitHub stalebot config file `stale.yml` with new issue/PR labels that should not go stale
- Updated benchmark driver scripts and config files to print GCClassic & GCHP timing information
- Updated documentation for GCPy 1.5.0 release
- Converted Github issue templates to issue forms using YAML definition files

Fixed
- CS inquiry functions in `gcpy/cstools.py` now work properly for `xr.Dataset` and `xr.DataArray` objects
- Prevent an import error by using `seaborn-v0_8-darkgrid` in`gcpy/benchmark/modules/benchmark_models_vs_obs.py`
- `gcpy/file_regrid.py` now creates GCHP files with `DELP_DRY` instead of `DELPDRY`
- Fixed bugs in GCHP vs GCHP sections of 1-yr benchmark run scripts to allow comparison of GCHP runs with different grid resolutions
- Fixed silent bug in transport tracer benchmark GCC vs GCHP mass
tables preventi ng them from being generated
- Import error in `gcpy/examples/diagnostics/compare_diags.py`
- Added missing `n_cores` to `gcpy/examples/diagnostics/compare_diags.yml`
- Added missing `plot_drydep` option to `gcpy/gcpy/benchmark/config/1yr_ch4_benchmark.yml`
- Added `docs/requirements.txt` symbolic link to `docs/environment_files/read_the_docs_requirements.txt` for RTD builds
- `gcpy/file_regrid.py` now tests if `lon_bnds`, `lat_bnds` are in the dataset before trying to drop them
- Ensured that the header line in the aerosol burden table is written to file

Removed
- Example script `gcpy/examples/plotting/mda8_o3_timeseries.py`
- Removed `Pylint` GitHub action
- Environment file `docs/environment_files/environment.yml`
- Environment file `docs/environment_files/requirements.txt`
- Removed `awscli` from the GCPy environment; version 2 is no longer available on conda-forge or PyPi
- GitHub config files `.github/stale.yml` and `.github/no-response.yml`
- Routine `make_benchmark_mass_conservation_table` in `benchmark_funcs.py`; this is now obsolete

Added
- Example script `create_test_plot.py`, which can be used to check that GCPy has been installed properly
- GitHub action `build-gcpy-environment` which tests installation of the mamba environment specified in in `docs/environment_files/environment.yml`
- YAML file`docs/environment_files/testing.yml` for building an environment without pegged package versions (for testing)
- GitHub action `build-test-environment` to test the environment specified in `testing.yml`

Changed
- `build-gcpy-environment` GitHub action now runs with several Python versions

Fixed
- Prevent overwriting of the `results` variable when parallel plotting is deactivated (`n_cores: 1`)

Fixed
- Now use the proper default value for the `--weightsdir` argument to `gcpy/file_regrid.py`

Added
- Added C2H2 and C2H4 to `emission_species.yml`
- Updated `species_database.yml` for consistency with GEOS-Chem 14.2.0
- Added `.github/ISSUE_TEMPLATE/config.yml` file w/ Github issue options
- Added `CONTRIBUTING.md` and `SUPPORT.md`, replacing `docs/source/Contributing.rst` and `docs/source/Report_Request.rst`
- Added option to pass the benchmark type to plotting routines
- Updated `AUTHORS.txt` as of Apr 2023 (concurrent w/ GEOS-Chem 14.2.0)
- Added ReadTheDocs badge in `README.md`
- Added `.readthedocs.yaml` to configure ReadTheDocs builds
- Added cloud benchmarking YAML configuration files to `benchmark/cloud` folder
- Added `README.md` files in `gcpy/benchmark` directory structure
- Added `benchmark/modules/benchmark_models_vs_obs.py` script
- Added `benchmark/modules/GC_72_vertical_levels.csv` file
- Added `multi_index_lat` keyword to `reshape_MAPL_CS` function in `gcpy/util.py`
- Added FURA to `emission_species.yml` and `benchmark_categories.yml`
- Added new routine `format_number_for_table` in `gcpy/util.py`
- Added module `gcpy/cstools.py` with utility functions for cubed-sphere grids
- Added new routine `verify_variable_type` function in `gcpy/util.py`
- Added new routine `format_number_for_table` in `util.py`
- Added BrSALA and BrSALC to `emission_species.yml`
- Added `options:n_cores` to all benchmark YAML config files
- Added `__init__.py` files in subfolders of `gcpy/gcpy`
- `gcpy/benchmark/modules/*.py` scripts are now chmod 644
- Added `ENCODING = "UTF-8"` to `gcpy/constants.py`
- Added statement `from dask.array import Array as DaskArray` in `gcpy plot.py`
- Added SLURM run script `gcpy/benchmark/benchmark_slurm.sh`
- Added `gcpy/plot/gcpy_plot_style` style sheet for title and label default settings
- Added `gcpy/gcpy_plot_style` style sheet for title and label default settings
- Added new cubed-sphere grid inquiry functions to `gcpy/cstools.py`
- Added functions `get_ilev_coord` and `get_lev_coord` to `gcpy/grid.py`
- Add `tk` package to `docs/environment_files/environment.yml`

Changed
- Simplified the Github issues templates into two options: `new-feature-or-discussion.md` and `question-issue.md`
- The GitHub PR template is now named `./github/PULL_REQUEST_TEMPLATE.md`
- Updated badge links in `README.md`
- Construct ops budget table filename without using the `label` argument
- Updated species_database.yml for consistency with GEOS-Chem 14.2.0
- Renamed TransportTracers species in `benchmark_categories.yml`, `run_1yr_tt_benchmark.py`, and in documentation
- YAML files in `benchmark/` have been moved to `benchmark/config`
- Models vs. O3 obs plots are now arranged by site latitude from north to south
- Routine `print_totals` now prints small and/or large numbers in scientific notation
- Truncate names in benchmark & emissions tables to improve readability
- Add TransportTracers species names to `gcpy/emissions_*.yml` files
- Now pass `n_job=config["options"]["n_cores"]` to benchmark plotting routines
- Script `benchmark.py` to `benchmark_funcs.py` to remove a name collision
- Folder `gcpy/benchmark` is now `gcpy/gcpy/benchmark`
- Folder `benchmark/modules` is now `gcpy/gcpy/benchmark/modules`
- Folder `gcpy/examples` is now `gcpy/gcpy/examples`
- Pass `sys.argv` to the `main()` routine of `run_benchmark.py`,` compare_diags.py`
- Updated `docs/environment_files/environment.yml` for MambaForge (also added `gridspec`)
- Now use `pypdf` instead of `PyPDF2` in `plot.py` and `util.py`
- Added coding suggestions made by `pylint` where possible
- Abstracted and never-nested code from `six_plot` into functions (in `plot.py`)
- Added `main()` routine to `gcpy/file_regrid.py`; Also added updates suggested by Pylint
- Fixed broken regridding code in `gcpy/file_regrid.py`; also refactored for clarity
- Rewrote `Regridding.rst` page; Confirmed that regridding examples work properly
- Now allow `plot_val` to be of type `dask.array.Array` in `plot.py` routines `six_plot` and `single_panel`
- Now add `if` statements to turn of `Parallel()` commands when `n_jobs==1`.
- Do not hardwire fontsize in `gcpy/plot.py`; get defaults from `gcpy_plot_style`
- `gcpy/plot.py` has been split up into smaller modules in the `gcpy/plot` folder
- Updated and cleaned up code in `gcpy/regrid.py`
- Example scripts`plot_single_level` and `plot_comparisons` can now accept command-line arguments
- Example scripts `plot_single_level.py`, `plot_comparisons.py`, `compare_diags.py` now handle GCHP restart files properly
- Now specify the X11 backend with by setting the `MPLBACKEND` environment variable

Fixed
- Generalized test for GCHP or GCClassic restart file in `regrid_restart_file.py`
- Fixed bug in transport tracer benchmark mass conservation table file write
- Routine `create_display_name` now splits on only the first `_` in species & diag names
- Prevent plot panels from overlapping in six-panel plots
- Prevent colorbar tick labels from overlapping in dynamic-range ratio plots
- Updated `seaborn` plot style names to conform to the latest matplotlib
- Set `lev:positive` and/or `ilev:positive` properly in `regrid_restart_file.py` and `file_regrid.py`
- Prevent overwriting of `lev` coord in `file_regrid.py` at netCDF write time
- Fixed bug in option to allow different units when making comparison plots

Removed
- Removed `gchp_is_pre_13_1` arguments & code from benchmarking routines
- Removed `is_pre_13_1` tags from `*_benchmark.yml` config files
- Removed `benchmark_emission_totals.ipynb`, this is obsolete
- Replaced `gcpy/benchmark/README` with `README.md`
- Removed `gcpy_test_dir` option from `examples/diagnostics/compare_diags.*`
- Removed `docs/environment_files/gchp_regridding.yml` environment file
- Removed `gcpy/gcpy/benchmark/plot_driver.sh`
- Made benchmark configuration files consistent

Added
- Updated installation documentation, we now recommend users to create
a conda environment using the `environment.yml` file
- Benchmark summary table output (intended for 1hr & 1mo benchmarks)
- Species/emissions/inventories that differ between Dev & Ref versions are now printed at the top of the benchmark emissions, inventory, and global mass tables. if there are too many species with diffs, an alternate message is printed.
- New functions in `benchmark.py` and `util.py` to facilitate printing of the species/emissions/inventories that differ between Dev & Ref versions.
- Added new RTD documentation for installing Conda 4.12.0 with Miniconda
- Added GCHP regridding environnment file `docs/environment_files/gchp_regridding.yml`
- Added new benchmark type CH4Benchmark

Changed
- Applied cleanup susggestions from pylint to `benchmark.py`, `util.py`, `plot.py`, `oh_metrics.py`, `ste_flux.py`
- Replaced format with f-strings in `benchmark.py`, `util.py`, `plot.py`, `oh_metrics.py`, `ste_flux.py`
- Abstract some common in `benchmark.py` into functions
- Replaced direct calls to `yaml.load` with `util.read_config.file`
- Restore tag information to benchmark `refstr` and `devstr` labels
- Add a newline to diff-of-diffs refstr and devstr if the string is too long.
- Updated GCHP regridding documentation
- Restored `ipython` and `jupyter ` to environment file `environment.yml`