API

Main Functions

conjugate_map.calc_mlat_rings(mlats, ut=datetime.datetime(2025, 6, 5, 15, 27, 8, 672414, tzinfo=datetime.timezone.utc), method='auto', is_saved=False)

Calculate the geographic latitudes and longitudes of a circle of points for a list of magnetic latitudes. Provide a latitude in the magnetic coordinate system of your choice, and this function will return a set of geographic coordinates for points along that magnetic latitude.

Parameters

mlatsnp.array

List of magnetic latitudes

utdt.datetime

Datetime used in AACGMv2 conversion; by default, ut=dt.datetime.now(tz=dt.timezone.utc)

methodstring

Defines coordinate system used. “aacgm”: Calculated using aacgmv2. “qdip” : Calculated using apexpy. “apex” : Calculated using apexpy. “gsm” : Calculated using geopack. “auto” : defaults to aacgm.

is_savedboolean

If is_saved == True, saves .gpx versions.

to local output directory

Returns

mlats_dct: dict

Dictionary with geographic latitude and longitude points for each of the specified magnetic latitudes.

Example Use

Saves .gpx magnetic graticules for 1 January 2020 every 5 degrees latitude:

rings = calc_mlat_rings(list(range(-90, 90, 5)), ut =
                dt.datetime(2020, 1, 1), is_saved = True)

conjugate_map.conjcalc(gdf, latname='GLAT', lonname='GLON', dtime=datetime.datetime(2025, 6, 5, 15, 27, 8, 672413, tzinfo=datetime.timezone.utc), method='aacgm', mode='S2N', is_saved=False, directory='output/', name='stations')

Calculate the geographic latitudes and longitudes of conjugate points for all points in a dataframe. Calls findconj().

Parameters

gdf : dataframe of points whose conjugate points we’re finding lat : float

Geographic latitude of station.

lonfloat

Geographic longitude of station.

utdatetime

Datetime used in conversion.

methodstring

Defines method used in conversion. Options are ‘auto’, ‘geopack’, which uses IGRF + T89 to run field line traces, or ‘aacgm’, which uses AACGM v2.

limitfloat

Latitude limit, in degrees, used to switch between methods in auto mode. Default: 60. AACGM will converge above 35 degrees, but may be erroneous. See www.doi.org/10.1002/2014JA020264

latnamestring

Name of column containing latitude coordinates.

lonnamestring

Name of column containing longitude coordinates.

dtimedatetime

Datetime used in conversion.

modestring

‘S2N’ :

Return station coordinates for northern hemisphere, conjugate for southern. Map appears over the Arctic. Default.

‘N2S’ :

Return station coordinates for southern hemisphere, conjugate for northern. Map appears over the Antarctic.

‘flip’ :

Return conjugate coordinates for points regardless of hemisphere.

is_savedboolean

Boolean dictating whether the final .csv is saved to the output directory.

directorystring

Name of local directory to which .csv is saved; ‘output/’ by default.

namestring

First part of saved filename. ‘stations’ by default.

Returns

gdfpandas.DataFrame

Dataframe with PLAT, PLON columns added indicating which points to plot

See Also

conjugate_map.findconj

Note

Calls findconj for each entry in the dataframe.

conjugate_map.findconj(lat, lon, ut=datetime.datetime(2025, 6, 5, 15, 27, 8, 672405, tzinfo=datetime.timezone.utc), method='aacgm', alt=0, limit=60)

Calculate the geographic latitudes and longitudes of conjugate point for

given set of coordinates.

Parameters

latfloat

Geographic latitude of station.

lonfloat

Geographic longitude of station.

utdatetime

Datetime used in conversion.

methodstring

Defines method used in conversion. Options are ‘auto’, ‘geopack’, which uses IGRF + T89 to run field line traces, ‘aacgm’, which uses AACGM v2, ‘qdip’ for quasi-dipole coordinates via apexpy.

altfloat

Altitude of point in m. 0 by default.

limitfloat

Latitude limit, in degrees, used to switch between methods in auto mode. Default: 60. AACGM will converge above 35 degrees, but may be erroneous. See www.doi.org/10.1002/2014JA020264

Returns

lat, lonfloat

Latitude, longitude of conjugate points