API Reference#

Note

sampex handles the time conversions from second-of-day and day-of-year to pandas.Timestamp automatically. The time units are pandas.Timestamp, but you can lso use times in the datetime.datetime format to load the data.

Summary#

`sampex.load.HILT`	Load a day of HILT counts and convert the date and time to `pd.Timestamp` objects.
`sampex.load.PET`	Load a day of PET counts and convert the date and time to `pd.Timestamp` objects.
`sampex.load.LICA`	Load a day of LICA counts and convert the date and time to `pd.Timestamp` objects.
`sampex.load.Attitude`	Load a SAMEX attitude file that contains the desired day and convert the date and time to `pd.Timestamp`.
`sampex.load.date2yeardoy`	Converts a date into the "YYYYDOY" string format used extensively for the SAMPEX file names.
`sampex.load.yeardoy2date`	Converts a date in the (year day-of-year) format (YEARDOY) into a datetime.datetime object.
`sampex.download.Downloader`	Traverses and lists the directory structure on a server and download files.

Load#

class sampex.load.Attitude(load_date, verbose=False)[source]#

Bases: object

Load a SAMEX attitude file that contains the desired day and convert the date and time to pd.Timestamp. You need to explicitly call the .load() method to load the file into memory.

Once loaded, you can access the timestamps with Attitude[‘time’] You can access the other variables similarly. Alternatively, the Attitude.data attribute is a pd.DataFrame containing both the timestamps and attitude variables.

Parameters

load_date (datetime.datetime, pd.Timestamp) – The date to load the data.
verbose (bool) – If True, will notify you when data is loaded. This is useful when loading a lot of data and the computer seems unresponsive.

Notes

Attitude files span multiple days.

Longitudes are transformed from (0 -> 360) to (-180 -> 180).

Example

from datetime import datetime

import matplotlib.pyplot as plt

import sampex

day = datetime(2007, 1, 20)

a = sampex.Attitude(day)
a.load()

fig, ax = plt.subplots()
ax.step(a[‘time’], a[‘Altitude’], label=’SAMPEX Altitude’, where=’post’)
plt.suptitle(f’SAMPEX Altitude | {day.date()}’)
plt.show()

load(columns='default', remove_old_time_cols=True)[source]#

Loads the attitude file. Only columns specified in the columns arg are loaded to conserve memory.

Notes

The other than time, the loaded columns are: GEO_Radius, GEO_Long, GEO_Lat, Altitude, L_Shell, MLT, Mirror_Alt, Pitch, and Att_Flag

Longitudes are transformed from (0 -> 360) to (-180 -> 180).

class sampex.load.HILT(load_date, verbose=False, state=None)[source]#

Bases: object

Load a day of HILT counts and convert the date and time to pd.Timestamp objects. You need to explicitly call the .load() method to load the file into memory.

Once loaded, you can access the timestamps with HILT[‘time’] and counts array with HILT[column] where column depends on the HILT state

State 1: ‘SSD1’, ‘SSD2’, ‘SSD3’, ‘SSD4’, ‘PCRE’, ‘IK’,

States 2 and 4: ‘counts’ (sum of all SSD rows),

State 3: not implemented yet.

Alternatively, the HILT.data attribute is a pd.DataFrame containing both the timestamps and counts from all channels.

Parameters

