Options for ionospheric models

What are iono_kwargs??

In our top-level functions, we allow generic keyword arguments (kwargs) to be passed in and down to our ionospheric models. This will appear as **iono_kwargs: Any in a function signature. For example in get_rm_from_skycoord:

from __future__ import annotations

import astropy.units as u
import numpy as np
from astropy.coordinates import EarthLocation, SkyCoord
from astropy.time import Time
from spinifex import get_rm

help(get_rm.get_rm_from_skycoord)

Help on function get_rm_from_skycoord in module spinifex.get_rm:

get_rm_from_skycoord(
    loc: 'EarthLocation',
    times: 'Time',
    source: 'SkyCoord',
    iono_model_name: 'str' = 'ionex',
    magnetic_model_name: 'str' = 'ppigrf',
    **iono_kwargs: 'Any'
) -> 'RM'
    get rotation measures for user defined times and source coordinate

    Parameters
    ----------
    loc : EarthLocation
        observer location
    times : Time
        times
    source : SkyCoord
        coordinates of the source
    iono_model_name : str, optional
        ionospheric model name, by default "ionex". Must be a supported ionospheric model.
    magnetic_model_name : str, optional
        geomagnetic model name, by default "ppigrf". Must be a supported geomagnetic model.
    iono_kwargs : dict
        keyword arguments for the ionospheric model


    Returns
    -------
    RM
        rotation measure object

If no options are specified, a set of defaults will be used depending on the model chosen. The available options will also depend on the model. Specifying invalid options will raise an error. For example:

### Required to load local data for example - not needed for normal use
from importlib import resources

with resources.as_file(resources.files("spinifex.data.tests")) as datapath:
    spinifex_data = datapath
###
times = Time("2020-01-08T01:00:00") + np.arange(10) * 25 * u.min
# create source object
source = SkyCoord(ra=350.85 * u.deg, dec=58.815 * u.deg)
# create Earth Location
lon = 6.367 * u.deg
lat = 52.833 * u.deg
dwingeloo = EarthLocation(lon=lon, lat=lat, height=0 * u.km)


# Let's intentionally set a bad option to show how the function will fail
try:
    rm = get_rm.get_rm_from_skycoord(
        loc=dwingeloo,
        times=times,
        source=source,
        # We set these options to use the data packaged with spinifex
        # Unsetting them will cause the function to download the data from the internet
        prefix="cod",
        output_directory=spinifex_data,
        bad_option="bad_option",
    )
except Exception as e:
    print(e)

Incorrect arguments {'prefix': 'cod', 'output_directory': PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/spinifex/checkouts/latest/spinifex/data/tests'), 'bad_option': 'bad_option'} for ionospheric model <function get_density_ionex_single_layer at 0x7114aac13100>

We can inspect the available options using a couple of our helper functions:

from pprint import pprint

from spinifex.ionospheric.models import (
    ionospheric_models,
    parse_iono_kwargs,
    parse_iono_model,
)

print("Supported models are: ")
pprint(f"{list(ionospheric_models.__annotations__.keys())}")

for model_name in ionospheric_models.__annotations__:
    model = parse_iono_model(model_name)
    default_options = parse_iono_kwargs(model)
    print(f"Model {model_name} has default options: ")
    pprint(f"{dict(default_options)}")

INFO models - parse_iono_kwargs: Using ionospheric model <function get_density_ionex_single_layer at 0x7114aac13100> with options server=<Servers.CHAPMAN: 'chapman'> prefix='uqr' url_stem=None time_resolution=None solution='final' output_directory=None correct_uqrg_rms=True height=<Quantity 350. km> remove_midnight_jumps=True
INFO models - parse_iono_kwargs: Using ionospheric model <function get_density_ionex_iri at 0x7114a0001bc0> with options server=<Servers.CHAPMAN: 'chapman'> prefix='uqr' url_stem=None time_resolution=None solution='final' output_directory=None correct_uqrg_rms=True height=<Quantity 350. km> remove_midnight_jumps=True
INFO models - parse_iono_kwargs: Using ionospheric model <function get_density_tomion at 0x7114a0002160> with options output_directory=None

Supported models are:
"['ionex', 'ionex_iri', 'tomion']"
Model ionex has default options:
("{'server': <Servers.CHAPMAN: 'chapman'>, 'prefix': 'uqr', 'url_stem': None, "
 "'time_resolution': None, 'solution': 'final', 'output_directory': None, "
 "'correct_uqrg_rms': True, 'height': <Quantity 350. km>, "
 "'remove_midnight_jumps': True}")
Model ionex_iri has default options:
("{'server': <Servers.CHAPMAN: 'chapman'>, 'prefix': 'uqr', 'url_stem': None, "
 "'time_resolution': None, 'solution': 'final', 'output_directory': None, "
 "'correct_uqrg_rms': True, 'height': <Quantity 350. km>, "
 "'remove_midnight_jumps': True}")
Model tomion has default options:
"{'output_directory': None}"