sscws Conjunction Example Jupyter Notebook

This Jupyter notebook demonstrates using the sscws Python package to find satellite conjunctions. Additionally, it demonstrates using cdasws Python package to get data from cdaweb for the satellite/ground stations involved in the conjunction. This notebook contains the following sections:

1. Prerequisites
2. Setup
3. Define Conjunction Query
4. Run Conjunction Query
5. Display the results
6. Setup For Access To CDAWeb Data
7. Get Data During Conjunctions
8. Additional Documentation

Prerequisites

For just satellite conjunctions, install the following software from the Python Package Index if it is not already installed.

#%pip install sscws

To also get data from cdaweb, install the following additional software from the Python Package Index.

#%pip install xarray
#%pip install cdflib
#%pip install cdasws

Setup

Execute some preliminary code that is necessary before the code that follows.

import numpy as np
from sscws.sscws import SscWs
from sscws.conjunctions import BoxConjunctionArea, ConditionOperator,\
    GroundStationCondition, GroundStationConjunction,\
    Satellite, SatelliteCondition, TraceCoordinateSystem
from sscws.coordinates import CoordinateComponent, CoordinateSystem,\
    SurfaceGeographicCoordinates
from sscws.request import DataRequest, QueryRequest, SatelliteSpecification
from sscws.timeinterval import TimeInterval
from sscws.tracing import BFieldTraceDirection, TraceType
ssc = SscWs()

Define Conjunction Query

The following code defines a query to find magnetic field line conjuctions of at least two THEMIS satellites with one of four THEMIS ground stations during the time from 2008-01-05T10:00:00Z to 2008-01-05T11:59:59Z.

sats = [
    Satellite('themisa', BFieldTraceDirection.SAME_HEMISPHERE),
    Satellite('themisb', BFieldTraceDirection.SAME_HEMISPHERE),
    Satellite('themisc', BFieldTraceDirection.SAME_HEMISPHERE),
    Satellite('themisd', BFieldTraceDirection.SAME_HEMISPHERE),
    Satellite('themise', BFieldTraceDirection.SAME_HEMISPHERE)
]
satellite_condition = SatelliteCondition(sats, 2)

box_conjunction_area = BoxConjunctionArea(TraceCoordinateSystem.GEO,
                                          3.00, 10.00)

ground_stations = [
    GroundStationConjunction('FSMI', 'THM_Fort Smith',\
        SurfaceGeographicCoordinates(59.98, -111.84),\
        box_conjunction_area),
    GroundStationConjunction('WHIT', 'THM_White Horse',\
        SurfaceGeographicCoordinates(61.01, -135.22),\
        box_conjunction_area),
    GroundStationConjunction('FSIM', 'THM_Fort Simpson',\
        SurfaceGeographicCoordinates(61.80, -121.20),\
        box_conjunction_area),
    GroundStationConjunction('GAK', 'THM_HAARP/Gakona',\
        SurfaceGeographicCoordinates(62.40, -145.20),\
        box_conjunction_area)
]
ground_station_condition = \
    GroundStationCondition(ground_stations,
                            TraceCoordinateSystem.GEO,
                            TraceType.B_FIELD)
conditions = [
    satellite_condition,
    ground_station_condition
]
query_request = \
    QueryRequest('Magnetic conjunction of at least 2 THEMIS satellites with one of 4 THEMIS ground stations during 2008 doy=1-5.',
                 TimeInterval('2008-01-05T10:00:00Z',
                              '2008-01-05T11:59:59Z'),
                 ConditionOperator.ALL,
                 conditions)

Run Conjunction Query

The following code submits the conjunction query to SSC for evaluation.

result = ssc.get_conjunctions(query_request)

Display the results

The following code displays the results of the conjunction query.

SscWs.print_conjunction_result(result)

StatusCode: ResultStatusCode.SUCCESS StatusSubCode: ResultStatusSubCode.SUCCESS
2008-01-05T10:20:00+00:00 to 2008-01-05T10:34:00+00:00
  Satellite      Lat     Lon    Radius Ground Station           Lat     Lon    ArcLen
  themisd      -1.77  242.60  74817.00 THM_Fort Smith         58.86  253.08  81676.00
  themisd      -1.85  239.79  74618.00 THM_Fort Smith         59.22  251.14  82324.00
  themise      -1.50  238.10  75081.00 THM_Fort Smith         59.21  249.82  83264.00
  themise      -1.58  235.28  75153.00 THM_Fort Smith         59.59  247.82  84142.00
2008-01-05T10:35:00+00:00 to 2008-01-05T10:59:00+00:00
  Satellite      Lat     Lon    Radius Ground Station           Lat     Lon    ArcLen
  themisa       0.52  222.02  60857.00 THM_Fort Simpson       60.30  237.17  63709.00
  themisa       0.17  217.74  61674.00 THM_Fort Simpson       61.09  233.83  66012.00
  themisd      -1.85  239.58  74603.00 THM_Fort Smith         59.23  251.00  82357.00
  themisd      -1.98  234.76  74165.00 THM_Fort Smith         59.69  247.63  83003.00
  themise      -1.59  235.07  75156.00 THM_Fort Smith         59.62  247.67  84341.00
  themise      -1.73  230.23  75184.00 THM_Fort Smith         60.18  244.19  92810.00
2008-01-05T11:00:00+00:00 to 2008-01-05T11:05:00+00:00
  Satellite      Lat     Lon    Radius Ground Station           Lat     Lon    ArcLen
  themisd      -1.99  234.56  74145.00 THM_Fort Smith         59.72  247.49  83055.00
  themisd      -2.02  233.56  74038.00 THM_Fort Smith         59.84  246.78  83411.00
  themise      -1.74  230.02  75182.00 THM_Fort Smith         60.21  244.05  92872.00
  themise      -1.77  229.01  75173.00 THM_Fort Smith         60.34  243.30  92377.00
