feat(data): add Asplund 2009 photospheric reference abundances

Add reference photospheric elemental abundances from Asplund et al. (2009)
for computing FIP bias and elemental fractionation factors in solar wind
composition analysis.

New module: solarwindpy.data.reference
- ReferenceAbundances class with photospheric_abundance() method
- Returns abundance ratios (e.g., Fe/O, Ne/O) with uncertainties
- Data stored in asplund.csv, loaded via importlib.resources

Reference:
Asplund, M., Grevesse, N., Sauval, A. J., & Scott, P. (2009).
The Chemical Composition of the Sun.
Annual Review of Astronomy and Astrophysics, 47(1), 481-522.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: blalterman

solarwindpy/__init__.py

@@ -20,7 +20,7 @@
     spacecraft,
     alfvenic_turbulence,
 )
-from . import core, plotting, solar_activity, tools, fitfunctions
+from . import core, plotting, solar_activity, tools, fitfunctions, data
 from . import instabilities  # noqa: F401
 from . import reproducibility
 
@@ -43,6 +43,7 @@ def _configure_pandas() -> None:
 
 __all__ = [
     "core",
+    "data",
     "plasma",
     "ions",
     "tensor",

solarwindpy/data/__init__.py

@@ -0,0 +1,5 @@
+"""Solar wind reference data and constants."""
+
+from .reference import ReferenceAbundances
+
+__all__ = ["ReferenceAbundances"]

solarwindpy/data/reference/__init__.py

@@ -0,0 +1,126 @@
+"""Reference photospheric abundances from Asplund et al. (2009).
+
+Reference:
+    Asplund, M., Grevesse, N., Sauval, A. J., & Scott, P. (2009).
+    The Chemical Composition of the Sun.
+    Annual Review of Astronomy and Astrophysics, 47(1), 481-522.
+    https://doi.org/10.1146/annurev.astro.46.060407.145222
+"""
+
+__all__ = ["ReferenceAbundances", "Abundance"]
+
+import numpy as np
+import pandas as pd
+from collections import namedtuple
+from importlib import resources
+
+Abundance = namedtuple("Abundance", "measurement,uncertainty")
+
+
+class ReferenceAbundances:
+    """Photospheric elemental abundances from Asplund et al. (2009).
+
+    Abundances are stored in 'dex' units:
+        log(epsilon_X) = log(N_X/N_H) + 12
+
+    where N_X is the number density of element X and N_H is hydrogen.
+
+    Example
+    -------
+    >>> ref = ReferenceAbundances()
+    >>> fe_o = ref.photospheric_abundance("Fe", "O")
+    >>> print(f"Fe/O = {fe_o.measurement:.4f} +/- {fe_o.uncertainty:.4f}")
+    Fe/O = 0.0646 +/- 0.0060
+    """
+
+    def __init__(self):
+        self._load_data()
+
+    @property
+    def data(self):
+        """Elemental abundances in dex units."""
+        return self._data
+
+    def _load_data(self):
+        """Load Asplund 2009 data from package resources."""
+        with resources.files(__package__).joinpath("asplund.csv").open() as f:
+            data = pd.read_csv(
+                f, skiprows=4, header=[0, 1], index_col=[0, 1]
+            ).astype(np.float64)
+        self._data = data
+
+    def get_element(self, key, kind="Photosphere"):
+        """Get abundance measurements for an element.
+
+        Parameters
+        ----------
+        key : str or int
+            Element symbol (e.g., "Fe") or atomic number (e.g., 26)
+        kind : str, optional
+            "Photosphere" or "Meteorites" (default: "Photosphere")
+
+        Returns
+        -------
+        pd.Series
+            Series with 'Ab' (abundance in dex) and 'Uncert' (uncertainty)
+        """
+        if isinstance(key, str):
+            level = "Symbol"
+        elif isinstance(key, int):
+            level = "Z"
+        else:
+            raise ValueError(f"Unrecognized key type ({type(key)})")
+
+        out = self.data.loc[:, kind].xs(key, axis=0, level=level)
+        assert out.shape[0] == 1, f"Expected 1 row for {key}, got {out.shape[0]}"
+
+        return out.iloc[0]
+
+    @staticmethod
+    def _convert_from_dex(case):
+        """Convert from dex to linear abundance ratio."""
+        m = case.loc["Ab"]
+        u = case.loc["Uncert"]
+
+        mm = 10.0 ** (m - 12.0)
+        uu = mm * np.log(10) * u
+        return mm, uu
+
+    def photospheric_abundance(self, top, bottom):
+        """Compute photospheric abundance ratio of two elements.
+
+        Parameters
+        ----------
+        top : str or int
+            Numerator element (symbol or Z)
+        bottom : str or int
+            Denominator element (symbol or Z), or "H" for hydrogen
+
+        Returns
+        -------
+        Abundance
+            Named tuple with (measurement, uncertainty) for the ratio N_top/N_bottom
+
+        Example
+        -------
+        >>> ref = ReferenceAbundances()
+        >>> ref.photospheric_abundance("Fe", "O")
+        Abundance(measurement=0.0646, uncertainty=0.0060)
+        """
+        top_data = self.get_element(top)
+        tu = top_data.Uncert
+        if np.isnan(tu):
+            tu = 0
+
+        if bottom != "H":
+            bottom_data = self.get_element(bottom)
+            bu = bottom_data.Uncert
+            if np.isnan(bu):
+                bu = 0
+
+            rat = 10.0 ** (top_data.Ab - bottom_data.Ab)
+            uncert = rat * np.log(10) * np.sqrt((tu ** 2) + (bu ** 2))
+        else:
+            rat, uncert = self._convert_from_dex(top_data)
+
+        return Abundance(rat, uncert)

solarwindpy/data/reference/asplund.csv

@@ -0,0 +1,90 @@
+Chemical composition of the Sun from Table 1 in [1].
+
+[1] Asplund, M., Grevesse, N., Sauval, A. J., & Scott, P. (2009). The Chemical Composition of the Sun. Annual Review of Astronomy and Astrophysics, 47(1), 481–522. https://doi.org/10.1146/annurev.astro.46.060407.145222
+
+Kind,,Meteorites,Meteorites,Photosphere,Photosphere
+,,Ab,Uncert,Ab,Uncert
+Z,Symbol,,,,
+1,H,8.22 , 0.04,12.00,
+2,He,1.29,,10.93 , 0.01
+3,Li,3.26 , 0.05,1.05 , 0.10
+4,Be,1.30 , 0.03,1.38 , 0.09
+5,B,2.79 , 0.04,2.70 , 0.20
+6,C,7.39 , 0.04,8.43 , 0.05
+7,N,6.26 , 0.06,7.83 , 0.05
+8,O,8.40 , 0.04,8.69 , 0.05
+9,F,4.42 , 0.06,4.56 , 0.30
+10,Ne,-1.12,,7.93 , 0.10
+11,Na,6.27 , 0.02,6.24 , 0.04
+12,Mg,7.53 , 0.01,7.60 , 0.04
+13,Al,6.43 , 0.01,6.45 , 0.03
+14,Si,7.51 , 0.01,7.51 , 0.03
+15,P,5.43 , 0.04,5.41 , 0.03
+16,S,7.15 , 0.02,7.12 , 0.03
+17,Cl,5.23 , 0.06,5.50 , 0.30
+18,Ar,-0.05,,6.40 , 0.13
+19,K,5.08 , 0.02,5.03 , 0.09
+20,Ca,6.29 , 0.02,6.34 , 0.04
+21,Sc,3.05 , 0.02,3.15 , 0.04
+22,Ti,4.91 , 0.03,4.95 , 0.05
+23,V,3.96 , 0.02,3.93 , 0.08
+24,Cr,5.64 , 0.01,5.64 , 0.04
+25,Mn,5.48 , 0.01,5.43 , 0.04
+26,Fe,7.45 , 0.01,7.50 , 0.04
+27,Co,4.87 , 0.01,4.99 , 0.07
+28,Ni,6.20 , 0.01,6.22 , 0.04
+29,Cu,4.25 , 0.04,4.19 , 0.04
+30,Zn,4.63 , 0.04,4.56 , 0.05
+31,Ga,3.08 , 0.02,3.04 , 0.09
+32,Ge,3.58 , 0.04,3.65 , 0.10
+33,As,2.30 , 0.04,,
+34,Se,3.34 , 0.03,,
+35,Br,2.54 , 0.06,,
+36,Kr,-2.27,,3.25 , 0.06
+37,Rb,2.36 , 0.03,2.52 , 0.10
+38,Sr,2.88 , 0.03,2.87 , 0.07
+39,Y,2.17 , 0.04,2.21 , 0.05
+40,Zr,2.53 , 0.04,2.58 , 0.04
+41,Nb,1.41 , 0.04,1.46 , 0.04
+42,Mo,1.94 , 0.04,1.88 , 0.08
+44,Ru,1.76 , 0.03,1.75 , 0.08
+45,Rh,1.06 , 0.04,0.91 , 0.10
+46,Pd,1.65 , 0.02,1.57 , 0.10
+47,Ag,1.20 , 0.02,0.94 , 0.10
+48,Cd,1.71 , 0.03,,
+49,In,0.76 , 0.03,0.80 , 0.20
+50,Sn,2.07 , 0.06,2.04 , 0.10
+51,Sb,1.01 , 0.06,,
+52,Te,2.18 , 0.03,,
+53,I,1.55 , 0.08,,
+54,Xe,-1.95,,2.24 , 0.06
+55,Cs,1.08 , 0.02,,
+56,Ba,2.18 , 0.03,2.18 , 0.09
+57,La,1.17 , 0.02,1.10 , 0.04
+58,Ce,1.58 , 0.02,1.58 , 0.04
+59,Pr,0.76 , 0.03,0.72 , 0.04
+60,Nd,1.45 , 0.02,1.42 , 0.04
+62,Sm,0.94 , 0.02,0.96 , 0.04
+63,Eu,0.51 , 0.02,0.52 , 0.04
+64,Gd,1.05 , 0.02,1.07 , 0.04
+65,Tb,0.32 , 0.03,0.30 , 0.10
+66,Dy,1.13 , 0.02,1.10 , 0.04
+67,Ho,0.47 , 0.03,0.48 , 0.11
+68,Er,0.92 , 0.02,0.92 , 0.05
+69,Tm,0.12 , 0.03,0.10 , 0.04
+70,Yb,0.92 , 0.02,0.84 , 0.11
+71,Lu,0.09 , 0.02,0.10 , 0.09
+72,Hf,0.71 , 0.02,0.85 , 0.04
+73,Ta,-0.12 , 0.04,,
+74,W,0.65 , 0.04,0.85 , 0.12
+75,Re,0.26 , 0.04,,
+76,Os,1.35 , 0.03,1.40 , 0.08
+77,Ir,1.32 , 0.02,1.38 , 0.07
+78,Pt,1.62 , 0.03,,
+79,Au,0.80 , 0.04,0.92 , 0.10
+80,Hg,1.17 , 0.08,,
+81,Tl,0.77 , 0.03,0.90 , 0.20
+82,Pb,2.04 , 0.03,1.75 , 0.10
+83,Bi,0.65 , 0.04,,
+90,Th,0.06 , 0.03,0.02 , 0.10
+92,U,-0.54 , 0.03,,