fflib

Simplified Python Flat File Library

Examples

Reading files

from fflib import ff_reader

name = 'test'
ff = ff_reader(name)

data = ff.get_data() # Data in row-major format

times = ff.get_times() # Time column in seconds since epoch time

epoch = ff.get_epoch()

cols = ff.get_labels()

Writing files

from fflib import ff_writer
# Data to be written to file
file_name = 'test'
times = [0,1,2,3]
data = [[0,5,5],[12,251,11],[23,444,523],[434,121,123]]
columns = ['Bx', 'By', 'Bz']
epoch = 'J2000'

# Create and set information to write to a new file
ff = ff_writer(file_name)
ff.set_epoch(epoch)
ff.set_data(times, data)
ff.set_labels(columns)

# Write to file
ff.write()

Time format conversion

from fflib import ff_reader
from fflib import ff_time

# Read in times and epoch from a file
ff = ff_reader('test')
epoch = ff.get_epoch()
times = ff.get_times()

# Convert to datetime objects
# leap_indices contains locations of leap seconds
dates, leap_indices = ff_time.ticks_to_dates(ticks, epoch)

# Convert to year-month-dayThh:mm:ss.sss format
iso_ts = ff_time.ticks_to_iso_ts(ticks, epoch)

# Convert to year month day hh:mm:ss.sss format
ts = ff_time.ticks_to_ts(ticks, epoch)

API

ff_reader

check_exists(self)
      Checks that the header and data files exist and are not empty

get_abstract(self)
      Returns the abstract from the header file

get_data(self, include_times=False)
      Returns data as m x n array where m = # of rows, n = # of data columns; Optional include_times flag specifies whether to include the seconds since epoch time array as the first column

get_data_table(self)
      Returns data w/ time tick column as a structured numpy array (different from a regular np.array)

get_epoch(self)
      Returns the epoch (in string format) of the file

get_error_flag(self)
      Returns the error flag for the data

get_labels(self)
      Returns the label for each column

get_sources(self)
      Returns the sources listed for each column

get_time_range(self)
      Returns the start/end time ticks of this file

get_times(self, fmt='ticks')
      Returns the time array

get_units(self)
      Returns the units for each column

list_header(self)
      Prints key information from the header file and column desc table

shape(self)
      Returns the number of rows and columns in the file

to_csv(self, name=None, prec=7)
      Writes out the flat file data to a comma-separated-value file
      Optional name argument specifies an alternate filename to give to the .csv file
      Optional prec argument specifies the precision for the values

ff_writer

set_abstract(self, abstract)
      Sets the abstract for the header file
      Input: A list of strings (one per line)

set_data(self, times, data, epoch=None)
      Sets the time array (in SCET) and data in record format
      Optional epoch argument is passed to set_epoch()
      Input: times - array of length m, data - array of shape m x n epoch - string

set_epoch(self, epoch)
      Sets the epoch (in string-format) for the file

set_error_flag(self, flag)
      Sets the error flag

set_labels(self, names, units=None, sources=None, time_label='SCET')
      Sets the column names for non-time columns
      Input: A list of strings
      Optional col_units and col_sources arguments are passed to set_units() and set_sources() respectively
      Optional time_label arg specifies a label for the time column

set_sources(self, col_sources)
      Sets data column sources

set_units(self, col_units, time_units='Seconds')
      Sets the units for non-time columns
      Input: A list of strings
      Optional time_units arg specifies the units for the time column

write(self, name=None)
      Writes out binary data to .ffd file and ASCII header content to .ffh file
      Optional name argument specifies a filename to write to other than the one passed to the instance

ff_time

Note: Arrays of ticks, timestamps, datetimes, etc. are assumed to be increasing.

date_to_tick(date, epoch)
      Maps a datetime object to seconds since epoch

ff_ts_to_iso(ts)
      Maps UTC timestamp from flat file to year-month-dayThh:mm:ss.sss format

get_leap_info(epoch)
      Returns leapseconds in datetime format, ticks since the given epoch, and their respective leap offsets

leap_table()
      Opens leap second list and returns a named numpy array of each leap second entry

tick_to_date(tick, epoch)
      Converts a tick to a datetime object

tick_to_iso_str(tick, epoch)
      Converts a tick to a timestamp in year-month-dayThh:mm:ss.sss format

tick_to_timestamp(tick, epoch)
      Converts a tick to a timestamp in 'year month_abrv day hh:mm:ss.sss' format

ticks_to_dates(ticks, epoch)
      Maps seconds relative to an epoch to datetime objects

ticks_to_iso(ticks, epoch)
      Converts an array of time ticks relative to the given epoch to a timestamp in year-month-dayThh:mm:ss.sss format

ticks_to_timestamps(ticks, epoch)
      Converts an array of time ticks relative to the given epoch to a timestamp in year month_abrv day hh:mm:ss.sss format