Skip to content

redplanet.Mag.sh.get 

get(
    lon: float | numpy.ndarray,
    lat: float | numpy.ndarray,
    quantity: str = "total",
    as_xarray: bool = False,
) -> (
    float | numpy.ndarray | xarray.core.dataarray.DataArray
)

Get magnetic field values at the specified coordinates. Dataset must be loaded first, see redplanet.Mag.sh.load(...).

Parameters:

Name Type Description Default
lon float | np.ndarray

Longitude coordinate(s) in range [-180, 360].

 required
lat float | np.ndarray

Latitude coordinate(s) in range [-90, 90].

 required
quantity str

Options are: ['radial', 'theta', 'phi', 'total', 'potential'], by default 'total'.

 'total'
as_xarray bool

If True, return the data as an xarray.DataArray. Default is False.

 False

Returns:

Type Description
float | np.ndarray | xr.DataArray

Data values at the the input coordinates. The return type is determined as follows:

  • float: if both lon and lat are floats.
  • numpy.ndarray (1D): if one of lon or lat is a numpy 1D array and the other is a float.
  • numpy.ndarray (2D): if both lon and lat are numpy 1D arrays. The first dimension of output array corresponds to lat values.
  • xarray.DataArray: see as_xarray parameter (this takes precedence over the above types).

Units are nanotesla [nT].

Raises:

Type Description
ValueError

If quantity is not one of ['radial', 'theta', 'phi', 'total', 'potential.
Source code in src/redplanet/Mag/sh/getter.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
@substitute_docstrings
def get(
    lon       : float | np.ndarray,
    lat       : float | np.ndarray,
    quantity  : str  = 'total',
    as_xarray : bool = False
) -> float | np.ndarray | xr.DataArray:
    """
    Get magnetic field values at the specified coordinates. Dataset must be loaded first, see `redplanet.Mag.sh.load(...)`.

    Parameters
    ----------
    {param.lon}
    {param.lat}
    quantity : str, optional
        Options are: ['radial', 'theta', 'phi', 'total', 'potential'], by default 'total'.
    {param.as_xarray}

    Returns
    -------
    {return.GriddedData}

        Units are nanotesla [nT].

    Raises
    ------
    ValueError
        If `quantity` is not one of ['radial', 'theta', 'phi', 'total', 'potential.
    """

    q = ['radial', 'theta', 'phi', 'total', 'potential']
    if quantity not in q:
        raise ValueError(f"Quantity {quantity} is not in list of supported quantities: {q}.")

    dat_mag = get_dataset()

    return dat_mag.get_values(
        lon = lon,
        lat = lat,
        var = quantity,
        as_xarray = as_xarray,
    )