netsa.data.times — Time and Date Manipulation¶
- netsa.data.times.make_datetime(v : num or str or datetime or mxDateTime[, utc_only=True]) → datetime¶
Produces a datetime.datetime object from a number (seconds from UNIX epoch), a string (in ISO format, SiLK format, or old SiLK format), or a datetime.datetime object. If utc_only is True, coerces the result to be in the UTC time zone.
If the mxDateTime library is installed, this function also accepts mxDateTime objects.
- netsa.data.times.bin_datetime(dt : timedelta, t : datetime[, z=UNIX_EPOCH : datetime]) → datetime¶
Returns a new datetime.datetime object which is the floor of the datetime.datetime t in a dt-sized bin. For example:
bin_datetime(timedelta(minutes=5), t)
will return the beginning of a five-minute bin containing the time t. If you have very specific requirements, you can replace the origin point for binning (z) with a time of your choice. By default, the UNIX epoch is used, which is appropriate for most uses.
- netsa.data.times.make_timedelta(v : timedelta or str) → timedelta¶
Produces a datetime.timedelta object from a string (in ISO 8601 duration format) or a datetime.timedelta object.
Since datetime.timedelta objects do not internally support units larger than ‘days’, ISO 8601 strings containing month or year designations are discouraged. If these units are encountered in the string, however, they converted to days using a precise formula. This is an exact conversion that does not take into account any calendrical context. If you apply the result to a datetime, and the interval happens to include leapseconds, or if you expect to land on the same day of the month while adding ‘months’ or ‘years’, adjust your expectations accordingly.
Example of ISO 8601: ‘P1DT1H1M1S’
This translates as a period of ‘1 day’ with time offset of ‘1 hour, 1 minute, and 1 second’. Fields are optional, the ‘P’ is required, as is the ‘T’ if using any units smaller than a day. A zero-valued timedelta can be represented as ‘P0D’.
- netsa.data.times.divmod_timedelta(n : timedelta, d : timedelta) → int, timedelta¶
Given two datetime.timedelta objects, return the number of times the second one (denominator) fits into the first one (numerator), along with any remainder expressed as another timedelta.
Date Snappers¶
- class netsa.data.times.DateSnapper(size : timedelta[, epoch=UNIX_EPOCH : datetime])¶
Class for date bin manipulations
- date_aligned(date) → bool¶
Tests whether or not the provided date is the beginning datetime.datetime for the containing time bin.
See make_datetime for more detail on acceptable formats for date descriptors.
- date_bin(date) → datetime¶
Returns a datetime.datetime object representing the beginning of the date bin containing the provided date (‘snapping’ the date into place)
See make_datetime for more detail on acceptable formats for date descriptors.
- date_bin_end(date) → datetime¶
Returns a datetime.datetime object representing the last date of the date bin which contains the provided date.
See make_datetime for more detail on acceptable formats for date descriptors.
- date_binner(dates : date seq) → seq¶
Given a list of datetimes, returns an iterator which produces tuples containing two datetime objects for each provided datetime. The first value of the tuple is the beginning of the date bin containing the datetime in question and the second value is the original datetime.
See make_datetime for more detail on acceptable formats for datetime descriptors.
- date_clumper(date_ranges : seq) → datetime seq¶
Given a list of date ranges, return a list of date bins that intersect the union of the given date ranges. Each date range in the provided list can be a single datetime descriptor or a tuple representing a beginning and end datetime for the range.
See make_datetime for more detail on acceptable formats for date descriptors.
- date_sequencer(date_list : date seq) → seq¶
Given a list of datetimes, returns an iterator which produces tuples containing two datetime objects. The first value of the tuple is the begining of the date bin and the second value is the original datetime. Both bins and datetimes will be repeated where necessary to fill in gaps not present in the original list of datetimes.
If, for example, the span between each successive datetime in the provided list is smaller than the defined bin size, the same bin will be returned for each datetime residing in that bin. (An example of this would be a bin size of 7 days and a list of daily dates – the same bin would be returned for each week of dates within that bin).
If, on the other hand, the span between successive datetimes in the provided list is larger than the defined bin size, each provided date will be repeatly returned with each bin that exists between the provided datetimes. (An example of this would be a bin size of 7 days and a list of monthly dates – each monthly date would be succesively returned with the 4 (or so) bins touched by that month)
See make_datetime for more detail on acceptable formats for date descriptors.
- next_date_bin(date) → datetime¶
Returns a datetime.datetime object representing the beginning of the date bin following the date bin in which the given date resides.
See make_datetime for more detail on acceptable formats for date descriptors.
- prior_date_bin(date) → datetime¶
Returns a datetime.datetime object representing the beginning of the date bin prior to the date bin in which the given date resides.
See make_datetime for more detail on acceptable formats for date descriptors.
- today_bin() → datetime¶
Returns a datetime.datetime object representing the beginning of the date bin containing the current date.
- netsa.data.times.dow_day_snapper(size : int[, dow=0]) → DateSnapper¶
Given an integer size in days and an integer day-of-the-week, returns a :class:DateSnapper object anchored on the first occurring instance of that DOW after the given epoch, which defaults to the UNIX epoch. Monday is the 0th DOW. DOW values are modulo 7, so the 7th DOW would also represent Monday.
