Skip to content

Datasets

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.

        Parameters:
            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.

    Parameters:
        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,
    )

el_paso.dataset.PRBEMDataSet

Bases: DataSet

A concrete implementation of DataSet for the PRBEMStandard.

Represents a dataset with variables defined by the PRBEMStandard, 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.
Epoch NDArray[float64]

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

Add detailed descriptions and units for each variable based on the PRBEMStandard documentation.
Source code in el_paso/dataset/dataset_implementations.py 
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
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
class PRBEMDataSet(DataSet):
    """A concrete implementation of DataSet for the PRBEMStandard.

    Represents a dataset with variables defined by the PRBEMStandard,
    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.
        Epoch (NDArray[np.float64]): Array of time values as floats (e.g. seconds since epoch).
        #TODO: Add detailed descriptions and units for each variable based on the PRBEMStandard documentation.
        datetime (list[dt.datetime])
        Epoch (NDArray[np.float64])
        FEDU (NDArray[np.float64])
        FEDO (NDArray[np.float64])
        FEIU (NDArray[np.float64])
        Energy_FEDU (NDArray[np.float64])
        Alpha (NDArray[np.float64])
        Alpha_Eq (NDArray[np.float64])
        Position (NDArray[np.float64])
        B_Calc (NDArray[np.float64])
        B_Eq (NDArray[np.float64])
        L_star (NDArray[np.float64])
        I (NDArray[np.float64])
        MLT (NDArray[np.float64])
        L_m (NDArray[np.float64])
        PSD (NDArray[np.float64])
        R_Eq (NDArray[np.float64])
        InvMu (NDArray[np.float64])
        InvK (NDArray[np.float64])
    """

    datetime: list[dt.datetime]
    Epoch: NDArray[np.float64]
    FEDU: NDArray[np.float64]
    FEDO: NDArray[np.float64]
    FEIU: NDArray[np.float64]
    Energy_FEDU: NDArray[np.float64]
    Alpha: NDArray[np.float64]
    Alpha_Eq: NDArray[np.float64]
    Position: NDArray[np.float64]
    B_Calc: NDArray[np.float64]
    B_Eq: NDArray[np.float64]
    L_star: NDArray[np.float64]
    I: NDArray[np.float64]  # noqa: E741
    MLT: NDArray[np.float64]
    L_m: NDArray[np.float64]
    PSD: NDArray[np.float64]
    R_Eq: NDArray[np.float64]
    InvMu: NDArray[np.float64]
    InvK: NDArray[np.float64]
    metadata: PRBEMMetaData

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

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

        Parameters:
            saving_strategy (SavingStrategy):  Instance of
                the saving strategy used to resolve file paths. Defaults to
                ``ep.saving_strategies.MonthlyRBStrategy``.
            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 not isinstance(self.saving_strategy.data_standard, PRBEMStandard):
            msg = f"PRBEMDataSet requires a saving strategy with  `PRBEMStandard`, 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.PRBEMDataSet.__init__ 

__init__

Initializes a PRBEMDataSet 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. Defaults to ep.saving_strategies.MonthlyRBStrategy.

 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 
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
def __init__(
    self,
    saving_strategy: SavingStrategy,
    start_time: dt.datetime,
    end_time: dt.datetime,
    preferred_extension: MFSFormats = "nc",
    *,
    verbose: bool = True,
) -> None:
    """Initializes a PRBEMDataSet instance.

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

    Parameters:
        saving_strategy (SavingStrategy):  Instance of
            the saving strategy used to resolve file paths. Defaults to
            ``ep.saving_strategies.MonthlyRBStrategy``.
        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 not isinstance(self.saving_strategy.data_standard, PRBEMStandard):
        msg = f"PRBEMDataSet requires a saving strategy with  `PRBEMStandard`, 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,
    )