CSESpy: A Unified Framework for Data Analysis of the Payloads on Board the CSES Satellite

Highlights

What are the main findings?

• A new Python package, CSESpy, which provides interfaces and tools for handling data from the ionospheric CSES mission, is introduced
• CSESpy features advanced analysis and visualization capabilities for multi-instrument measurements within a unified framework.

What is the implication of the main finding?

• CSESpy enhances researchers’ ability to study complex ionospheric phenomena by simplifying data handling and enabling multi-variable analysis of both space weather and seismic events.
• CSESpy flexible architecture supports integration with external datasets and embedding in wider software ecosystems.

Abstract

The China Seismo Electromagnetic Satellite (CSES) mission provides in situ measurements of the electromagnetic field, plasma, and charged particles in the topside ionosphere. Each CSES spacecraft carries several different scientific payloads delivering a wealth of information about the ionospheric plasma dynamics and properties, as well as measurement about energetic particles precipitating in the ionosphere. In this work, we introduce CSESpy, a Python package designed to provide an interface to CSES data products, with the aim of easing the pathway for scientists to carry out analyses of CSES data. Beyond simply being an interface to the data, CSESpy aims to provide higher-level analysis and visualization tools, as well as methods for combining concurrent measurements from different instruments, so as to allow multipayload studies in a unified framework. Moreover, CSESpy is designed to be highly flexible as such, it can be extended to interface with datasets from other sources and can be embedded in wider software ecosystems. We highlight some applications, also demonstrating that CSESpy is a powerful visualization tool for investigating complex events involving variations across multiple physical observables.

1. Introduction

The China Seismo Electromagnetic Satellite (CSES) mission is a constellation of Low-Earth-Orbit (LEO) satellites devoted to the study of the ionospheric environment and its interaction with the Earth atmosphere and lithosphere, as well as the magnetosphere and the interplanetary plasma. The CSES mission aims to enhance our knowledge of the plasma and of the electromagnetic field dynamics in the ionosphere. The main scientific objective of the CSES mission is the investigation of ionospheric signatures of seismic activity (either electromagnetic perturbations, e.g., [1,2,3] or plasma perturbations [4]), to advance our understanding of the lithosphere–atmosphere–ionosphere coupling (LAIC, [5]). Complementary to its primary objective is the investigation of ionospheric variability induced by solar–terrestrial interactions and its coupling with the magnetosphere and the interplanetary plasma (e.g., the study of geomagnetic storms and substorms e.g., [6,7,8], of auroral variability [9], and of the climatology of plasma bubbles [10,11], to name a few), that is, the research area known as space weather.

The first spacecraft, CSES-01 [12], was launched on February 2018 and since then has provided continuous measurements of nine scientific payloads. Among those, the High Precision Magnetometer (HPM, a fluxgate magnetometer, [13]) and the Search Coil Magnetometer (SCM, [14]) take measurements of the magnetic field (from DC up to 20 kHz), the Electric Field Detector (EFD, [15]) measures the electric field by means of the double-probe technique (from DC up to 3.5 MHz), the Langmuir Probe (LAP, [16]) measures electron plasma density and temperature (with a cadence of 3 s), and the Plasma Analyzer Package (PAP [17]) measures the density of ions (H+, He+, O+), O+ temperature and drift velocities, and relative density fluctuations with a cadence of 1 s. For energetic particles, the High Energy Particle Package (HEPP, [18]) measures the energy spectrum, flux, and pitch-angle distribution of energetic protons and electrons and soft X-ray emissions from the Sun. The last instrument onboard CSES-01 is the High Energy Particle Detector (HEPD-01) [19], which measures the integrated rate (counts per second) and the flux of electrons (from 3 to 100 MeV) and protons (from 30 to 200 MeV) as a function of energy and pitch angle.

To date, observations employing the suite of instruments just described have led to several studies on space weather dynamics, for instance, characterization of the variability and properties of the field aligned currents at auroral latitudes (via EFD measurements, e.g., [20,21]), climatological studies of plasma depletions (using LAP and EFD observations [11]), and assessments of geomagnetic storm effects (through HPM and HEPD measurements [7]). With regards to its primary scientific objective, much effort has been invested in studying the ionospheric response to seismic activity employing multipayload in situ measurements from CSES-01, including detection of anomalous signals in the vicinity of earthquakes (EQs) concurrently [22] and before their occurrence, e.g., [23]. Such studies provide invaluable in situ information that complements investigations of coseismic and preseismic signals derived from remote sensing observations (measuring, e.g., the vertical Total Electron Content, vTEC, [24,25]), which have a lower-frequency resolution than that of CSES instruments.

The payloads just described measure different physical quantities (electromagnetic fields in different frequency bands, density, temperature and velocity of ionospheric-plasma ions and electrons, particles fluxes, etc.) using different timing, sampling frequency, and formats for the measured physical quantities. Moreover, some of those data require a postprocessing for correcting known issues or reformatting (as we will show, e.g., in Section 3.1), so as to obtain a final product adequate for scientific investigation. For instance, the temporal misalignment observed between EFD and SCM [26,27] needs to be corrected before conducting any scientific investigation that exploits data from both instruments. Indeed, if not accounted for, such misalignment can severely affect the study of electromagnetic wave phenomena such as, e.g., whistler events generated by lightning (see, e.g., [28]) or Pc1 waves at the polar cap associated with sub-auroral proton precipitation [29]. Data preprocessing and correction is fundamental also for the search of concurrent and, eventually, preceding signals of earthquakes (see, e.g., Section 3.5).

Scientists usually deal with these problems by themselves, by writing personalized routines for the processing of the data that solve various issues encountered, often without having a comprehensive knowledge of the working of the instrument and/or the data-processing pipeline. Besides severely hindering colleagues’ ability to replicate their scientific results, these issues also put the scientist at risk of data misuse and significantly complicate the processes of cross-validation and scientific collaboration. These considerations make evident the need for a unified framework that provides an interface between the scientist and CSES data by retrieving, reading, and processing the data of interest (also applying data correction, if needed) and delivering them to the user in a clear, unified, and harmonized manner. Here, we present CSESpy, a new Python package that we developed with the aim of providing such a framework. CSESpy is designed to be highly flexible. Beyond being simply a modern interface to CSES data, CSESpy also provides higher-level data-analysis and -visualization tools, and methods to combine and exploit concurrent measurements from different payloads, so to allow multipayload studies and maximize the scientific outcome.

