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