rayference / joseki

Reference atmospheric thermophysical properties for radiative transfer applications in Earth's atmosphere.

Joseki

Reference atmospheric thermophysical profiles for radiative transfer applications in Earth's atmosphere.

This package gathers together datasets of thermophysical properties of the Earth's atmosphere relevant for radiative transfer applications, and provides utilities to compute common characteristic quantities and perform operations such as interpolation and rescaling on a dataset.

Features

• Available profiles:
  • AFGL Atmospheric Constituent Profiles (0-120 km)
  • MIPAS (2007) reference atmospheres
  • U.S. Standard Atmosphere, 1976
• NetCDF support thanks to the xarray library
• Documented and standard dataset format based on the CF conventions
• Dataset schema validation
• Altitude interpolation/extrapolation and regularization
• Molecular concentration rescaling
• Molecules selection
• Computation of derived quantities
• Convenient units support thanks to the pint library
• Command-line interface
• Python API

Requirements

• Python 3.8+

Installation

You can install Joseki via pip from PyPI:

pip install joseki

or via conda from conda-forge:

conda install -c conda-forge joseki

Documentation

Visit https://rayference.github.io/joseki/latest.

Ikigai

Joseki was born in the context of the development of the Eradiate radiative transfer model, from the need to collect, document and trace, integrate and modify popular thermophysical profiles. As such, its features evolve in close relationship to those of Eradiate.

About

Joseki was created by Yvan Nollet and is maintained by Rayference.

Joseki is a component of the Eradiate radiative transfer model.

Joseki's logo is a simple representation (not to scale!) of the 5 layers of Earth's atmosphere (troposphere, stratosphere, mesosphere, thermosphere and exosphere).

joseki's Issues

Store molecular masses and drop `molmass` dependency

At the moment, the molmass package serves only to compute the molecular masses of molecules included in the atmospheric profiles. A more lightweight solution would be to store a mapping of molecules and molecular masses. This would also ease the deployment of a conda package as molmass is not available on conda.

Add version

Flexible `joseki.create()` method

Add a flexible way -- i.e. from custom data -- to create a thermo-physical profile.

Something like:

import numpy as np

import joseki
from joseki import unit_registry as ureg

joseki.create(
    z=np.array([0.0, 10.0]) * ureg.km,
    t=np.array([288.0, 276.0]) * ureg.kelvin,
    p=np.array([101325, 50651.25]) * ureg.pascal,
    x=np.array([[0.01, 0.005], [0.0004, 0.0004]]) * ureg.dimensionless,
    m=["H20", "CO2"],
)

Concentration rescaling

Add methods to rescale the profiles so that target concentrations -- column (mass/number) densities or number/mass density at the surface -- are reached for selected molecules.

Profile schema validation

Profle schema validation could be implemented using pydantic

Logging system

Terminology

Add a terminology section in documentation to give the definitions of the following terms:

• column number density
• column mass density
• number density at sea level
• mass density at sea level

Rename `molecules` -> `molecule`

The standard_name and long_name for the m coordinate should be molecule, instead of molecules.

Add project relationship to Eradiate/Rayference

Python 3.10

Add support for python-3.10. Add version 3.10 to noxfile.py.

Dataset format

The dataset format page lacks the information about what variables depend on what coordinates.

Add U.S. Standard Atmosphere, 1976

https://github.com/nollety/ussa1976

Update standard name 'molecule' -> 'gas_molecule'

This standard name (gas_molecule) is more specific than the previous one (molecule).

Use a factory

Update Command line interface

Command line interface is outdated compared to the features of joseki.core.make

Refactor `make` to take a single `z` parameter to specify the altitude grid

• remove altitudes: pathlib.Path parameter
• remove altitude_units: str parameter
• add z: pint.Quantity parameter
• refactor CLI to generate z out of altitudes and altitude_units.

Remove plot accessor method

Let users have all the control on plotting.

Profiles summaries

It would be convenient if each registered profile could export a summary of their characteristic with the information:

• publication reference
• dates of development, authors
• basis of the model
• model codes and sources
• model content
• model uncertainties and limitations
• gas molecules list
• altitude range
• covered time range
• covered longitude/latitude range

Rename `molecules` to `m`

That would be more consistent.

Some profiles have volume mixing ratio sum > 1.0

The following AFGL1986 profiles have a volume mixing ratio sum larger than one at some altitudes:

• tropical
• midlatitude_summer
• subarctic_summer

This causes an issue when trying to rescale these profiles.