load_date (datetime.datetime, pd.Timestamp) – The date to load the data.
verbose (bool) – If True, will notify you when data is loaded. This is useful when loading a lot of data and the computer seems unresponsive.
state (int) – Override the default state calculation (https://izw1.caltech.edu/sampex/DataCenter/docs/HILThires.html)

Example

from datetime import datetime

import matplotlib.pyplot as plt

import sampex

day = datetime(2007, 1, 20)

h = sampex.HILT(day)
h.load()

fig, ax = plt.subplots()
ax.step(h[‘time’], h[‘counts’], label=’HILT’, where=’post’)
plt.suptitle(f’SAMPEX-HILT | {day.date()}’)
plt.show()

load(extract=False)[source]#

Load the HILT data into memory

Parameters: extract (bool) – Wether or not to extract the HILT file if it is zipped.
Returns: The HILT data that is also saved as a HILT.data attribute.
Return type: pd.DataFrame

parse_time()[source]#: Parse the seconds of day column to a datetime column.

read_csv(path)[source]#: Reads in the CSV file given either the filename or the zip file reference

read_zip(zip_path, extract=False)[source]#: Open the zip file and load in the csv file. If extract=False than the file will only be opened and not extracted to a text file in the sampex/data/hilt directory.

reshape_20ms_state()[source]#

This function reshapes the HILT counts to 20 ms resolution assuming the data is in state 2 or 4. The counts represent the sum from the 4 SSDs.

Returns: datetime index and “counts” column.
Return type: DataFrame

class sampex.load.LICA(load_date, verbose=False)[source]#

Bases: object

Load a day of LICA counts and convert the date and time to pd.Timestamp objects. You need to explicitly call the .load() method to load the file into memory.

Once loaded, you can access the timestamps with LICA[‘time’] You can access the counts similarly, but the column names must be one of these: D4+D3 D2+D1 Stop Start Low_Pri, or High_Pri. Alternatively, the LICA.data attribute is a pd.DataFrame containing both the timestamps and counts.

Parameters

load_date (datetime.datetime, pd.Timestamp) – The date to load the data.
verbose (bool) – If True, will notify you when data is loaded. This is useful when loading a lot of data and the computer seems unresponsive.

Example

from datetime import datetime

import matplotlib.pyplot as plt

import sampex

day = datetime(2007, 1, 20)

l = sampex.LICA(day)
l.load()

fig, ax = plt.subplots()
ax.step(l[‘time’], l[‘stop’], label=’PET’, where=’post’)
plt.suptitle(f’SAMPEX-LICA (stop) | {day.date()}’)
plt.show()

load()[source]#: Loads the LICA data into self.data.

parse_time(time_index=True)[source]#: Parse the seconds of day column to a datetime column. If time_index=True, the time column will become the index.

class sampex.load.PET(load_date, verbose=False)[source]#

Bases: object

Load a day of PET counts and convert the date and time to pd.Timestamp objects. You need to explicitly call the .load() method to load the file into memory.

Once loaded, you can access the timestamps with PET[‘time’] and counts array with PET[‘counts’]. Alternatively, the PET.data attribute is a pd.DataFrame containing both the timestamps and counts (called P1_Rate in the original data).

Parameters

load_date (datetime.datetime, pd.Timestamp) – The date to load the data.
verbose (bool) – If True, will notify you when data is loaded. This is useful when loading a lot of data and the computer seems unresponsive.

Example

from datetime import datetime

import matplotlib.pyplot as plt

import sampex

day = datetime(2007, 1, 20)

p = sampex.PET(day)
p.load()

fig, ax = plt.subplots()
ax.step(p[‘time’], p[‘counts’], label=’PET’, where=’post’)
plt.suptitle(f’SAMPEX-PET | {day.date()}’)
plt.show()

load()[source]#: Loads the PET data into self.data.

parse_time()[source]#: Parse the seconds of day column to a datetime column.

sampex.load.date2yeardoy(day)[source]#

Converts a date into the “YYYYDOY” string format used extensively for the SAMPEX file names.

Parameters: day (str, datetime.datetime, pd.Timestamp) – A date.
Returns: The corresponding YYYDOY string.
Return type: str

sampex.load.yeardoy2date(yeardoy)[source]#

Converts a date in the (year day-of-year) format (YEARDOY) into a datetime.datetime object.

Parameters: yeardoy (str) – The date in the YYYDOY format
Returns: The corresponding datetime object
Return type: datetime.datetime

Plot#

sampex.plot_sampex.main()[source]#

A simple command-line interface to plot the SAMPEX data.

Parameters

year (int) – Define the date
month (int) – Define the date
day (int) – Define the date
--yscale (str) – The y-scale. Can be “linear” or “log”
--instrument (str) – The instrument to plot. Default is “all” but you can plot “HILT”, “PET”, or “LICA.

Example

plot_sampex 2007 1 20 –yscale log

Download#

class sampex.download.Downloader(url, download_dir=None)[source]#

Bases: object

Traverses and lists the directory structure on a server and download files.

Parameters

url (str) – The dataset URL.
download_dir (str or pathlib.Path) – The download directory. Must either specify here, or when you call Downloader.download().

Example

# List all of the SAMPEX-HILT State4 files and download the first one.

import sampex

d = sampex.Downloader(
‘https://izw1.caltech.edu/sampex/DataCenter/DATA/HILThires/State4/’,
download_dir=sampex.config[‘data_dir’]
)
paths = d.ls(match=’.txt’)
print(f”The downloaded files are: {paths}”)

print(f”The first file’s name is: {paths[0].name} at url {paths[0].url}”)
path = paths[0].download(stream=False)
print(f’The file was downloaded to {path}’)

download(download_dir=None, overwrite=False, stream=False)[source]#

Downloads file from self.url to the download_dir directory.

Parameters

download_dir (str or pathlib.Path) – The parent directory where to save the data to. Set it either here or when initializing the class. This
overwrite (bool) – Will overwrite an existing file.
stream (bool) – Download the data in one chunk if False, or break it up and download it in 5 Mb chunks if True.

Returns

The full path to the file.

Return type

pathlib.Path

ls(match='*')[source]#

List files and folders in self.url.

Parameters: match (str) – An optional string pattern to match.
Returns: A list of full URLs.
Return type: list

name()[source]#: Get the url filename