Skip to content

GFZ DataSet

el_paso.dataset.GFZDataSet

Bases: DataSet

A concrete implementation of DataSet for the GFZStandard.

Represents a dataset with variables defined by the GFZStandard, providing structured access to space physics measurements including particle fluxes, phase space densities, magnetic field data, and adiabatic invariants.

Attributes:

Name Type Description
datetime list[datetime]

List of datetime objects corresponding to each time step.
time NDArray[float64]

Array of time values as floats (e.g. seconds since epoch).
energy_channels NDArray[float64]

Array of energy channel center values in keV.
alpha_local NDArray[float64]

Local pitch angle array in degrees.
alpha_eq_model NDArray[float64]

Model-derived equatorial pitch angle in degrees.
alpha_eq_real NDArray[float64]

Measured equatorial pitch angle in degrees.
InvMu NDArray[float64]

First adiabatic invariant (magnetic moment) array.
InvMu_real NDArray[float64]

Measured first adiabatic invariant array.
InvK NDArray[float64]

Second adiabatic invariant array.
InvV NDArray[float64]

Third adiabatic invariant (drift shell) array.
Lstar NDArray[float64]

Roederer L* (drift shell parameter) array.
Flux NDArray[float64]

Differential particle flux array.
PSD NDArray[float64]

Phase space density array.
MLT NDArray[float64]

Magnetic local time array in hours.
B_SM NDArray[float64]

Magnetic field vector in Solar Magnetic (SM) coordinates.
B_total NDArray[float64]

Total magnetic field magnitude array in nT.
xGEO NDArray[float64]

Position vector in Geocentric (GEO) coordinates.
P NDArray[float64]

Pressure array.
R0 NDArray[float64]

Equatorial crossing distance array in Earth radii.
density NDArray[float64]

Plasma density array.
Source code in el_paso/dataset/dataset_implementations.py 
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
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
class GFZDataSet(DataSet):
    """A concrete implementation of DataSet for the GFZStandard.

    Represents a dataset with variables defined by the GFZStandard,
    providing structured access to space physics measurements including
    particle fluxes, phase space densities, magnetic field data, and
    adiabatic invariants.

    Attributes:
        datetime (list[dt.datetime]): List of datetime objects corresponding to each time step.
        time (NDArray[np.float64]): Array of time values as floats (e.g. seconds since epoch).
        energy_channels (NDArray[np.float64]): Array of energy channel center values in keV.
        alpha_local (NDArray[np.float64]): Local pitch angle array in degrees.
        alpha_eq_model (NDArray[np.float64]): Model-derived equatorial pitch angle in degrees.
        alpha_eq_real (NDArray[np.float64]): Measured equatorial pitch angle in degrees.
        InvMu (NDArray[np.float64]): First adiabatic invariant (magnetic moment) array.
        InvMu_real (NDArray[np.float64]): Measured first adiabatic invariant array.
        InvK (NDArray[np.float64]): Second adiabatic invariant array.
        InvV (NDArray[np.float64]): Third adiabatic invariant (drift shell) array.
        Lstar (NDArray[np.float64]): Roederer L* (drift shell parameter) array.
        Flux (NDArray[np.float64]): Differential particle flux array.
        PSD (NDArray[np.float64]): Phase space density array.
        MLT (NDArray[np.float64]): Magnetic local time array in hours.
        B_SM (NDArray[np.float64]): Magnetic field vector in Solar Magnetic (SM) coordinates.
        B_total (NDArray[np.float64]): Total magnetic field magnitude array in nT.
        xGEO (NDArray[np.float64]): Position vector in Geocentric (GEO) coordinates.
        P (NDArray[np.float64]): Pressure array.
        R0 (NDArray[np.float64]): Equatorial crossing distance array in Earth radii.
        density (NDArray[np.float64]): Plasma density array.
    """

    datetime: list[dt.datetime]
    time: NDArray[np.float64]
    energy_channels: NDArray[np.float64]
    alpha_local: NDArray[np.float64]
    alpha_eq_model: NDArray[np.float64]
    alpha_eq_real: NDArray[np.float64]
    InvMu: NDArray[np.float64]
    InvMu_real: NDArray[np.float64]
    InvK: NDArray[np.float64]
    InvV: NDArray[np.float64]
    Lstar: NDArray[np.float64]
    Lm: NDArray[np.float64]
    Flux: NDArray[np.float64]
    PSD: NDArray[np.float64]
    MLT: NDArray[np.float64]
    B_eq: NDArray[np.float64]
    B_total: NDArray[np.float64]
    xGEO: NDArray[np.float64]  # noqa: N815
    P: NDArray[np.float64]
    R0: NDArray[np.float64]
    density: NDArray[np.float64]
    metadata: GFZMetaData

    def __init__(
        self,
        saving_strategy: SavingStrategy,
        start_time: dt.datetime,
        end_time: dt.datetime,
        preferred_extension: MFSFormats = "nc",
        *,
        verbose: bool = True,
    ) -> None:
        """Initializes a GFZDataSet instance.

        Constructs the saving strategy, invokes the parent DataSet initializer,
        and populates the list of possible variables from class annotations.

        Args:
            saving_strategy (SavingStrategy): Instance of the saving strategy used to resolve file paths.
            start_time (dt.datetime): Beginning of the time range to load.
            end_time (dt.datetime): End of the time range to load.
            preferred_extension (MFSFormats): File format to prefer when reading
                and writing data. Defaults to ``"nc"`` (NetCDF).
            verbose (bool): If ``True``, print progress and diagnostic messages.
                Defaults to ``True``.
        """
        self.saving_strategy = saving_strategy
        self._start_time = start_time
        self._end_time = end_time
        self._preferred_ext = preferred_extension
        self._verbose = verbose

        if isinstance(self.saving_strategy, GFZStrategy):
            self._preferred_ext = "mat"
            logger.warning(
                "Overriding `preferred_extension` to 'mat' since `GFZStrategy` is used, which only supports .mat files."
                " Ignoring provided `preferred_extension` value."
            )

        if not isinstance(self.saving_strategy.data_standard, GFZStandard):
            msg = f"GFZDataSet requires a saving strategy with  `GFZStandard`, but got {type(self.saving_strategy.data_standard).__name__}"  # noqa: E501
            logger.error(msg)
            raise TypeError(msg)

        super().__init__(
            self.saving_strategy,
            self._start_time,
            self._end_time,
            self._preferred_ext,
            verbose=self._verbose,
        )

