Module pyaurorax.util

The util module provides helper methods such as converting arbitrary geographic locations to North/South B-trace geographic locations.

Note that all functions and classes from submodules are all imported at this level of the util module. They can be referenced from here instead of digging in deeper to the submodules.

"""
The util module provides helper methods such as converting
arbitrary geographic locations to North/South B-trace geographic
locations.

Note that all functions and classes from submodules are all imported
at this level of the util module. They can be referenced from
here instead of digging in deeper to the submodules.
"""

# function and class imports
from .calculate_btrace import (ground_geo_to_nbtrace,
                               ground_geo_to_sbtrace)

# pdoc imports and exports
from .calculate_btrace import __pdoc__ as __btrace_pdoc__
__pdoc__ = __btrace_pdoc__
__all__ = [
    "ground_geo_to_nbtrace",
    "ground_geo_to_sbtrace",
]

Sub-modules

pyaurorax.util.calculate_btrace

Helper functions for calculating the north and south B-trace geographic locations for ground-based instruments.

Functions

def ground_geo_to_nbtrace(geo_location: Location, timestamp: datetime.datetime) ‑> Location

Convert geographic location to North B-Trace geographic location

The timestamp is required because when calculating the B-trace values, the location is converted into geomagnetic coordinates. This conversion is different based on the timestamp since the magnetic coordinates change over time.

Note: aacgmv2 must be installed. To install it, you can run "python -m pip install pyaurorax[aacgmv2]".

Args

geo_location

a Location object representing the geographic location

dt

timestamp for this set of lat and lons

Returns

the north B-trace location as a Location object

Expand source code

def ground_geo_to_nbtrace(geo_location: Location,
                          timestamp: datetime.datetime) -> Location:
    """
    Convert geographic location to North B-Trace geographic
    location

    The timestamp is required because when calculating the B-trace
    values, the location is converted into geomagnetic coordinates.
    This conversion is different based on the timestamp since the
    magnetic coordinates change over time.

    Note: aacgmv2 must be installed. To install it, you can run
    "python -m pip install pyaurorax[aacgmv2]".

    Args:
        geo_location: a Location object representing the
            geographic location
        dt: timestamp for this set of lat and lons

    Returns:
        the north B-trace location as a Location object
    """
    # check to make sure aacgmv2 is installed
    if (__aacgm_found is False):
        warnings.warn("The aacgmv2 package is not installed, so an unchanged "
                      "location object will be returned. For this function to "
                      "work, please install it using 'pip install pyaurorax[aacgmv2]'.")
        return geo_location

    # check if location is in northern hemisphere
    if (geo_location.lat is not None and geo_location.lat >= 0.0):
        # northern hemisphere, north b-trace is the same as geographic location
        return geo_location

    # calculate South B-trace and return
    sbtrace = __calculate_btrace(geo_location, timestamp)
    return sbtrace

def ground_geo_to_sbtrace(geo_location: Location, timestamp: datetime.datetime) ‑> Location

Convert geographic location to South B-Trace geographic location

The timestamp is required because when calculating the B-trace values, the location is converted into geomagnetic coordinates. This conversion is different based on the timestamp since the magnetic coordinates change over time.

Note: aacgmv2 must be installed. To install it, you can run "python -m pip install pyaurorax[aacgmv2]".

Args

geo_location

a Location object representing the geographic location

dt

timestamp for this set of lat and lons

Returns

the south B-trace location as a Location object

Expand source code

def ground_geo_to_sbtrace(geo_location: Location,
                          timestamp: datetime.datetime) -> Location:
    """
    Convert geographic location to South B-Trace geographic
    location

    The timestamp is required because when calculating the B-trace
    values, the location is converted into geomagnetic coordinates.
    This conversion is different based on the timestamp since the
    magnetic coordinates change over time.

    Note: aacgmv2 must be installed. To install it, you can run
    "python -m pip install pyaurorax[aacgmv2]".

    Args:
        geo_location: a Location object representing the
            geographic location
        dt: timestamp for this set of lat and lons

    Returns:
        the south B-trace location as a Location object
    """
    # check to make sure aacgmv2 is installed
    if (__aacgm_found is False):
        warnings.warn("The aacgmv2 package is not installed, so an unchanged "
                      "location object will be returned. For this function to "
                      "work, please install it using 'pip install pyaurorax[aacgmv2]'.")
        return geo_location

    # check if location is in southern hemisphere
    if (geo_location.lat is not None and geo_location.lat < 0.0):
        # southern hemisphere, south b-trace is the same as geographic location
        return geo_location

    # calculate North B-trace and return
    nbtrace = __calculate_btrace(geo_location, timestamp)
    return nbtrace