Methods

magcoord

Routines for projecting aacgmv2 and apexpy model values onto pysat instruments.

pysatMissions.methods.magcoord.add_aacgm_coordinates(inst, glat_label='glat', glong_label='glong', alt_label='alt')

Add AACGM coordinates to instrument object using AACGMV2 package.

The Altitude Adjusted Corrected Geomagnetic Coordinates library is used to calculate the latitude, longitude, and local time of the spacecraft with respect to the geomagnetic field.

Parameters:
  • inst (pysat.Instrument) – instrument object including lat, lon, and alt as timeseries

  • glat_label (string) – label used in inst to identify WGS84 geodetic latitude (degrees N)

  • glong_label (string) – label used in inst to identify WGS84 geodetic longitude (degrees E)

  • alt_label (string) – label used in inst to identify WGS84 geodetic altitude (km, height above surface)

Returns:

Input pysat.Instrument object modified to include quasi-dipole coordinates, ‘aacgm_lat’ for magnetic latitude, ‘aacgm_long’ for longitude, and ‘aacgm_mlt’ for magnetic local time.

Return type:

inst

Example

# function added velow modifies the inst object upon every inst.load call inst.custom.attach(add_quasi_dipole_coordinates, kwargs={‘glat_label’: ‘custom_label’})

pysatMissions.methods.magcoord.add_quasi_dipole_coordinates(inst, glat_label='glat', glong_label='glong', alt_label='alt')

Add quasi-dipole coordinates to instrument object using Apexpy package.

The Quasi-Dipole coordinate system includes both the tilt and offset of the geomagnetic field to calculate the latitude, longitude, and local time of the spacecraft with respect to the geomagnetic field.

This system is preferred over AACGM near the equator for LEO satellites.

Parameters:
  • inst (pysat.Instrument) – instrument object including lat, lon, and alt as timeseries

  • glat_label (string) – label used in inst to identify WGS84 geodetic latitude (degrees)

  • glong_label (string) – label used in inst to identify WGS84 geodetic longitude (degrees)

  • alt_label (string) – label used in inst to identify WGS84 geodetic altitude (km, height above surface)

Returns:

Input pysat.Instrument object modified to include quasi-dipole coordinates, ‘qd_lat’ for magnetic latitude, ‘qd_long’ for longitude, and ‘mlt’ for magnetic local time.

Return type:

inst

Example

# function added velow modifies the inst object upon every inst.load call inst.custom.attach(add_quasi_dipole_coordinates, kwargs={‘glat_label’: ‘custom_label’})

spacecraft

Default routines for projecting values onto vectors for pysat instruments.

pysatMissions.methods.spacecraft.add_ram_pointing_sc_attitude_vectors(inst)

Add attitude vectors for spacecraft assuming ram pointing.

Presumes spacecraft is pointed along the velocity vector (x), z is generally nadir pointing (positive towards Earth), and y completes the right handed system (generally southward).

Parameters:

inst (pysat.Instrument) – Instrument object

Returns:

Modifies pysat.Instrument object in place to include S/C attitude unit vectors, expressed in ECEF basis. Vectors are named sc_(x,y,z)hat_ecef_(x,y,z). sc_xhat_ecef_x is the spacecraft unit vector along x (positive along velocity vector) reported in ECEF, ECEF x-component.

Return type:

None

Notes

Expects velocity and position of spacecraft in Earth Centered Earth Fixed (ECEF) coordinates to be in the instrument object and named velocity_ecef_* (=x,y,z) and position_ecef_ (*=x,y,z)

Adds attitude vectors for spacecraft in the ECEF basis by calculating the scalar product of each attitude vector with each component of ECEF.

pysatMissions.methods.spacecraft.calculate_ecef_velocity(inst)

Calculate spacecraft velocity in ECEF frame.

Deprecated since version 0.4.0: This function is no longer needed with the deprecation of missions_ephem. Better calculations are available through geospacepy and skyfield. calculate_ecef_velocity will be removed in versions 0.5.0+

Presumes that the spacecraft velocity in ECEF is in the input instrument object as position_ecef_*. Uses a symmetric difference to calculate the velocity thus endpoints will be set to NaN. Routine should be run using pysat data padding feature to create valid end points.

Parameters:

inst (pysat.Instrument) – Instrument object

Returns:

Modifies pysat.Instrument object in place to include ECEF velocity using naming scheme velocity_ecef_* (*=x,y,z)

Return type:

None

pysatMissions.methods.spacecraft.normalize(vector)

Normalize a time-series of vectors.

Parameters:

vector (pds.DataFrame) – A time-series consisting of vector components at each time step.

Returns:

norm_vector – The normalized version of vector

Return type:

pds.DataFrame

pysatMissions.methods.spacecraft.project_ecef_vector_onto_sc(inst, x_label, y_label, z_label, new_x_label, new_y_label, new_z_label, meta=None)

Express input vector using s/c attitude directions.

x - ram pointing y - generally southward z - generally nadir

Parameters:
  • x_label (string) – Label used to get ECEF-X component of vector to be projected

  • y_label (string) – Label used to get ECEF-Y component of vector to be projected

  • z_label (string) – Label used to get ECEF-Z component of vector to be projected

  • new_x_label (string) – Label used to set X component of projected vector

  • new_y_label (string) – Label used to set Y component of projected vector

  • new_z_label (string) – Label used to set Z component of projected vector

  • meta (array_like of dicts (None)) – Dicts contain metadata to be assigned.

Instrument Methods

Orbits

Methods to convert orbital information for propagators.

pysatMissions.instruments.methods.orbits.convert_from_keplerian(eccentricity, mean_motion, planet='earth')

Calculate orbital eccentricity from periapsis and apoapsis.

Parameters:
  • eccentricity (float) – The eccentricty of the orbit (unitless)

  • mean_motion (float) – The mean angular speed of the orbit (rad/minute)

  • planet (str) – The name of the planet of interest. Used for radial calculations. (default=’earth’)

Returns:

  • alt_periapsis (float) – The lowest altitude from the mean planet surface along the orbit (km)

  • alt_apoapsis (float) – The highest altitude from the mean planet surface along the orbit (km)

pysatMissions.instruments.methods.orbits.convert_to_keplerian(alt_periapsis, alt_apoapsis=None, planet='earth')

Calculate orbital eccentricity from periapsis and apoapsis.

Parameters:
  • alt_periapsis (float) – The lowest altitude from the mean planet surface along the orbit (km)

  • alt_apoapsis (float or NoneType) – The highest altitude from the mean planet surface along the orbit (km) If None, assumed to be equal to periapsis. (default=None)

  • planet (str) – The name of the planet of interest. Used for radial calculations and mass. (default=’earth’)

Returns:

  • eccentricity (float) – The eccentricty of the orbit (unitless)

  • mean_motion (float) – The mean angular speed of the orbit (rad/minute)