Numbers¶

netsa.data.format.num_fixed(value : num[, units : str, dec_fig=2, thousands_sep : str]) → str¶

Format value using a fixed number of figures after the decimal point. (e.g. “1234” is formatted as “1234.00”) If units is provided, this unit of measurement is included in the output. dec_fig specifies the number of figures after the decimal point.

If thousands_sep is given, it is used to separate each group of three digits to the left of the decimal point.

Examples:

>>> num_fixed(1234, 'm')
'1234.00m'
>>> num_fixed(1234, 'm', dec_fig=4)
'1234.0000m'
>>> num_fixed(1234.5678, 'm', dec_fig=0)
'1235m'
>>> num_fixed(123456789, dec_fig=3, thousands_sep=",")
'123,456,789.000'

netsa.data.format.num_exponent(value : num[, units : str, sig_fig=3]) → str¶

Format value using exponential notation. (i.e. “1234” becomes “1.23e+3” for three significant digits, or “1.234e+4” for four significant digits.) If units is provided, this unit of measurement is included in the output. sig_fig is the number of significant figures to display in the formatted result.

Examples:

>>> num_exponent(1234, 'm')
'1.23e+3m'
>>> num_exponent(1234, 'm', sig_fig=4)
'1.234e+3m'
>>> num_exponent(1234.5678, 'm', sig_fig=6)
'1.23457e+3m'
>>> num_exponent(123456789, sig_fig=2)
'1.2e+8'
>>> num_exponent(123456, sig_fig=6)
'1.23456e+5'

netsa.data.format.num_prefix(value : num[, units : str, sig_fig=3, use_binary=False, thousands_sep : str]) → str¶

Format value using SI prefix notation. (e.g. 1k is 1000) If units is provided, this unit of measurement is included in the output. sig_fig is the number of significant figures to display in the formatted result.

If use_binary is True, then SI binary prefixes are used (e.g. 1Ki is 1024). Note that there are no binary prefixes for negative exponents, so standard prefixes are always used for such cases.

For very large or very small values, exponential notation (e.g. “1e-30”) is used.

If thousands_sep is given, it is used to separate each group of three digits to the left of the decimal point.

Examples:

>>> num_prefix(1024, 'b')
'1.02kb'
>>> num_prefix(1024, 'b', use_binary=True)
'1.00Kib'
>>> num_prefix(12345, 'b', sig_fig=2)
'12kb'
>>> num_prefix(12345, 'b', sig_fig=7)
'12345.00b'
>>> num_prefix(12345678901234567890, 'b')
'12.3Eb'
>>> num_prefix(12345678901234567890, 'b', sig_fig=7)
'12345.68Pb'
>>> num_prefix(1234567890123456789012345, 's')
'1.23e+24s'
>>> num_prefix(0.001, 's')
'1.00ms'
>>> num_prefix(0.001, 's', use_binary=True)
'1.00ms'

Dates and Times¶

Dates and times may be formatted to a variety of precisions. The formatting functions support the following precisions, except where otherwise noted: DATETIME_YEAR, DATETIME_MONTH, DATETIME_DAY, DATETIME_HOUR, DATETIME_MINUTE, DATETIME_SECOND, DATETIME_MSEC, and DATETIME_USEC.

netsa.data.format.datetime_silk(value : datetime[, precision=DATETIME_SECOND]) → str¶

Format value as a SiLK format date and time (YYYY/MM/DDTHH:MM:SS.SSS). Implicitly coerces the time into UTC.

precision is the amount of precision that should be included in the output.

For a more general way to round times, see netsa.data.times.bin_datetime. See also datetime_silk_hour and datetime_silk_day for the most common ways to format incomplete dates in SiLK format.

Examples:

>>> t = netsa.data.times.make_datetime("2010-02-03T04:05:06.007")
>>> datetime_silk(t)
'2010/02/03T04:05:06'
>>> datetime_silk(t, precision=DATETIME_YEAR)
'2010'
>>> datetime_silk(t, precision=DATETIME_MONTH)
'2010/02'
>>> datetime_silk(t, precision=DATETIME_DAY)
'2010/02/03'
>>> datetime_silk(t, precision=DATETIME_HOUR)
'2010/02/03T04'
>>> datetime_silk(t, precision=DATETIME_MINUTE)
'2010/02/03T04:05'
>>> datetime_silk(t, precision=DATETIME_SECOND)
'2010/02/03T04:05:06'
>>> datetime_silk(t, precision=DATETIME_MSEC)
'2010/02/03T04:05:06.007'
>>> datetime_silk(t, precision=DATETIME_USEC)
'2010/02/03T04:05:06.007000'

netsa.data.format.datetime_silk_hour(value : datetime) → str¶

Format value as a SiLK format datetime to the precision of an hour (YYYY/MM/DDTHH). Implicitly coerces time into UTC. This is shorthand for datetime_silk(value, precision=DATETIME_HOUR).

Example:

>>> t = netsa.data.times.make_datetime("2010-02-03T04:05:06.007")
>>> datetime_silk_hour(t)
'2010/02/03T04'

netsa.data.format.datetime_silk_day(v : datetime) → str¶

Format value as a SiLK format datetime to the precision of a day (YYYY/MM/DD). Implicitly coerces time into UTC. This is shorthand for datetime_silk(value, precision=DATETIME_DAY).

Example:

>>> t = netsa.data.times.make_datetime("2010-02-03T04:05:06.007")
>>> datetime_silk_day(t)
'2010/02/03'

netsa.data.format.datetime_iso(value : datetime[, precision=DATETIME_SECOND]) → str¶

Format value as an ISO 8601 extended format date and time (YYYY/MM/DDTHH:MM:SS.SSSSSS[TZ]). Includes timezone offset unless the value has no timezone or the value’s timezone is UTC.

precision is the amount of precision that should be included in the output.

For a more general way to round times, see netsa.data.times.bin_datetime. See also datetime_silk_hour and datetime_silk_day for the most common ways to format incomplete dates in SiLK format.

Examples:

>>> t = netsa.data.times.make_datetime("2010-02-03T04:05:06.007008")
>>> datetime_iso(t)
'2010-02-03T04:05:06'
>>> datetime_iso(t, precision=DATETIME_YEAR)
'2010'
>>> datetime_iso(t, precision=DATETIME_MONTH)
'2010-02'
>>> datetime_iso(t, precision=DATETIME_DAY)
'2010-02-03'
>>> datetime_iso(t, precision=DATETIME_HOUR)
'2010-02-03T04'
>>> datetime_iso(t, precision=DATETIME_MINUTE)
'2010-02-03T04:05'
>>> datetime_iso(t, precision=DATETIME_SECOND)
'2010-02-03T04:05:06'
>>> datetime_iso(t, precision=DATETIME_MSEC)
'2010-02-03T04:05:06.007'
>>> datetime_iso(t, precision=DATETIME_USEC)
'2010-02-03T04:05:06.007008'
>>> t = netsa.data.times.make_datetime("2010-02-03T04:05:06.007008+09:10", utc_only=False)
>>> datetime_iso(t)
'2010-02-03T04:05:06+09:10'

netsa.data.format.datetime_iso_day(value : datetime) → str¶

Format value as an ISO 8601 extended format date to the precision of a day (YYYY-MM-DD[TZ]). Includes timezone offset unless the value has no timezone or the value’s timezone is UTC. This is shorthand for datetime_iso(value, precision=DATETIME_DAY).

Example:

>>> t = netsa.data.times.make_datetime("2010-02-03T04:05:06.007")
>>> datetime_iso_day(t)
'2010-02-03'
>>> t = netsa.data.times.make_datetime("2010-02-03T04:05:06.007+03:00", utc_only=False)
>>> datetime_iso_day(t)
'2010-02-03+03:00'

netsa.data.format.datetime_iso_basic(value : datetime[, precision=DATETIME_SECOND]) → str¶

Format value as an ISO 8601 basic (compact) format date and time (YYYYMMDDTHHMMSS.SSSSSS[TZ]). Includes timezone offset unless the value has no timezone or the value’s timezone is UTC.

precision is the amount of precision that should be included in the output. Note that in accordance with the ISO 8601 specification, this format does not support the DATETIME_MONTH precision, because YYYYMM and YYMMDD would be potentially ambiguous.

For a more general way to round times, see netsa.data.times.bin_datetime. See also datetime_silk_hour and datetime_silk_day for the most common ways to format incomplete dates in SiLK format.

Examples:

>>> t = netsa.data.times.make_datetime("2010-02-03T04:05:06.007008")
>>> datetime_iso_basic(t)
'20100203T040506'
>>> datetime_iso_basic(t, precision=DATETIME_YEAR)
'2010'
>>> datetime_iso_basic(t, precision=DATETIME_DAY)
'20100203'
>>> datetime_iso_basic(t, precision=DATETIME_HOUR)
'20100203T04'
>>> datetime_iso_basic(t, precision=DATETIME_MINUTE)
'20100203T0405'
>>> datetime_iso_basic(t, precision=DATETIME_SECOND)
'20100203T040506'
>>> datetime_iso_basic(t, precision=DATETIME_MSEC)
'20100203T040506.007'
>>> datetime_iso_basic(t, precision=DATETIME_USEC)
'20100203T040506.007008'
>>> t = netsa.data.times.make_datetime("2010-02-03T04:05:06.007008+09:10", utc_only=False)
>>> datetime_iso_basic(t)
'20100203T040506+0910'

netsa.data.format.timedelta_iso(value : timedelta) → str¶

Format a datetime.timedelta object as a str in ISO 8601 duration format, minus ‘year’ and ‘month’ designators (P[n]DT[n]H[n]M[n]S). Fractional seconds will represented using decimal notation in the seconds field.

Note that conversions between units are precise and do not take into account any calendrical context. In particular, a day is exactly 24*3600 seconds, just like datetime.timedelta uses.

If you apply the resulting timedelta to a datetime and the interval happens to include something like leap seconds adjust your expectations accordingly.

Since datetime.timedelta has no internal representation of months or years, these units are never included in the result.

Examples:

>>> t1 = netsa.data.times.make_datetime("2010-02-03T04:05:06.007008")
>>> t2 = netsa.data.times.make_datetime("2010-02-04T05:06:07.008009")
>>> t3 = netsa.data.times.make_datetime("2010-02-03T04:06:06.008009")
>>> d1 = t2 - t1
>>> d2 = t3 - t1
>>> timedelta_iso(d1)
>>> 'P1DT1H1M1.001001S'
>>> timedelta_iso(d2)
>>> 'PT1M0.001001S'