`from_cams_reanalysis`: rescale pressure profile with surface pressure

The pressure profile in from_cams_reanalysis is created entirely from the model_level_60.csv data file, independently of the actual CAMS reanalysis dataset. This suggestion is to correct this artificial pressure profile by rescaling it by a factor equal to the ratio of the actual surface pressure and the model_level_60.csv surface pressure value.

`nox_poetry.export_requirements` is deprecated

Remove this deprecation warning:

FutureWarning: nox_poetry.export_requirements is deprecated, use @nox_poetry.session instead and invoke session.poetry.export_requirements
  _deprecate("export_requirements", "session.poetry.export_requirements")

Upload to anaconda

Add COSPAR International Reference Atmosphere 1986/1996

Book on Amazon

`scaling_factors` accessor

Provide a scaling_factors accessor to compute the scaling factor to use in order to reach a target amount along the molecule dimension.

The accessor would be useful in coordinate with the rescale accessor:

ds = joseki.make(identifier="afgl_1986-midlatitude_summer")
factors = ds.joseki.scaling_factors(
    {
        "H2O": 40 * ureg.kg / ureg.m**2
    }
)  # returns {"H2O": 1.3403081516598105}
ds.joseki.rescale(factors=factors)

Support for CAMS reanalysis datasets

CAMS reanalysis datasets could be used to define (parts of) atmospheric profiles, or update existing ones.

The following use cases are anticipated:

1. update a standard profile with multi-level temperature and pressure data
2. update a standard profile with total columns data
3. update a standard profile with multi-level molecular concentration data
4. hybrid update of a standard profile (combination of 1, 2 and 3)
5. create a profile entirely from multi-level temperature, pressure and molecular concentration data

`safety` failure

The safety nox session fails due to numpy version < 1.22.1.
Since numpy 1.22 requires python > 3.8, solving this issue means removing support for python 3.7.

Add WCP 112

Add atmosphere profiles from the following report:
World Climate Programme, 1986 "A preliminary Cloudless Standard Atmosphere for Radiation Computation".

Vertical datum

At present, the z (altitude) coordinate is defined as the height above the geoid, so that the origin of the altitude axis, z = 0 km, corresponds to the geoid. (the geoid differs from the mean sea level by less than 2 meters)

Given that the Earth surface is different from this geoid (e.g. mountains), the convention for z = 0 km could be generalized so that altitude could alternatively be reported relative to the Earth surface (the ground surface).

Implementation details

Each dataset would have a new attribute vertical_datum with a value corresponding to the vertical datum.
The z coordinate' attribute could be also updated to indicate, e.g. height above the geoid, height above the ground level and so on.

A new module (e.g. geodesy.py) could include an enumeration such as:

from enum import Enum

class VerticalDatum(Enum, str):
    """
    Zero-level reference.
    """

    GROUND = "ground"  # 'z' is the height above ground level
    EGM_96 = "EGM-96"  # 'z' is the orthometric height, namely height above EGM-96 geoid
    MEAN_SEA_LEVEL = "mean sea level"  # z is the height above sea level (very close to orthometric height)
    WGS_84 = "WGS 84"  # 'z' is the ellipsoidal height, namely height above Earth reference ellipsoid World Geodetic System 84
    UNDEFINED = "undefined"  # fall-back

including a transformation method to convert one representation to another:

def transform(
    ds: xr.Dataset,
    to: VerticalDatum | str,
    **kwargs,
) -> xr.Dataset:
    pass

Notes

• Vertical datum: vertical datums are also known as zero-elevation surface or zero-level reference.
• Height above ground level
• World Geodetic System 84 reference ellipsoid 84
• EGM96 geoid
• The location-dependent, but persistent in time, separation between mean sea level and the geoid is referred to as (mean) ocean surface topography. It varies globally in a range of ± 2 m.

`from_cams_reanalysis`: improve the model level to altitude conversion

https://confluence.ecmwf.int/display/CUSF/How+to+convert+model+levels+to+altitudes
https://confluence.ecmwf.int/display/ECC/compute_geopotential_on_ml.py
https://confluence.ecmwf.int/pages/viewpage.action?pageId=143037738
https://confluence.ecmwf.int/pages/viewpage.action?pageId=143037736
https://confluence.ecmwf.int/pages/viewpage.action?pageId=155325574

Cite article about the reference forward model (RFM)

At the moment, references to the RFM (reference forward model) consist of a single link to website https://eodg.atm.ox.ac.uk/RFM/.

This could be improved by citing the article along the website where the the atmospheric profile data is hosted.