Indeed, CSESpy adds to a growing family of tools designed to support scientific research. An excellent example in the context of heliophysics is pySPEDAS [30], a Python implementation of the Space Physics Environment Data Analysis System (SPEDAS) provided by NASA. Among other things, pySPEDAS can retrieve online scientific data from more than thirty space-based and ground-based missions, and perform coordinate transforms, interpolation, and unit conversions. For ionospheric studies, the VirES for Swarm platform provides an ecosystem of libraries and tools for the retrieval, visualization, and analysis of scientific data products from the Swarm mission [31]. Another paramount example is SpacePy, a Python package that aims to ease data analysis, and modeling and visualization of scientific data relevant to space physics studies [32].

The rest of this work is structured as follows. In Section 2, we describe the L2 CSES data and describe the CSESpy package. In Section 3, we give examples of application of CSESpy to the loading, correction, and visualization of CSES data, also with an application example with Swarm data. Section 4 is devoted to discussion and summary.

2. Materials and Methods

In this section, we describe the Level 2 public data of CSES-01. For a complete description of the data, the naming convention, and further details, we refer the reader to the CSES-01 data manual [33].

2.1. CSES Level 2 Public Data

Currently, the CSES mission only has one spacecraft in operation, CSES-01. A second twin spacecraft, CSES-02, was launched on 14 June 2025 and is currently in the commissioning phase. CSES-01 flies in a sun-synchronous orbit at an altitude of ∼500 km, i.e., inside the F2-layer of the ionosphere, with an orbital period of ∼94 min. Its inclination is 97°, with a 02:00 a.m. ascending-node local time and a revisit period of 5 days. Due to operational constraints, scientific instruments are turned off at polar latitudes when the spacecraft is located above/below a geographic latitude of roughly ±65° (in some orbits; the limit extends up to ∼70°). Each orbit is effectively divided into one descending (labeled “0”) and one ascending (labeled as “1”) semi-orbit for the day side and the night side, respectively (in the following, we refer to the orbit number as the semi-orbit number; for example, orbit number 028981 denotes semi-orbit 2898, night side). This distinction is kept in the Level 2 (L2) scientific data of the CSES mission (available at www.leos.ac.cn and https://limadou.ssdc.asi.it/ upon registration, accessed on 2 October 2025). Data are organized into files, each one containing the data from a specific semi-orbit, instrument (EFD, SCM, etc.), and data product type, e.g., waveforms (with the term “waveform”, we refer to the timeseries of the vector components of the electric and the magnetic fields) and power spectral densities (PSDs) in the ULF band for EFD, energy particle flux and spectrum for HEPD. The HDF5 [34] file format is employed. For file naming conventions, as well as for a detailed description of the data organization, see [33]. In

Table 1. Scientific payloads of CSES-01 implemented in CSESpy, together with the physical quantities they provide and the cadence/sampling frequency of the instruments. For the LAP, only the 50 mm probe is used for scientific measurements. ULF, ELF, VLF, and HF denote the Ultra Low Frequency (ULF), the Extreme Low Frequency (ELF), the Very Large Frequency, and the High Frequency bands respectively.

Instrument	Data Product	Physical Observables
EFD	ULF, ELF, VLF	electric field waveforms (from DC to 5 kHz)
	ULF, ELF, VLF, HF	electric field PSDs (from DC to 3.5 MHz)
SCM	ULF, ELF, VLF	magnetic field waveforms and PSD (from 10 Hz to 20 kHz)
HPM	FGM-1 Hz	magnetic field waveforms (from DC to 1 Hz)
LAP	50 mm	electron density and temperature (3 s)
PAP	–	H+, He+, O+ densities; O+ temperature and drift velocity (1 s)
HEPP	L, H, X	Electron and proton fluxes (1 s)
HEPD-01	–	Particle fluxes

, we report the main payloads of CSES routinely used for scientific investigation and currently implemented in CSESpy (see Section 2.2).

A convention common to all CSES data product files is employed in naming both the files and the variables stored therein. An alphanumeric naming convention is used for the scientific data which uniquely identifies them, but at the same time hides their physical meaning.

2.2. The CSESpy Python Package: Design and Workflow

We now introduce the CSESpy Python package. A prototype of CSESpy was initially created as part of the data pipeline used to identify latitudinal intervals characterized by high levels of electromagnetic activity at auroral latitudes in the orbit of CSES-01 [21]. More specifically, it was a package developed internally for automatically retrieving (from the file system), loading, and processing all L2 data from the EFD and HPM payloads, including correcting for known errors and artifacts eventually present in the data and performing rotations of electric and magnetic fields in the desired reference frame, e.g., the North-East-Center (NEC) frame. CSESpy was later extended to include handling of SCM, LAP, and PAP instruments. Since the end of 2023, the CSESpy capabilities have been further extended to include L2 data from the HEPP and HEPD payloads. We remark that, thanks to the common convention used in the production of L2 data, CSESpy can also be used for the handling of the CSES-02 satellite, launched on 14 June 2025.

CSESpy is organized so that the end user can load, manipulate, and visualize the desired data simply by typing a few commands. All operations are carried through the CSES class, which is the main interface between the data and the user. The main features of CSESpy include

• Automatic and flexible organization of database filesystem;
• Loading of a database containing information about CSES orbits;
• Data search and selection based on payload name, time span, orbit number, or filename string: if a database of the orbits is also available, a search based on longitude and latitude range can also be performed;
• Loading of multiple semi-orbits and payloads;
• Concurrent multipayload plotting.

In Figure 1, we sketch a flowchart that highlights a typical CSESpy workflow. Through the CSES.load_CSES method, data are loaded as pandas.Dataframe objects (as items of the CSES.data dictionary). This choice offers several advantages in the organization of the data and allows (among others) a straightforward interpolation and synchronization between data from different payloads. To better support data retrieval and selection, the CSES_database class is also available. It can be instantiated directly by the CSES class (as the CSES.orbitdb attribute) and contains a database of the CSES-01 orbits, together with methods for orbit selection and plotting. Currently, the database must be provided by the user in the form of an HDF5 file.

CSESpy goes beyond being a tool for data loading and visualization. It also aims at incorporating procedures for the automatic postprocessing of L2 public data and to provide the user with additional features, such as

• Correction for known artifacts/issues in L2 data;
• Automatic interpolation/resampling in time between different data products;
• Possibility to save processed/analyzed data to dedicated HDF5 files;
• Calculation of Altitude Adjusted Corrected Geomagnetic (aacgm) and Quasi-Dipole (QD) coordinates [35,36];
• Calculation of geomagnetic field from the CHAOS-8 model (available at https://www.spacecenter.dk/files/magnetic-models/CHAOS-8/, accessed on 20 December 2024) [37];
• Calculation of spectrograms from waveforms (via the short-time Fourier transform).

The purpose of postprocessing operations is two-fold. On the one hand, it allows one to expose CSES-01 data from all payloads to the user, directly translating them to a format that is immediately understandable and usable for science. On the other hand, postprocessing takes care to correct for known issues that may be present in the data (see Section 3.1).

2.3. Loading EFD and SCM Data

We now explain how L2 public data from CSES payloads are loaded in CSESpy. In particular, we will focus on EFD-01 and SCM-01, since data from other payloads (LAP, HPM, PAP) require only little care to be translated into data structures ready for scientific analysis.

According to the CSES-01 data manual [33], L2 public data are stored in HDF5 files, each containing measurements of one data product from one semi-orbit. Files are named according to the convention reported in

Table 2. File-naming convention of CSES-01 L2 data.

File naming template:
CSES_01_INS_X_L02_AX_orbitn_YYYYMMDD_hhmmss_YYYYMMDD_hhmmss_XXX.h5
<start_date>        <end_date>
INS	Instrument code (EFD, LAP, HPM, SCM, PAP, HEP, GRO, TBB)
X	Instrument number (identifies the data product)
AX	Observation item code (e.g., A1 for EFD, A2 for SCM)
orbitn	Orbit number (see Section 2)
YYYYMMDD	Start/end date of measurements
hhmmss	Start/end time of measurements
XXX	Receiving ground station code

.

Each measured observable (e.g., electric field waveforms, electron density, particle fluxes, etc.) is stored in a dataset that is uniquely identified via an alphanumeric naming convention. In

Table 3. Examples of CSES-01 dataset organization for EFD, SCM, LAP, HEP, and HEPD data products (see [33] for a complete list). From left to right: dataset name used in the HDF5 file, related physical quantity, corresponding instrument and band (if applicable), its shape, and its physical units. Datasets enclosed between horizonal lines belong to the same data product. In the shape, N is different for each data product and identifies the number of data packets contained in a file.

Name	Definition	Instrument—Band	Shape	Units
A111_W	$E_x$ waveform	EFD—ULF	(N, 256)	V/m
A112_W	$E_y$ waveform	EFD—ULF	(N, 256)	V/m
A113_W	$E_z$ waveform	EFD—ULF	(N, 256)	V/m
...
A121_W	$E_x$ waveform	EFD—ELF	(N, 2048)	V/m
A122_W	$E_y$ waveform	EFD—ELF	(N, 2048)	V/m
A123_W	$E_z$ waveform	EFD—ELF	(N, 2048)	V/m
A121_P	$E_x$$\sqrt{\mathrm{PSD}}$	EFD—ELF	(N, 1024)	V/m/$\sqrt{\mathrm{Hz}}$
A122_P	$E_y$$\sqrt{\mathrm{PSD}}$	EFD—ELF	(N, 1024)	V/m/$\sqrt{\mathrm{Hz}}$
A123_P	$E_z$$\sqrt{\mathrm{PSD}}$	EFD—ELF	(N, 1024)	V/m/$\sqrt{\mathrm{Hz}}$
...
A231	$B_x$ waveform	SCM—ULF	(N, 4096)	nT
A232	$B_y$ waveform	SCM—ULF	(N, 4096)	nT
A233	$B_z$ waveform	SCM—ULF	(N, 4096)	nT
...
A311	electron density $n_e$	LAP	(N, 1)	${\mathrm{m}}^{-3}$
A321	electron temperature $T_e$	LAP	(N, 1)	K
...
A411	Electron Spectrum	HEPP_L	(N, 256, 9)	${\displaystyle \frac{\mathrm{counts}}{{\mathrm{cm}}^2·\mathrm{s}·\mathrm{str}·\mathrm{MeV}}}$
A412	Proton Spectrum	HEPP_L	(N, 256, 9)	${\displaystyle \frac{\mathrm{counts}}{{\mathrm{cm}}^2·\mathrm{s}·\mathrm{str}·\mathrm{MeV}}}$
Count_electron	Electron Counts	HEPP_L	(N, 9)	count/s
Count_proton	Proton Counts	HEPP_L	(N, 9)	count/s
...
A411	Electron Spectrum	HEPP_H	(N, 256, 36)	${\displaystyle \frac{\mathrm{counts}}{{\mathrm{cm}}^2·\mathrm{s}·\mathrm{str}·\mathrm{MeV}}}$
A412	Proton Spectrum	HEPP_H	(N, 256, 36)	${\displaystyle \frac{\mathrm{counts}}{{\mathrm{cm}}^2·\mathrm{s}·\mathrm{str}·\mathrm{MeV}}}$
Count_electrons	Electron Counts	HEPP_H	(N, 1)	count/s
Count_protons	Proton Counts	HEPP_H	(N, 1)	count/s
...
A413	X-ray Spectrum	HEPP_X	(N, 1024)	${\displaystyle \frac{\mathrm{counts}}{\mathrm{s}·\mathrm{str}·\mathrm{MeV}}}$
A433	Photon Counts	HEPP_X	(N, 1)	count/s
...
Count_particles	Count Particles	HEPD	(N, 1)	count/s
...

, we highlight the organization of some datasets of the EFD, the SCM, and the LAP instruments.

For EFD and SCM, waveforms (and PSDs as well. we note that, unlike as reported in [33], in the case of EFD data the square root of the PSD is stored instead of the PSD) are organized in two-dimensional arrays, whose rows identify data packets (the length of the packets depends on the data product, e.g., 2048 for EFD-ELF waveforms). For each data product, position and time at which the measurement was taken is also provided (see

Table 4. Selection of the auxiliary variables providing spacecraft position and time of the measurements for a given data product.

Name	Definition	Shape	Type	Units
VERSE_TIME	Time Relative to 1 Jan 2009, 00:00 UTC	(N, 1)	integer	ms
GEO_LAT	Geographic Latitude	(N, 1)	float	Degree °
GEO_LON	Geographic Longitude	(N, 1)	float	Degree °
...

). In particular, the temporal information is provided by the VERSE_TIME variable, which gives the time of measurements relative to midnight of 1 January 2009 UTC expressed in milliseconds.

For the LAP, the PAP, and the HPM payloads, position and time variables have the same shape of the scientific data provided. For EFD and SCM, instead, only the position and time of the first point of each data packet is provided. Data gaps are often present in the data, which are not reported. However, such information is implicitly stored in VERSE_TIME.

It is evident, from the above considerations, that preprocessing is needed before performing any kind of analysis. For data products in which the shape of the scientific measurements is the same as that of auxiliary variables, data are directly loaded and transformed into a pandas.DataFrame, eventually filling gaps that may be present in the data. An example of a DataFrame containing LAP data is shown in

Table 5. Sample of the DataFrame structure of LAP data that is loaded in CSESpy. In this case, the A311 and A321 variable names (see Table 3) have been translated to $n_e$ and $T_e$ respectively.

Time	${\mathit{n}}_{\mathit{e}}$	${\mathit{T}}_{\mathit{e}}$	gaps_mask	Alt	Lat	Lon	Orbitn
2022-01-15 14:25:59.772	1.92 $\times {10}^{10}$	2699.5	False	522.36	−69.47	−164.24	219391
2022-01-15 14:26:02.772	1.92 $\times {10}^{10}$	2848.8	False	522.33	−69.30	−164.45	219391
2022-01-15 14:26:05.772	7.08 $\times {10}^9$	1772.9	False	522.29	−69.12	−164.66	219391
2022-01-15 14:26:08.772	9.27 $\times {10}^9$	2758.6	False	522.27	−68.94	−164.86	219391
...

. For EFD and SCM waveforms, data are loaded by flattening the shape of the dataset (e.g., from (N, 2048) to (N·2048) for EFD-ELF waveforms) and then reconstructing the position and timing of each datapoint, by using linear interpolation and the knowledge of the sampling frequency of the data product that is being processed. In

Table 6. Sample of the DataFrame structure of EFD data that is loaded in CSESpy. In this case, the A111_W, A112_W, and A113_W variable names (see Table 3) have been translated to $E_x$, $E_y$, and $E_z$, respectively, and data gaps have been filled with NaNs and labeled in gaps_mask.

Time	${\mathit{E}}_{\mathit{x}}$	${\mathit{E}}_{\mathit{y}}$	${\mathit{E}}_{\mathit{z}}$	gaps_mask	...
...
2022-01-15 14:49:01.958	−0.388676	−0.128942	0.039865	False	...
2022-01-15 14:49:01.966	−0.388633	−0.128925	0.039871	False	...
2022-01-15 14:49:01.974	NaN	NaN	NaN	True	...
2022-01-15 14:49:01.982	NaN	NaN	NaN	True	...
...
2022-01-15 14:49:06.062	NaN	NaN	NaN	True	...
2022-01-15 14:49:06.070	−0.382796	−0.125008	0.039105	False	...
2022-01-15 14:49:06.078	−0.382800	−0.125007	0.039120	False	...
2022-01-15 14:49:06.086	−0.382801	−0.125008	0.039148	False	...
...

, we report a sample of the DataFrame structure of the EFD-ELF waveforms.

3. Results

In this section, we highlight the capabilities of CSESpy and present a few examples of applications in realistic scenarios of a usual research workflow.

3.1. Algorithm Correction for Electric Field Waveforms

An invaluable feature of CSESpy is the postprocessing of EFD-01 data to address known errors that, to date, are found in the public EFD-01 L2 data. Such issues arise from the processing pipeline that produces L2 data from Level 0 (L0) ones. To our knowledge, this is the first time that such errors have been reported. EFD-01 waveforms are affected by the following issues:

• Presence of systematic temporal gaps in the waveforms;
• Discretization errors in the timing of the data;
• Presence of systematic jumps in the waveforms between the data packets.

The presence of gaps was already reported in Section 2.3. The last issue is the most critical because it greatly affects data analysis. A correction procedure has been devised and is currently implemented in CSESpy (the same correction procedure is also available as an independent script at https://github.com/EmanuelePapini/EFDL2Limadou [38], accessed on 2 October 2025) to resolve or mitigate the above issues, which we now describe. Such a procedure requires the issues to be addressed sequentially since they are dependent on each other.

3.1.1. Correction of Temporal Gaps

Temporal gaps of length of 2.048 s are always found in EFD-01 data and in each semi-orbit, both in waveforms and PSDs. All gaps are usually separated by 245.76 s: they appear because of diagnostic operations of EFD, which undergoes periodic calibration of the bias current [15]. During calibration (which lasts for roughly two seconds), EFD-01 does not take measurements. As a result, data gaps appear with the length of five ELF data packets (each being 0.4096 s long) and two ULF data packets (each being 2.048 s long). Figure 2 shows an example of such gaps. After each gap, waveforms in the ELF band always begin with a spike that lasts for approximately two seconds, an instrumental artifact of the calibration procedure. Fortunately, identifying the gaps is rather easy, since it simply requires finding the times at which the temporal differences in the time variable (i.e., VERSE_TIME) exceed the length of a data packet in the respective band. Once the gaps have been found, they are filled with any constant value (including NaNs), or via linear or any custom interpolation of the surrounding data. Concurrently, a boolean mask that highlights the position of the gaps is created and added to the pandas.DataFrame. Moreover, an interpolation procedure is used to remove the spike (in the ELF data), while concurrently flagging the interval after the gap from which the spike has been removed, so as to mark them as not trustworthy data.

3.1.2. Correction of Timing Errors

The discretization error in the data timing arises from the format of the VERSE_TIME variable used in the HDF5 files (see Table 4). Indeed, such a variable is defined as an integer and denotes the time in milliseconds from midnight of 1 January 2009 (UTC time). This definition impacts the correct timing of ELF data packets (and also VLF and HF, which we do not discuss here). As already described in Section 2.3, waveforms in HDF5 files are organized as matrices of shape [N, 2048] and [N, 256] for the ELF and the ULF bands, respectively. Each row corresponds to a data packet. The VERSE_TIME variable (of shape N) contains the time of measurements of the first point of each packet. The sampling frequency in the ELF band is 5 kHz, corresponding to a sampling time of 0.2 milliseconds. Therefore, the time duration of an ELF packet is 409.6 milliseconds, which is not a multiple integer of one millisecond, thus producing a discretization error. To overcome this issue, we take as reference (for any L2 EFD-01 file) the first value of the VERSE_TIME variable and then calculate the correct timing using the sampling time of EFD-01 in the desired band, finally converting the timing to a floating variable (or to, for example, an integer variable in microseconds). Since this correction requires that no temporal gaps are present in the data (see Section 3.1.1), they must be removed before such correction is applied. This is done automatically (by the CSES.load_CSES method) when loading the data.

3.1.3. Correction of Data Jumps

Figure 3, reporting a sample of both ULF and ELF data, clearly shows the presence of regular jumps in the electric field waveforms. These jumps are always found between all ULF packets (as can be seen in the left panel of Figure 3, where jumps are located at the beginning of each packet) with an average amplitude of $\sim 0.4\mathrm{mV}/\mathrm{m}$, and between ELF packets only every two or three packets (see right panel), with an amplitude of roughly $\sim 0.2\mathrm{mV}/\mathrm{m}$. Moreover, jumps are not present in the amplitude of the electric field, nor are they present in Level 1 data, where waveforms are given in the spacecraft reference frame. The above facts, together with the observation that these jumps are exactly located between the last point of a data packet and the first one of the next, brought us to conclude that they are due to an error introduced in the rotation of the electric field vector from the spacecraft reference frame to the WGS84 frame [39].

We hypothesized that, for ULF L2 data, the electric field waveforms are rotated packet by packet, i.e., using the same rotation matrix for a data packet and eventually updating it when processing the next packet. For what concerns ELF data, the rotation matrix is updated every two or three packets, depending on whether the rotation matrix provided by spacecraft telemetry has been updated (we recall that rotation quaternions in CSES-01 are provided with a cadence of 1 s, i.e., a time slightly longer than the length of two ELF data packets). Such a discretization error in the update of the rotation matrix creates a rotational drift in each packet and causes the observed jumps. Since it is a rotation error, the jump is present only in the vector components of the electric field, while it is absent in its amplitude.

The presence of systematic jumps is the most critical issue because it introduces a systematic error that can severely affect any scientific analysis. To compensate for rotational drift, we devised the following procedure, which is implemented in CSESpy. For each jump, we calculate the rotation matrix ${\mathbf{R}}_j$ needed to align the electric field vector of the last data point of the packet before the jth jump with the electric field vector of the first data point of the next packet. The rotational drift is then removed by applying a spherical linear interpolation (SLERP) from the identity matrix (i.e., no rotation) to the matrix ${\mathbf{R}}_j$ over the whole packet, in the case of the ULF waveforms, or over the packets contained between two jumps in the case of the ELF waveforms. By denoting with $t_0=0$ the time of the first data point of the first packet after the jth$-1$ jump (or the first point of the data) and with $t_{M-1}=(M-1)/M$ the time of the last point before the jth jump (i.e., M = 256 for ULF data and 4096 or 6144 for ELF data), the electric field without rotational drift is then given by

$${\mathbf{E}}_{j,\mathrm{derot}}\left(t_i\right)=\mathrm{SLERP}(t_i;\mathbf{I},{\mathbf{R}}_j,0,1)·{\mathbf{E}}_j\left(t_i\right),$$

(1)

where ${\mathbf{E}}_j\left(t_i\right)$ is the vector electric field of the ith data point between the jth$-1$ and the jth jump and where $\mathrm{SLERP}(t_i;\mathbf{I},{\mathbf{R}}_j,0,1)$ is the rotation matrix at the time $t_i$ as obtained from a SLERP interpolation from the identity matrix $\mathbf{I}$ (at $t=0$) to the rotation matrix ${\mathbf{R}}_j$ (at $t=1$). In Figure 4, we report an example of the result of our correction of rotational drift.

Although such a procedure certainly removes the jumps, it does not ensure the correct rotation of the electric field, in the first instance because SLERP is a linear interpolation, which implicitly assumes a circular orbit for the spacecraft. More importantly, it is not ensured that the rotation matrix given by spacecraft telemetry (through attitude quaternions) corresponds to the time when the first data point of one packet was measured. This introduces potential systematic errors in the estimation of the rotational drift. To assess the amplitude of such errors, we calculated the distribution of the absolute value of the angles ($\alpha$) between packets

$$\alpha =arccos\left({\displaystyle \frac{{\mathbf{E}}_{k,N-1}·{\mathbf{E}}_{k+1,0}}{|{\mathbf{E}}_{k,N-1}\left|\right|{\mathbf{E}}_{k+1,0}|}}\right)$$

(where k denotes the kth packet), the same distribution after the correction of rotational drift, and the distribution of the angle separation between two consecutive vector electric field measurements inside the packets (i.e., excluding the angles between packets). In Figure 5, we report such distributions for the ELF data gathered in orbit 175331.

It is evident that not all angles between data packets contain jumps, since the distribution of rotational jumps is bimodal and contains a population of angles that follows the same distribution of the angle separation between any two consecutive data points. From the figure, we conclude that the maximum error introduced in the electric field rotation by the EFD-01 L0 to L2 data-processing pipeline is around 200 arcseconds (equal to ∼0.05°) (This is consistent with a rough estimate of the rotational drift of $0.07°$ obtained by dividing the rotation of a full orbit (i.e., 360°) by the orbital period of CSES-01 ($\sim 5400$ s) and also taking into account that the update rate of the rotation quaternions is 1 s), which corresponds to a pointing error of 200 m at a distance of 200 km from the spacecraft (for the purpose of geophysical studies aiming at identifying sources of electromagnetic activity, e.g., earthquakes and lightning, such pointing error is negligible). The right panel of the same figure shows the distribution of the angles between the packets after the rotational drift has been removed from the data. This plot clearly shows a bimodal distribution with the distribution of the corrected jumps now peaking at around 0.04 arcseconds. Assuming that a perfect rotation would make the distribution of angles unimodal, we can assert that the residual error in the orientation of the electric field vector after our correction procedure ranges from about 10 to 70 arcseconds (i.e., a pointing error diminished to less than half), with 60 arcseconds being the standard deviation of the distribution of the angle separations, assuming that they follow a lognormal distribution.

As an example of a scientific analysis that is greatly impacted by rotational-drift jumps, in the top panel of Figure 6, we report the PSD of the Short-Time Fourier Transform (STFT) [40], as calculated from the waveform $E_x\left(t\right)$ in the ELF band by employing non-overlapping windows of 0.8192 s (4096 points) on the ELF data and using the Hann function. A pattern of vertical comb-like stripes is clearly visible, which is caused by the presence of the rotational jumps (the black vertical stripe at about 17:59:08 is due instead to the presence of a gap in the data that has been filled with linear interpolation). In the bottom panel of the same figure, we show the PSD calculated from $E_{x,\mathrm{derot}}$. The comb-like pattern has now disappeared, and it is even possible to appreciate the presence of energetic features at around 20 Hz (highlighted by a horizontal red-dashed line), compatible with the occurrence of Schumann resonances.

3.2. Example 1: Orbit-Type Labeling

A common step in the analysis of spacecraft measurements is data selection based on orbital position and/or time. Especially when dealing with large and complex datasets, such as that of CSES-01, this task can be cumbersome and time consuming. CSESpy makes it easy to conduct these tasks, thanks to the CSES_database class. This class also allows one to perform rather complex operations (also exploiting the features of pandas.DataFrames). In this context, we now show an application that can considerably boost the scientific analysis of CSES data: the labeling of orbit types.

In Figure 7, we report all CSES-01 semi-orbits from January to April 2019. It is evident that semi-orbits do not uniformly cover the globe. Instead, they show a specific recurrence pattern; that is, CSES-01 always revisits roughly the same latitudes and longitudes (every 5 days).

The analysis of orbits revisiting the same geographical position is obviously important for Earth science studies; therefore, data selection based on the orbital pattern can be a useful feature. For instance, one could define orbit-type templates to provide the average measurement of a given ionospheric property (e.g., average electron density) to be compared to the ionospheric response to any specific phenomenon, in order to extract weak signals from the ionospheric background [22,41].

In the following, we define all the orbits covering the same geographical positions as belonging to the same “orbit type”. We can use CSESpy to label semi-orbits according to their type. The number of different orbit types is 152, with 76 ascending and 76 descending. We designed an algorithm for labeling ascending (descending) semi-orbit types with odd (even) integers increasing with longitude (for its Python implementation, see Listing A3 of Appendix A.3). The procedure is as follows. Firstly, we divide the CSES orbit database into dayside and nightside semi-orbits. For each semi-orbit, we then take its latitudinal point closest to the equator and apply a clustering algorithm to the associated longitudes, so as to identify and label the average longitude at the equator of each orbit type. The final step consists of labeling all semi-orbits in the database, according to their equatorial longitude. In Figure 8, we highlight the result of the labeling procedure: In

Table 7. Sample of the DataFrame of the CSES orbits, labeled according to “OrbitType” (see Listing A3 and text).

Time	Lat	Lon	Alt	Orbitn	OrbitType
2018-07-31 23:34:14.620	−69.603218	57.577400	525.375000	027321	89
2018-07-31 23:34:20.764	−69.242798	57.153309	525.205078	027321	89
2018-07-31 23:34:26.908	−68.881470	56.742210	525.034180	027321	89
...	...	...	...	...	...
2023-09-11 23:55:24.067	69.184998	21.656000	510.703461	311251	95
2023-09-11 23:55:30.067	69.536903	21.230600	510.768036	311251	95
2023-09-11 23:55:36.067	69.887901	20.791800	510.834412	311251	95
...	...	...	...	...	...

we report a sample of the orbit database, together with the “OrbitType” labels.

The new information about the orbit type can now be exploited directly for data selection using the CSES class. It is sufficient to instantiate a new CSES object by specifying in input the new improved orbit database (shown in Table 7) and then use the CSES.select_data_to_load() method with the following keyword argument:

$$\mathtt{orbit}\_\mathtt{database}\_\mathtt{ranges}=((’\mathtt{OrbitType}’, \mathtt{np}.\mathtt{equal},\mathtt{89}),)$$

to select all available orbits with OrbitType = 89. Data available from all the orbits with same orbit type and for the desired payload can then be loaded by using the CSES.load_CSES() method.

The example just shown highlights the flexibility of CSESpy and its customization capabilities.

3.3. Example 2: Multipayload Observation of May 2024 Geomagnetic Super Storm

A useful feature of CSESpy is the possibility to perform quicklook plots, showing concurrent multipayload measurements of CSES-01 along one or more semi-orbits. This feature comes in particularly handy for, e.g., data exploration.

On 10 May 2024, one of the most intense geomagnetic storms ever recorded impacted Earth’s environment [42]. Storm activity persisted for more than two days, until 12 May 2024, characterized by intense geomagnetic activity. As a consequence, among other things, auroras were observed at lower latitudes than usual, new temporary electron and proton radiation belts at an L-shell with $L=2-3.5$ formed which persisted for days, and a long lasting four-belts configuration appeared [43,44]. Let us assume we want to investigate the ionospheric dynamics during those days with CSES-01. CSESpy considerably eases the task, both in data selection and visualization operations. For instance, data selection can be easily achieved using selection based on time span. The desired data for payloads of interest can then be loaded and data visualized together in what we call a quicklook plot. As an example, in Figure 9 we show two plots reporting concurrent measurements of electric field waveforms (taken by EFD in the ELF band, panel a), electron density (from the 50 mm probe of the LAP instrument, panel b), the fluxes for proton and electrons with energies above 1 MeV (from the HEPP_L instrument, panel c), and PSDs in the VLF band of the magnetic and electric fields (taken by SCM and EFD, panel d and e, respectively). The plots on the left are measurements taken from one orbit of CSES-01 during the storm period, while those on the right are from another orbit of the same orbit type (see Section 3.2) but belonging to a quiet period, which we use here for comparison.

From the plot, the geomagnetically induced variations observed by the various instruments at latitudes above (below) 50° (−40°) are evident: namely, the correlation of the increase in the electron and proton fluxes (panel c) and the presence of electromagnetic fluctuations in the VLF band (green areas between 2 kHz and 20 kHz in panel d and e of the left plots, characterized by a complex latitudinal and multifrequency pattern). It is interesting to note that at high latitudes in the Southern Hemisphere (where CSES-01 measured high proton and electron fluxes), the orbit of CSES-01 (shown in Figure 10) nicely overlaps with the proton flux enhancements observed in the same period by PROBA-V/ETP (see Figure 5b of [43]). In contrast, in the quiet period orbit, almost no electromagnetic activity is detected, only electrostatic activity but with a different pattern. Thanks to CSESpy, the whole procedure to produce such plots (including data retrieval and loading) was completed in less than 10 min. Moreover, such plots can be explored interactively by the user to focus on particular intervals of interest (e.g., at auroral latitudes). This task can be repeated for many other semi-orbits or temporal intervals, thus considerably speeding up the search of data of interest for deeper scientific investigation.

3.4. Example 3: Multipayload Observation of the Ground-Level Enhancement on October 2021

The solar energetic particle (SEP) event of 28 October 2021, triggered by an X1.0-class solar flare and a full-halo CME, led to a ground-level enhancement (GLE) detected on Earth at 16:00 UT [45,46]. Observations from the China Seismo Electromagnetic Satellite (CSES-01) and other spacecraft provided comprehensive insights into this event.

CSES-01’s particle detectors, including HEPP-L, HEPP-H, and HEPD-01, recorded increased proton fluxes (50–250 MeV), in agreement with ACE, SOHO/EPHIN, and SOHO/ERNE data, enabling a detailed spectral analysis (300 keV–250 MeV). Stochastic acceleration at the CME-driven shock was identified as a primary mechanism for particle acceleration. NOAA-19 and GOES confirmed enhancements in lower-energy protons (2.5–6.9 MeV).

Geomagnetic perturbations induced by the CME were recorded by CSES-01’s payloads [46]. Figure 11 is realized using the CSESpy package, selecting only latitudes > 10°. While charged particle fluxes exhibited significant enhancements (panels c, d, and e), the corresponding electromagnetic field variations (panels a and b) remained unaffected for the whole time.

This event underscores the necessity of multipayload observations for understanding solar eruptions and their impact on space weather. The coordinated insights from CSES-01, CSES-02, and other satellites enhance our knowledge of SEP acceleration and transport processes, emphasizing the importance of collaborative space weather monitoring. Therefore, the CSESpy tool can be of great importance in improving multipayload observations.

3.5. Example 4: Frequency Analysis of Anomalies Induced by Earthquakes

Ionospheric coseismic disturbances in the electromagnetic fields were observed almost concurrently with the earthquake (EQ) that occurred in Haiti on 14 August 2021 at 12:29 UTC by both EFD and SCM payloads onboard CSES-01 during orbit 195931 ([22], hereafter DR23). Indeed, in that orbit CSES-01 was flying close to the EQ epicenter (located at a latitude of 18.417°N and a longitude of 73.480°E), less then six hours prior to the occurrence of the EQ.

DR23 were the first to discover a coseismic signal by exploiting both electric and magnetic field measurements taken in the ELF band by EFD and SCM, respectively. Their analysis involved a multifrequency characterization of the electromagnetic background in the surroundings of the EQ epicenter in order to be able to distinguish possible anomalies caused by the EQ. Three types of background were defined (quiet, disturbed, and stormy) based on the levels of geomagnetic activity. This classification was later extended to distinguish between dayside and nightside orbits [41]. Thanks to the time frequency characterization of the background, DR23 were then able to identify an anomalous signal in the electric field at around 250 Hz in orbit 195931 close to the EQ epicenter. In this section, we use CSESpy to reproduce their results, with some improvements thanks to the features implemented for the correction of the known issues of EFD L2 data (see Section 3.1).

The multifrequency characterization of the electric field is based on the calculation of the relative energy

$$\begin{array}{c}{ϵ}_{\mathrm{rel}}(\nu ,t)={\int }_{t-\Delta t/2}^{t+\Delta t/2}{\left|f_{\nu }\left(t\right)\right|}^2\mathrm{d}t/{\int }_{t-\Delta t/2}^{t+\Delta t/2}{\left|f\left(t\right)\right|}^2\mathrm{d}t,\end{array}$$

(2)

which denotes the energy content at a given frequency $\nu$ and time t of a signal $f\left(t\right)$ (i.e., a vector component of the electric field) relative to the total energy of the signal in a given interval $\Delta t$. Here, $f_{\nu }\left(t\right)$ denotes a band-filtered signal of $f\left(t\right)$ around the frequency $\nu$. In DR23, band filtering is achieved by means of Fast Iterative Filtering ([47], FIF). Here, instead, we employ the STFT implemented in CSESpy, which allows for a straightforward calculation of ${ϵ}_{\mathrm{rel}}$. Indeed, by performing an STFT of $f\left(t\right)$ that employs a non-overlapping window of length $\Delta t$, Equation (2) reduces to (using Parseval’s theorem)

$$\begin{array}{c}{ϵ}_{\mathrm{rel}}(\nu ,t)={\left|{\widehat{f}}_{\nu }\left(t\right)\right|}^2/\sum _{{\nu }^{\prime }}{\left|{\widehat{f}}_{{\nu }^{\prime }}\left(t\right)\right|}^2,\end{array}$$

(3)

where the sum is performed over all the Fourier coefficients ${\widehat{f}}_{\nu }\left(t\right)$ obtained from the transform. Following DR23, the search for EQ-induced anomalies entails the following steps:

• Identification of the background type corresponding the orbit close to the EQ.
• Identification of all available orbits passing in the vicinity of the EQ that belong to the same type of background.
• Calculation of ${ϵ}_{\mathrm{rel}}$ for all the selected orbits in a geographic interval close to the EQ.
• Calculation of ${ϵ}_{\mathrm{rel}}$ of the EQ orbit.

The first two steps require the classification of the orbits in terms of geomagnetic activity, as done in DR23. This is achieved in CSESpy by customizing the CSES_database object, similarly to what was done in Section 3.2 (for further details, see Appendix B) Orbit identification is then straightforward, as it only requires querying the CSES_database for all orbits passing close the EQ epicenter. In DR23, a geographic square of $6°\times 6°$ centered at the EQ epicenter was used for orbit selection. We modified that approach (building on what was done in Section 3.2) and selected the orbits with the same OrbitType and same geomagnetic activity of the orbit of the EQ (i.e., orbit 195391) passing in a latitudinal interval with 6° length and centered at the latitude of the EQ epicenter.

For each selected orbit and latitudinal interval, we then calculated the STFT of the vector components of the electric field measurements taken in the ELF band, using a windows of length $\Delta t=1.6384$ s (i.e., 8192 data points). Before the STFT calculation, a convolutional high-pass filter (also implemented in CSESpy) was applied to the data, so as to remove the energy content at frequencies lower than ∼1.2 Hz. The relative energy was then calculated by means of Equation (2). The result is a set $\left\{{ϵ}_{\mathrm{rel}}(\nu ,\mathrm{lat})\right\}$, with each ${ϵ}_{\mathrm{rel}}$ being defined on the same frequency grid and roughly on the same latitudinal grid. Following DR23, an interpolation on a grid of logarithmic spaced frequencies and linearly spaced latitudes is then performed to produce a homogeneous set. Finally, the background ${\overline{ϵ}}_{\mathrm{rel}}(\nu ,\mathrm{lat})$ is the average relative energy of the set (for a detailed account of the procedure, we refer the reader to Appendix B). The relative energy of the EQ orbit is also contained in the set.

In Figure 12, we report the average relative energy of the background (left) and the relative energy of orbit 195931 of the $E_z$ component of the electric field (right). Several energetic features can be observed, particularly between 200 and 300 Hz between latitude $\sim 18°$ and $\sim 20°$ (corresponding to CSES-01 flying over Haiti’s mainland), roughly where DR23 reports the presence of a coseismic signal. In our case, the signal is enhanced with respect to DR23. This is due to two factors: the first is the rotational-drift correction to the electric field data which, by removing jumps between each packet, effectively removes artifacts present at roughly 1 Hz, which affects the calculation of the relative energy. The other is the application of the high-pass filters to the data, which removes energetic signals at low frequencies, thus effectively boosting the relative energy of high-frequency signals.

The use of the STFT in place of FIF decomposition does not change the results. In fact, we have repeated the analysis by employing FIF [48] and obtained both qualitative and quantitative agreement.

4. Conclusions

In this work, we introduced CSESpy, a new Python package designed to provide access to Level 2 data available from different scientific payloads of the CSES mission. CSESpy goes beyond being only an interface to the data: it incorporates (among other things)

• Procedures for the automatic postprocessing of the data and their translation into a user-friendly format (ready to use for scientific analysis);
• Methods for interpolation of data between different scientific payloads. This also allows for the direct calculation of important derived plasma quantities, such as, e.g., the ion (electron) cyclotron and plasma frequency, and their gyroradius, all important quantities for the characterization of ionospheric wave phenomena;
• Procedures for the calculation of model-related quantities (e.g., the geomagnetic field from the CHAOS-8 model) along the CSES orbit;
• Tools for data selection and visualization (including multipayload plotting capabilities);
• Procedures for correction of known artifacts and issues that are present in public L2 data from the CSES-01 database.

In particular, in Section 3.1 we reported for the first time the presence of artificial systematic jumps in the EFD waveform data, introduced by errors in the rotation of the electric field from the spacecraft reference frame to the Earth-centered WGS84 frame. The correction procedure implemented in CSESpy strongly mitigates this problem, as shown, for instance, in Figure 6 and in Section 3.5. This is perhaps one of the most important features of CSESpy since such artifacts, if not properly removed, severely hinder the possibility to conduct any scientific analysis that relies on EFD waveform data.

Thanks to the use of pandas DataFrame as a data structure paradigm, CSESpy is highly flexible, and allows one to perform complex operations with just a few commands. Example applications have shown the ability to perform advanced data selection that can also be customized (see, i.e., Section 3.2), data exploration using multipayload plot features for the study of space weather events (see Section 3.3 and Section 3.4), and electromagnetic anomaly detection for earthquake studies (see Section 3.5).

Future Development

Indeed, we have shown that CSESpy is an advanced tool suite which we are confident will become an essential tool for any user interested in exploiting CSES data. At the same time, CSESpy has great potential for improvement, thanks to the widespread use of the Python language. For instance, we foresee potential integration with other similar tools, such as the NASA pySPEDAS package [30], the ESA VirES for the Swarm Python tool [31], the spacepy package (designed for online data retrieval, analysis, and plotting for space science applications [32]), or the geospacelab Python-based library (designed to collect, manage, and visualize geospace data from different sources [49]), so as to allow interface with data from other space missions, and boost multispacecraft studies. Other improvements may include the integration of CSESpy with TITIpy, a Python package for the calculation and mapping of topside ionosphere RODI, ROTI, and ROTEI indices [50].

At present, only corrections to EFD L2 data are implemented in CSESpy. Future developments may include the implementation of other corrections, such as, e.g., intercalibration procedures for the electron density measurements from the LAP [51] and procedures for the automatic syncronization between payloads with known syncronization offsets [27].

Finally, a fundamental development that would ease the use of CSESpy by the community is the design of a graphical (front end) interface that relieves the user from the burden of using Command Line Interface (CLI).