Methods:

el_paso.dataset.GFZDataSet.__init__ 

__init__

Initializes a GFZDataSet instance.

Constructs the saving strategy, invokes the parent DataSet initializer, and populates the list of possible variables from class annotations.

Parameters:

Name Type Description Default
saving_strategy SavingStrategy

Instance of the saving strategy used to resolve file paths.

 required
start_time datetime

Beginning of the time range to load.

 required
end_time datetime

End of the time range to load.

 required
preferred_extension MFSFormats

File format to prefer when reading and writing data. Defaults to "nc" (NetCDF).

 'nc'
verbose bool

If True, print progress and diagnostic messages. Defaults to True.

 True
Source code in el_paso/dataset/dataset_implementations.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
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
def __init__(
    self,
    saving_strategy: SavingStrategy,
    start_time: dt.datetime,
    end_time: dt.datetime,
    preferred_extension: MFSFormats = "nc",
    *,
    verbose: bool = True,
) -> None:
    """Initializes a GFZDataSet instance.

    Constructs the saving strategy, invokes the parent DataSet initializer,
    and populates the list of possible variables from class annotations.

    Args:
        saving_strategy (SavingStrategy): Instance of the saving strategy used to resolve file paths.
        start_time (dt.datetime): Beginning of the time range to load.
        end_time (dt.datetime): End of the time range to load.
        preferred_extension (MFSFormats): File format to prefer when reading
            and writing data. Defaults to ``"nc"`` (NetCDF).
        verbose (bool): If ``True``, print progress and diagnostic messages.
            Defaults to ``True``.
    """
    self.saving_strategy = saving_strategy
    self._start_time = start_time
    self._end_time = end_time
    self._preferred_ext = preferred_extension
    self._verbose = verbose

    if isinstance(self.saving_strategy, GFZStrategy):
        self._preferred_ext = "mat"
        logger.warning(
            "Overriding `preferred_extension` to 'mat' since `GFZStrategy` is used, which only supports .mat files."
            " Ignoring provided `preferred_extension` value."
        )

    if not isinstance(self.saving_strategy.data_standard, GFZStandard):
        msg = f"GFZDataSet requires a saving strategy with  `GFZStandard`, but got {type(self.saving_strategy.data_standard).__name__}"  # noqa: E501
        logger.error(msg)
        raise TypeError(msg)

    super().__init__(
        self.saving_strategy,
        self._start_time,
        self._end_time,
        self._preferred_ext,
        verbose=self._verbose,
    )