2008-01-05T11:06:00+00:00 to 2008-01-05T11:27:00+00:00
  Satellite      Lat     Lon    Radius Ground Station           Lat     Lon    ArcLen
  themisd      -2.02  233.36  74016.00 THM_Fort Smith         59.87  246.63  83504.00
  themisd      -2.14  229.15  73507.00 THM_Fort Smith         60.45  243.60  86740.00
  themise      -1.77  228.81  75170.00 THM_Fort Simpson       60.36  243.15  92157.00
  themise      -1.90  224.57  75071.00 THM_Fort Simpson       61.03  240.02  91425.00
2008-01-05T11:28:00+00:00 to 2008-01-05T11:30:00+00:00
  Satellite      Lat     Lon    Radius Ground Station           Lat     Lon    ArcLen
  themisa      -0.24  212.51  62448.00 THM_White Horse        62.20  229.65  70754.00
  themisa      -0.27  212.14  62493.00 THM_White Horse        62.25  229.35  71101.00
  themisd      -2.14  228.95  73480.00 THM_Fort Smith         60.48  243.45  86910.00
  themisd      -2.16  228.56  73426.00 THM_Fort Smith         60.54  243.16  87234.00
  themise      -1.90  224.37  75064.00 THM_Fort Simpson       61.05  239.87  91883.00
  themise      -1.92  223.97  75050.00 THM_Fort Simpson       61.11  239.57  92860.00
2008-01-05T11:31:00+00:00 to 2008-01-05T11:37:00+00:00
  Satellite      Lat     Lon    Radius Ground Station           Lat     Lon    ArcLen
  themisa      -0.29  211.96  62515.00 THM_White Horse        62.27  229.20  71261.00
  themisa      -0.37  210.87  62641.00 THM_White Horse        62.48  228.28  71965.00
  themisd      -2.16  228.36  73399.00 THM_Fort Simpson       60.57  243.02  87387.00
  themisd      -2.19  227.16  73232.00 THM_Fort Simpson       60.72  242.13  88101.00
  themise      -1.92  223.76  75042.00 THM_Fort Simpson       61.14  239.42  93375.00
  themise      -1.96  222.55  74993.00 THM_Fort Simpson       61.36  238.53  96695.00
2008-01-05T11:38:00+00:00 to 2008-01-05T11:59:00+00:00
  Satellite      Lat     Lon    Radius Ground Station           Lat     Lon    ArcLen
  themisd      -2.20  226.96  73204.00 THM_Fort Simpson       60.75  241.99  88179.00
  themisd      -2.32  222.78  72555.00 THM_Fort Simpson       61.30  238.86  87433.00
  themise      -1.96  222.35  74984.00 THM_Fort Simpson       61.40  238.38  97250.00
  themise      -2.09  218.12  74750.00 THM_Fort Simpson       62.08  235.13  98900.00

---

Setup For Access To CDAWeb Data

The following is code to find the corresponding data from cdaweb. Note that you need to have installed CDF, spacepy, and cdasws as mentioned in prerequisites for the following.

import re
from cdasws import CdasWs
from cdasws.datarepresentation import DataRepresentation
import matplotlib.pyplot as plt
cdas = CdasWs()
gs_id = {
    'THM_Fort Smith': 'FSMI',
    'THM_White Horse': 'WHIT',
    'THM_Fort Simpson': 'FSIM',
    'THM_HAARP/Gakona': 'GAK'
}

def get_cdaweb_ds(name: str) -> str:
    if name.startswith("THM"):
        return 'THG_L2_MAG_' + gs_id[name]
    else:
        return 'TH' + name[-1].upper() + '_L2_FGM'

def get_a_mag_var_name(ds: str, names) -> str:
    match = re.search('^THG_L2_MAG_(\w*)$', ds)
    if match:
        station = match.group(1)
        return 'thg_mag_' + station.lower()
    else:
        for name in names:
            if name.endswith('fgs_btotal'):
                return name
    return None

Get Data During Conjunctions

The following code gets data from cdaweb during the conjunctions and plots it.

for conjunction in result['Conjunction']:
    time_interval = conjunction['TimeInterval']
    start = time_interval['Start']
    end = time_interval['End']
    sats = []
    for sat_des in conjunction['SatelliteDescription']:
        sats.append(sat_des['Satellite'])
    sat = conjunction['SatelliteDescription'][0]['Satellite']
    gs = conjunction['SatelliteDescription'][0]['Description'][0]['TraceDescription']['Target']['GroundStation']
    datasets = [get_cdaweb_ds(gs)]
    for sat in sats:
        datasets.append(get_cdaweb_ds(sat))
    for ds in datasets:
        var_name = get_a_mag_var_name(ds, cdas.get_variable_names(ds))
        #print('dataset, var_name:', ds, var_name)
        status, data = cdas.get_data(ds, [var_name], start, end,
                                     dataRepresentation = DataRepresentation.XARRAY)
        var_data = data[var_name]
        epoch_var_name = var_data.attrs['DEPEND_0']
        if var_data.ndim == 2:
            var_data = np.linalg.norm(var_data, axis = 1)
            data_label = 'delta magnitude ' + var_name
        else:
            data_label = 'delta ' + var_name
        mean = var_data.mean(axis = 0)
        delta_data = var_data - mean
        plt.plot(data[epoch_var_name], delta_data, label = data_label)

    plt.xlabel('UTC: ' + start.date().isoformat())
    plt.ylabel('Delta Magnetic Field Magnitude (nT)')
    plt.legend()
    plt.show()

Additional Documentation

View the sscws API for additional features. Additional notebook examples are also available.