Using Constellations

The pysat.Constellation class is an alternative to the pysat.Instrument class. It contains multiple pysat.Instrument objects and allows quicker processing and analysis on multiple data sets.

Initialization

There are several ways of initializing a Constellation object, which may be used individually or in combination.

Specify Registered Instruments

One way to initialize a Constellation is to specify lists of desired common Instrument platform, name, tag, and inst_id values. pysat will search the directory of registered (see Registry) Instrument modules and load all possible matches. This example uses the pysatSpaceWeather ACE Instruments to create a Constellation of real-time solar wind data.

import pysat
import pysatSpaceWeather

# If you haven't registered this module before, do it now
pysat.utils.registry.register_by_module(pysatSpaceWeather.instruments)

# Now initialize the ACE real-time Constellation
ace_rt = pysat.Constellation(platforms=['ace'], tags=['realtime'])

# Display the results
print(ace_rt)

This last command will show that four Instrument objects match the desired platform and tag criteria. The name values are: epam, mag, sis, and swepam. The only Instrument defining attributes that are not unique are the name values.

Use a Constellation sub-module

Some pysatEcosystem packages, such as pysatNASA, contain sub-modules that specify commonly-used Constellations. This example uses the DE2 Instruments to create a Constellation of Dynamics Explorer 2 LANG, NACS, RPA, and WATS instruments.

import pysat
import pysatNASA

# Initalize the DE2 Constellation using the DE2 constellation module
de2 = pysat.Constellation(const_module=pysatNASA.constellations.de2)

# Display the results
print(de2)

The last command will show that nine Instrument objects were loaded by the module.

Properties shared with Instruments

Just as with a Instrument object, a Constellation object will download and load data using the download() and load() methods.

# Download today's data and load it into the Constellation
ace_rt.download()
ace_rt.load(date=ace_rt.today())

This will download data for all Constellation Instrument objects into their appropriate directories and then load the data for each Instrument.

Other Instrument properties and methods, such as the loaded date, list of variables, custom function methods, and bounds behave the same for the Constellation object.

Properties differing from Instruments

Constellation also contains attributes that are unique to this object or differ slightly from their Instrument counterparts due to differing needs.

Time index

For example, there is an index attribute, but as this must represent times for all the desired Instrument objects, this may not exactly match the individual index objects. There are two additional attributes that inform how this time index is constructed: common_index and index_res. If common_index is True, only times present in all Instrument objects are included in index. If common_index is False, the maximum time range is used instead. index_res provides the index resolution, if it is not None. If it is None, then an appropriate resolution is established from the individual index objects. It is standard to have common_index be True and index_res set to None.

Empty flags

A Constellation has more states of having data loaded than merely True or False; it is possible for only some of the desired Instrument objects to have data. To address this issue, there are two Constellation attributes that address the presence of loaded data: empty and empty_partial. If True, empty indicates that no data is loaded. If empty_partial is True and empty is False, some data is loaded. If both empty_partial and empty are False, then all Instrument objects have data.

Instrument access

You can access all the standard Instrument attributes through the instruments attribute.

# Cycle through each ACE Real Time Instrument and print the most recent
# filename
for i, inst in enumerate(ace_rt.instruments):
    print(ace_rt.names[i], inst.files.files[-1])

This should yield a list of ACE name attributes and their files with the current or tomorrow’s date. List attributes that provide information about the individual Constellation Instrument objects include: platforms, names, tags, and inst_ids.

Converting to an Instrument

At a certain point in your data analysis, it may be desirable to convert your Constellation into an Instrument. This functionality is supported by the class method to_inst(). Let us use the ACE realtime data Constellation in this example.

# Convert the output to an Instrument
rt_inst = ace_rt.to_inst()
print(rt_inst)

This yields:

pysat Instrument object
-----------------------
Platform: 'ace'
Name: 'swepam_mag_epam_sis'
Tag: 'realtime'
Instrument id: ''

Data Processing
---------------
Cleaning Level: 'clean'
Data Padding: None
Keyword Arguments Passed to list_files: {}
Keyword Arguments Passed to load: {}
Keyword Arguments Passed to preprocess: {}
Keyword Arguments Passed to download: {}
Keyword Arguments Passed to list_remote_files: {}
Keyword Arguments Passed to clean: {}
Keyword Arguments Passed to init: {}
Custom Functions: 0 applied

Local File Statistics
---------------------
Number of files: 0


Loaded Data Statistics
----------------------
Date: 09 January 2023
DOY: 009
Time range: 09 January 2023 15:15:00 --- 09 January 2023 16:45:00
Number of Times: 91
Number of variables: 33

Variable Names:
jd_ace_epam_realtime  sec_ace_epam_realtime status_e
                             ...
sw_proton_dens        sw_bulk_speed         sw_ion_temp

pysat Meta object
-----------------
Tracking 7 metadata values
Metadata for 33 standard variables
Metadata for 0 ND variables
Metadata for 0 global attributes

Currently, if you wish to save your modified Constallation data to a NetCDF file, you must first convert it to an Instrument using to_inst(). From there, you may use to_netcdf4() to create a NetCDF file.