`rsudp.helpers` (helper functions)

These are some helper functions in rsudp.

rsudp.helpers.conn_stats(TESTING=False)

Print some stats about the connection.

Example:

>>> conn_stats()
2020-03-25 01:35:04 [conn_stats] Initialization stats:
2020-03-25 01:35:04 [conn_stats]                 Port: 18069
2020-03-25 01:35:04 [conn_stats]   Sending IP address: 192.168.0.4
2020-03-25 01:35:04 [conn_stats]     Set station name: R24FA
2020-03-25 01:35:04 [conn_stats]   Number of channels: 4
2020-03-25 01:35:04 [conn_stats]   Transmission freq.: 250 ms/packet
2020-03-25 01:35:04 [conn_stats]    Transmission rate: 4 packets/sec
2020-03-25 01:35:04 [conn_stats]   Samples per second: 100 sps
2020-03-25 01:35:04 [conn_stats]            Inventory: AM.R24FA (Raspberry Shake Citizen Science Station)

Parameters:: TESTING (bool) – if True, text is printed to the console in yellow. if not, in white.

rsudp.helpers.deconv_acc_inst(self, trace, output)

A helper function for rsudp.raspberryshake.deconvolve() for acceleration channels.

Parameters:

self (self) – The self object of the sub-consumer class calling this function.
trace (obspy.core.trace.Trace) – the trace object instance to deconvolve

rsudp.helpers.deconv_rbm_inst(self, trace, output)

A helper function for rsudp.raspberryshake.deconvolve() for Raspberry Boom pressure transducer channels.

Note

The Raspberry Boom pressure transducer does not currently have a deconvolution function. The Raspberry Shake team is working on a calibration for the Boom, but until then Boom units are given in counts.

Parameters:

self (self) – The self object of the sub-consumer class calling this function.
trace (obspy.core.trace.Trace) – the trace object instance to deconvolve

rsudp.helpers.deconv_vel_inst(self, trace, output)

A helper function for rsudp.raspberryshake.deconvolve() for velocity channels.

Parameters:

self (self) – The self object of the sub-consumer class calling this function.
trace (obspy.core.trace.Trace) – the trace object instance to deconvolve

rsudp.helpers.deconvolve(self)

A central helper function for sub-consumers (i.e. rsudp.c_plot.Plot or rsudp.c_alert.Alert) that need to deconvolve their raw data to metric units. Consumers with obspy.core.stream.Stream objects in self.stream can use this to deconvolve data if this library’s rsudp.raspberryshake.inv variable contains a valid obspy.core.inventory.inventory.Inventory object.

Parameters:: self (self) – The self object of the sub-consumer class calling this function. Must contain self.stream as a obspy.core.stream.Stream object.

rsudp.helpers.default_settings(output_dir='/home/energyneo0/rsudp', verbose=True)

Returns a formatted json string of default settings.

Parameters:

output_dir (str) – the user’s specified output location. defaults to ~/rsudp.
verbose (bool) – if True, displays some information as the string is created.

Returns:

default settings string in formatted json

Return type:

str

rsudp.helpers.dump_default(settings_loc, default_settings)

Dumps a default settings file to a specified location.

Parameters:

settings_loc (str) – The location to create the new settings JSON.
default_settings (str) – The default settings to dump to file.

rsudp.helpers.fsec(ti)

New in version 0.4.3.

The Raspberry Shake records at hundredths-of-a-second precision. In order to report time at this precision, we need to do some time-fu.

This function rounds the microsecond fraction of a obspy.core.utcdatetime.UTCDateTime depending on its precision, so that it accurately reflects the Raspberry Shake’s event measurement precision.

This is necessary because datetime objects in Python are strange and confusing, and strftime doesn’t support fractional returns, only the full integer microsecond field which is an integer right-padded with zeroes. This function uses the precision of a datetime object.

For example:

>>> from obspy import UTCDateTime
>>> ti = UTCDateTime(2020, 1, 1, 0, 0, 0, 599000, precision=3)
>>> fsec(ti)
UTCDateTime(2020, 1, 1, 0, 0, 0, 600000)

Parameters:: ti (obspy.core.utcdatetime.UTCDateTime) – time object to convert microseconds for
Returns:: the hundredth-of-a-second rounded version of the time object passed (precision is 0.01 second)
Return type:: obspy.core.utcdatetime.UTCDateTime

rsudp.helpers.get_msg_path(msg)

This function gets the path from IMGPATH messages as a string.

For example:

>>> from obspy import UTCDateTime
>>> ti = UTCDateTime(2020, 1, 1, 0, 0, 0, 599000, precision=3)
>>> path = '/home/pi/rsudp/screenshots/test.png'
>>> msg = msg_imgpath(ti, path)
>>> msg
b'IMGPATH 2020-01-01T00:00:00.599Z /home/pi/rsudp/screenshots/test.png'
>>> get_msg_path(msg)
'/home/pi/rsudp/screenshots/test.png'

Parameters:: msg (bytes) – the bytes-formatted queue message to decode
Return type:: str
Returns:: the path embedded in the message

rsudp.helpers.get_msg_time(msg)

