Skip to content

redplanet.analysis.radial_profile.get_profile 

get_profile(
    ring_coords__per_ring: tuple[numpy.ndarray],
    accessor: collections.abc.Callable[
        [float, float], float
    ],
    return_stats: bool = False,
) -> (
    numpy.ndarray
    | tuple[
        numpy.ndarray, numpy.ndarray, tuple[numpy.ndarray]
    ]
)

Compute a radial profile using data extracted from concentric rings.

This function computes a one-dimensional radial profile by applying an accessor function to a set of coordinates along each ring. For each ring, it averages the values returned by the accessor function. Optionally, the function can also return additional statistical information.

Parameters:

Name Type Description Default
ring_coords__per_ring tuple[np.ndarray]

A tuple where each element is a numpy array containing (longitude, latitude) coordinate pairs for a ring. This corresponds to the second output of get_concentric_ring_coords.

 required
accessor Callable[[float, float], float]

A function that accepts two arguments (longitude and latitude), then returns a numerical value corresponding to a data point at those coordinates. See Notes for more information.

 required
return_stats bool

If True, the function returns additional statistical data (standard deviation and raw values for each ring) along with the averaged values. Default is False.

 False

Returns:

Name Type Description
avg_vals__per_ring np.ndarray

Averaged values per ring (starting with the smallest).
sigma__per_ring np.ndarray

Only returned if return_stats is True.

Standard deviations (sigma) per ring.
vals__per_ring tuple[np.ndarray]

Only returned if return_stats is True.

A tuple of 1D numpy arrays, each containing the data values extracted from each ring (shape is (num_points,)).
Notes

The input for the accessor parameter must be a function, which might be confusing. Here are two examples (assume datasets have already been loaded):

  • Example 1: For functions which only take longitude and latitude as arguments (e.g., topography), you can simply pass accessor = redplanet.Crust.topo.get.
  • Example 2: For functions which require additional arguments (e.g., vector components of the magnetic field or custom calculations), you should define a separate function that will only require longitude and latitude as arguments. There are two ways to do this:
    • Directly supply a lambda function like accessor = lambda lon, lat: redplanet.Mag.sh.get(lon, lat, quantity='radial') — this is ideal for simple one-line accessors.
    • Define a function separately like def get_value(lon, lat): return redplanet.Mag.sh.get(lon, lat, quantity='radial'), and then pass accessor = get_value — this is ideal when your implementation of the get_value function involves multiple steps, e.g. querying multiple datasets, performing calculations, conditional/loop blocks, etc.
Source code in src/redplanet/analysis/radial_profile.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
def get_profile(
    ring_coords__per_ring : tuple[np.ndarray],
    accessor              : Callable[[float, float], float],
    return_stats          : bool = False,
) -> np.ndarray | tuple[ np.ndarray, np.ndarray, tuple[np.ndarray] ]:
    """
    Compute a radial profile using data extracted from concentric rings.

    This function computes a one-dimensional radial profile by applying an accessor function to a set of coordinates along each ring. For each ring, it averages the values returned by the accessor function. Optionally, the function can also return additional statistical information.


    Parameters
    ----------
    ring_coords__per_ring : tuple[np.ndarray]
        A tuple where each element is a numpy array containing (longitude, latitude) coordinate pairs for a ring. This corresponds to the second output of `get_concentric_ring_coords`.
    accessor : Callable[[float, float], float]
        A function that accepts two arguments (longitude and latitude), then returns a numerical value corresponding to a data point at those coordinates. See Notes for more information.
    return_stats : bool, optional
        If True, the function returns additional statistical data (standard deviation and raw values for each ring) along with the averaged values. Default is False.


    Returns
    -------
    avg_vals__per_ring : np.ndarray
        Averaged values per ring (starting with the smallest).

    sigma__per_ring : np.ndarray
        Only returned if `return_stats` is True.

        Standard deviations (sigma) per ring.

    vals__per_ring : tuple[np.ndarray]
        Only returned if `return_stats` is True.

        A tuple of 1D numpy arrays, each containing the data values extracted from each ring (shape is `(num_points,)`).

    Notes
    -----
    The input for the `accessor` parameter must be a function, which might be confusing. Here are two examples (assume datasets have already been loaded):

    - Example 1: For functions which only take longitude and latitude as arguments (e.g., topography), you can simply pass `accessor = redplanet.Crust.topo.get`.
    - Example 2: For functions which require additional arguments (e.g., vector components of the magnetic field or custom calculations), you should define a separate function that will only require longitude and latitude as arguments. There are two ways to do this:
        - Directly supply a lambda function like `accessor = lambda lon, lat: redplanet.Mag.sh.get(lon, lat, quantity='radial')` — this is ideal for simple one-line accessors.
        - Define a function separately like `def get_value(lon, lat): return redplanet.Mag.sh.get(lon, lat, quantity='radial')`, and then pass `accessor = get_value` — this is ideal when your implementation of the `get_value` function involves multiple steps, e.g. querying multiple datasets, performing calculations, conditional/loop blocks, etc.
    """

    vals__per_ring = []
    for ring_coords in ring_coords__per_ring:
        vals = []
        for (lon, lat) in ring_coords:
            vals.append(accessor(lon, lat))
        vals = np.array(vals)
        vals__per_ring.append(vals)

    avg_vals__per_ring = np.array([np.mean(vals) for vals in vals__per_ring])

    if not return_stats:
        return avg_vals__per_ring

    sigma__per_ring = np.array([np.std(vals) for vals in vals__per_ring])

    return (
        avg_vals__per_ring,
        sigma__per_ring,
        tuple(vals__per_ring),
    )