obspy.signal.spectral_estimation.PPSD.calculate_histogram¶

PPSD.calculate_histogram(starttime=None, endtime=None, time_of_weekday=None, year=None, month=None, isoweek=None, callback=None)[source]¶

Calculate and set current 2D histogram stack, optionally with start- and endtime and time of day restrictions.

Note

All restrictions to the stack are evaluated as a logical AND, i.e. only individual psd pieces are included in the stack that match all of the specified restrictions (e.g. isoweek=40, month=2 can never match any data).

Note

All time restrictions are specified in UTC, so actual time in local time zone might not be the same across start/end date of daylight saving time periods.

Note

Time restrictions only check the starttime of the individual psd pieces.

Parameters:

Parameters:	starttime (`UTCDateTime`) If set, data before the specified time is excluded from the returned stack. endtime (`UTCDateTime`) If set, data after the specified time is excluded from the returned stack. time_of_weekday (list of (int, float, float) 3-tuples) If set, restricts the data that is included in the stack by time of day and weekday. Monday is 1, Sunday is 7, -1 for any day of week. For example, using time_of_weekday=[(-1, 0, 2), (-1, 22, 24)] only individual spectra that have a starttime in between 10pm and 2am are used in the stack for all days of week, using time_of_weekday=[(5, 22, 24), (6, 0, 2), (6, 22, 24), (7, 0, 2)] only spectra with a starttime in between Friday 10pm to Saturdays 2am and Saturday 10pm to Sunday 2am are used. Note that time of day is specified in UTC (time of day might have to be adapted to daylight saving time). Also note that this setting filters only by starttime of the used psd time slice, so the length of individual slices (set at initialization: `PPSD(..., ppsd_length=XXX, ...)` in seconds) has to be taken into consideration (e.g. with a ppsd_length of one hour and a time_of_weekday restriction to 10pm-2am actually includes data from 10pm-3am). year (list of int) If set, restricts the data that is included in the stack by year. For example, using year=[2015] only individual spectra from year 2015 are used in the stack, using year=[2013, 2015] only spectra from exactly year 2013 or exactly year 2015 are used. month (list of int) If set, restricts the data that is included in the stack by month of year. For example, using month=[2] only individual spectra from February are used in the stack, using month=[4, 7] only spectra from exactly April or exactly July are used. isoweek (list of int) If set, restricts the data that is included in the stack by ISO week number of year. For example, using isoweek=[2] only individual spectra from 2nd ISO week of any year are used in the stack, using isoweek=[4, 7] only spectra from exactly 4th ISO week or exactly 7th ISO week are used. callback (func) Custom user defined callback function that can be used for more complex scenarios to specify whether an individual psd piece should be included in the stack or not. The function will be passed an array with the starttimes of all psd pieces (as a POSIX timestamp that can be used as a single argument to initialize a `UTCDateTime` object) and should return a boolean array specifying which psd pieces should be included in the stack (True) and which should be excluded (False). Note that even when callback returns True the psd piece will be excluded if it does not match all other criteria (e.g. starttime).
Return type:	None

starttime (UTCDateTime) If set, data before the specified time is excluded from the returned stack.
endtime (UTCDateTime) If set, data after the specified time is excluded from the returned stack.
time_of_weekday (list of (int, float, float) 3-tuples) If set, restricts the data that is included in the stack by time of day and weekday. Monday is 1, Sunday is 7, -1 for any day of week. For example, using time_of_weekday=[(-1, 0, 2), (-1, 22, 24)] only individual spectra that have a starttime in between 10pm and 2am are used in the stack for all days of week, using time_of_weekday=[(5, 22, 24), (6, 0, 2), (6, 22, 24), (7, 0, 2)] only spectra with a starttime in between Friday 10pm to Saturdays 2am and Saturday 10pm to Sunday 2am are used. Note that time of day is specified in UTC (time of day might have to be adapted to daylight saving time). Also note that this setting filters only by starttime of the used psd time slice, so the length of individual slices (set at initialization: PPSD(..., ppsd_length=XXX, ...) in seconds) has to be taken into consideration (e.g. with a ppsd_length of one hour and a time_of_weekday restriction to 10pm-2am actually includes data from 10pm-3am).
year (list of int) If set, restricts the data that is included in the stack by year. For example, using year=[2015] only individual spectra from year 2015 are used in the stack, using year=[2013, 2015] only spectra from exactly year 2013 or exactly year 2015 are used.
month (list of int) If set, restricts the data that is included in the stack by month of year. For example, using month=[2] only individual spectra from February are used in the stack, using month=[4, 7] only spectra from exactly April or exactly July are used.
isoweek (list of int) If set, restricts the data that is included in the stack by ISO week number of year. For example, using isoweek=[2] only individual spectra from 2nd ISO week of any year are used in the stack, using isoweek=[4, 7] only spectra from exactly 4th ISO week or exactly 7th ISO week are used.
callback (func) Custom user defined callback function that can be used for more complex scenarios to specify whether an individual psd piece should be included in the stack or not. The function will be passed an array with the starttimes of all psd pieces (as a POSIX timestamp that can be used as a single argument to initialize a UTCDateTime object) and should return a boolean array specifying which psd pieces should be included in the stack (True) and which should be excluded (False). Note that even when callback returns True the psd piece will be excluded if it does not match all other criteria (e.g. starttime).

Return type:

None