This function gets the time from ALARM, RESET, and IMGPATH messages as a UTCDateTime object.

For example:

>>> from obspy import UTCDateTime
>>> ti = UTCDateTime(2020, 1, 1, 0, 0, 0, 599000, precision=3)
>>> path = '/home/pi/rsudp/screenshots/test.png'
>>> msg = msg_imgpath(ti, path)
>>> msg
b'IMGPATH 2020-01-01T00:00:00.599Z /home/pi/rsudp/screenshots/test.png'
>>> get_msg_time(msg)
UTCDateTime(2020, 1, 1, 0, 0, 0, 599000)

Parameters:: msg (bytes) – the bytes-formatted queue message to decode
Return type:: obspy.core.utcdatetime.UTCDateTime
Returns:: the time embedded in the message

rsudp.helpers.lesser_multiple(x, base=10)

New in version 1.0.3.

This function calculates the nearest multiple of the base number base for the number x passed to it, as long as the result is less than x.

This is useful for rsudp.packetize() when figuring out where to cut off samples when trying to fit them into packets.

rsudp.helpers.msg_alarm(event_time)

This function constructs the ALARM message as a bytes object. Currently this is only used by rsudp.p_producer.Producer to construct alarm queue messages.

For example:

>>> from obspy import UTCDateTime
>>> ti = UTCDateTime(2020, 1, 1, 0, 0, 0, 599000, precision=3)
>>> msg_alarm(ti)
b'ALARM 2020-01-01T00:00:00.599Z'

Parameters:: event_time (obspy.core.utcdatetime.UTCDateTime) – the datetime object to serialize and convert to bytes
Return type:: bytes
Returns:: the ALARM message, ready to be put on the queue

rsudp.helpers.msg_imgpath(event_time, figname)

This function constructs the IMGPATH message as a bytes object. Currently this is only used by rsudp.c_plot.Plot to construct queue messages containing timestamp and saved image path.

For example:

>>> from obspy import UTCDateTime
>>> ti = UTCDateTime(2020, 1, 1, 0, 0, 0, 599000, precision=3)
>>> path = '/home/pi/rsudp/screenshots/test.png'
>>> msg_imgpath(ti, path)
b'IMGPATH 2020-01-01T00:00:00.599Z /home/pi/rsudp/screenshots/test.png'

Parameters:

event_time (obspy.core.utcdatetime.UTCDateTime) – the datetime object to serialize and convert to bytes
figname (str) – the figure path as a string

Return type:

bytes

Returns:

the IMGPATH message, ready to be put on the queue

rsudp.helpers.msg_reset(reset_time)

This function constructs the RESET message as a bytes object. Currently this is only used by rsudp.p_producer.Producer to construct reset queue messages.

For example:

>>> from obspy import UTCDateTime
>>> ti = UTCDateTime(2020, 1, 1, 0, 0, 0, 599000, precision=3)
>>> msg_reset(ti)
b'RESET 2020-01-01T00:00:00.599Z'

Parameters:: reset_time (obspy.core.utcdatetime.UTCDateTime) – the datetime object to serialize and convert to bytes
Return type:: bytes
Returns:: the RESET message, ready to be put on the queue

rsudp.helpers.msg_term()

This function constructs the simple TERM message as a bytes object.

>>> msg_term()
b'TERM'

Return type:: bytes
Returns:: the TERM message

rsudp.helpers.read_settings(loc)

Reads settings from a specific location.

Parameters:: loc (str) – location on disk to read json settings file from
Returns:: settings dictionary read from JSON, or None
Return type:: dict or NoneType

rsudp.helpers.resolve_extra_text(extra_text, max_len, sender='helpers')

New in version 1.0.3.

A central helper function for the rsudp.c_telegram.Tweeter and rsudp.c_telegram.Telegrammer classes that checks whether the "extra_text" parameter (in the settings file) is of appropriate length. This is done to avoid errors when posting alerts. The function will truncate longer messages.

Parameters:

extra_text (str) – String of additional characters to post as part of the alert message (longer messages will be truncated).
max_len (str) – Upper limit of characters accepted in message (280 for Twitter, 4096 for Telegram).
sender (str) – String identifying the origin of the use of this function (self.sender in the source function).

Return type:

str

Returns:

the message string to be incorporated

rsudp.helpers.set_channels(self, cha)

This function sets the channels available for plotting. Allowed units are as follows:

["SHZ", "EHZ", "EHN", "EHE"] - velocity channels
["ENZ", "ENN", "ENE"] - acceleration channels
["HDF"] - pressure transducer channel
["all"] - all available channels

So for example, if you wanted to display the two vertical channels of a Shake 4D, (geophone and vertical accelerometer) you could specify:

["EHZ", "ENZ"]

You can also specify partial channel names. So for example, the following will display at least one channel from any Raspberry Shake instrument:

["HZ", "HDF"]

Or if you wanted to display only vertical channels from a RS4D, you could specify

["Z"]

which would match both "EHZ" and "ENZ".

Parameters:

self (self) – self object of the class calling this function
cha (list or str) – the channel or list of channels to plot

Back to top ↑

rsudp.helpers (helper functions)

`rsudp.helpers` (helper functions)