Move frequencies functions to cython (#17746)

Author: jbrockmendel

pandas/_libs/tslibs/frequencies.pxd

@@ -1,4 +1,10 @@
 # -*- coding: utf-8 -*-
 # cython: profile=False
 
+cpdef object get_rule_month(object source, object default=*)
+
 cpdef get_freq_code(freqstr)
+cpdef object get_freq(object freq)
+cpdef str get_base_alias(freqstr)
+cpdef int get_to_timestamp_base(int base)
+cpdef str get_freq_str(base, mult=*)

pandas/_libs/tslibs/frequencies.pyx

@@ -6,9 +6,12 @@ cimport cython
 
 import numpy as np
 cimport numpy as np
+from numpy cimport int64_t
 np.import_array()
 
-from util cimport is_integer_object
+from util cimport is_integer_object, is_string_object
+
+from ccalendar import MONTH_NUMBERS
 
 # ----------------------------------------------------------------------
 # Constants
@@ -23,6 +26,22 @@ _INVALID_FREQ_ERROR = "Invalid frequency: {0}"
 # ---------------------------------------------------------------------
 # Period codes
 
+
+class FreqGroup(object):
+    FR_ANN = 1000
+    FR_QTR = 2000
+    FR_MTH = 3000
+    FR_WK = 4000
+    FR_BUS = 5000
+    FR_DAY = 6000
+    FR_HR = 7000
+    FR_MIN = 8000
+    FR_SEC = 9000
+    FR_MS = 10000
+    FR_US = 11000
+    FR_NS = 12000
+
+
 # period frequency constants corresponding to scikits timeseries
 # originals
 _period_code_map = {
@@ -125,8 +144,8 @@ cpdef get_freq_code(freqstr):
     -------
     return : tuple of base frequency code and stride (mult)
 
-    Example
-    -------
+    Examples
+    --------
     >>> get_freq_code('3D')
     (6000, 3)
 
@@ -203,3 +222,292 @@ cpdef _period_str_to_code(freqstr):
         return _period_code_map[freqstr]
     except KeyError:
         raise ValueError(_INVALID_FREQ_ERROR.format(freqstr))
+
+
+cpdef str get_freq_str(base, mult=1):
+    """
+    Return the summary string associated with this offset code, possibly
+    adjusted by a multiplier.
+
+    Parameters
+    ----------
+    base : int (member of FreqGroup)
+
+    Returns
+    -------
+    freq_str : str
+
+    Examples
+    --------
+    >>> get_freq_str(1000)
+    'A-DEC'
+
+    >>> get_freq_str(2000, 2)
+    '2Q-DEC'
+
+    >>> get_freq_str("foo")
+    """
+    code = _reverse_period_code_map.get(base)
+    if mult == 1:
+        return code
+    return str(mult) + code
+
+
+cpdef str get_base_alias(freqstr):
+    """
+    Returns the base frequency alias, e.g., '5D' -> 'D'
+
+    Parameters
+    ----------
+    freqstr : str
+
+    Returns
+    -------
+    base_alias : str
+    """
+    return _base_and_stride(freqstr)[0]
+
+
+cpdef int get_to_timestamp_base(int base):
+    """
+    Return frequency code group used for base of to_timestamp against
+    frequency code.
+
+    Parameters
+    ----------
+    base : int (member of FreqGroup)
+
+    Returns
+    -------
+    base : int
+
+    Examples
+    --------
+    # Return day freq code against longer freq than day
+    >>> get_to_timestamp_base(get_freq_code('D')[0])
+    6000
+    >>> get_to_timestamp_base(get_freq_code('W')[0])
+    6000
+    >>> get_to_timestamp_base(get_freq_code('M')[0])
+    6000
+
+    # Return second freq code against hour between second
+    >>> get_to_timestamp_base(get_freq_code('H')[0])
+    9000
+    >>> get_to_timestamp_base(get_freq_code('S')[0])
+    9000
+    """
+    if base < FreqGroup.FR_BUS:
+        return FreqGroup.FR_DAY
+    elif FreqGroup.FR_HR <= base <= FreqGroup.FR_SEC:
+        return FreqGroup.FR_SEC
+    return base
+
+
+cpdef object get_freq(object freq):
+    """
+    Return frequency code of given frequency str.
+    If input is not string, return input as it is.
+
+    Examples
+    --------
+    >>> get_freq('A')
+    1000
+
+    >>> get_freq('3A')
+    1000
+    """
+    if is_string_object(freq):
+        base, mult = get_freq_code(freq)
+        freq = base
+    return freq
+
+
+# ----------------------------------------------------------------------
+# Frequency comparison
+
+cpdef bint is_subperiod(source, target):
+    """
+    Returns True if downsampling is possible between source and target
+    frequencies
+
+    Parameters
+    ----------
+    source : string or DateOffset
+        Frequency converting from
+    target : string or DateOffset
+        Frequency converting to
+
+    Returns
+    -------
+    is_subperiod : boolean
+    """
+
+    if target is None or source is None:
+        return False
+    source = _maybe_coerce_freq(source)
+    target = _maybe_coerce_freq(target)
+
+    if _is_annual(target):
+        if _is_quarterly(source):
+            return _quarter_months_conform(get_rule_month(source),
+                                           get_rule_month(target))
+        return source in {'D', 'C', 'B', 'M', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif _is_quarterly(target):
+        return source in {'D', 'C', 'B', 'M', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif _is_monthly(target):
+        return source in {'D', 'C', 'B', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif _is_weekly(target):
+        return source in {target, 'D', 'C', 'B', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif target == 'B':
+        return source in {'B', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif target == 'C':
+        return source in {'C', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif target == 'D':
+        return source in {'D', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif target == 'H':
+        return source in {'H', 'T', 'S', 'L', 'U', 'N'}
+    elif target == 'T':
+        return source in {'T', 'S', 'L', 'U', 'N'}
+    elif target == 'S':
+        return source in {'S', 'L', 'U', 'N'}
+    elif target == 'L':
+        return source in {'L', 'U', 'N'}
+    elif target == 'U':
+        return source in {'U', 'N'}
+    elif target == 'N':
+        return source in {'N'}
+
+
+cpdef bint is_superperiod(source, target):
+    """
+    Returns True if upsampling is possible between source and target
+    frequencies
+
+    Parameters
+    ----------
+    source : string
+        Frequency converting from
+    target : string
+        Frequency converting to
+
+    Returns
+    -------
+    is_superperiod : boolean
+    """
+    if target is None or source is None:
+        return False
+    source = _maybe_coerce_freq(source)
+    target = _maybe_coerce_freq(target)
+
+    if _is_annual(source):
+        if _is_annual(target):
+            return get_rule_month(source) == get_rule_month(target)
+
+        if _is_quarterly(target):
+            smonth = get_rule_month(source)
+            tmonth = get_rule_month(target)
+            return _quarter_months_conform(smonth, tmonth)
+        return target in {'D', 'C', 'B', 'M', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif _is_quarterly(source):
+        return target in {'D', 'C', 'B', 'M', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif _is_monthly(source):
+        return target in {'D', 'C', 'B', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif _is_weekly(source):
+        return target in {source, 'D', 'C', 'B', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif source == 'B':
+        return target in {'D', 'C', 'B', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif source == 'C':
+        return target in {'D', 'C', 'B', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif source == 'D':
+        return target in {'D', 'C', 'B', 'H', 'T', 'S', 'L', 'U', 'N'}
+    elif source == 'H':
+        return target in {'H', 'T', 'S', 'L', 'U', 'N'}
+    elif source == 'T':
+        return target in {'T', 'S', 'L', 'U', 'N'}
+    elif source == 'S':
+        return target in {'S', 'L', 'U', 'N'}
+    elif source == 'L':
+        return target in {'L', 'U', 'N'}
+    elif source == 'U':
+        return target in {'U', 'N'}
+    elif source == 'N':
+        return target in {'N'}
+
+
+cdef str _maybe_coerce_freq(code):
+    """ we might need to coerce a code to a rule_code
+    and uppercase it
+
+    Parameters
+    ----------
+    source : string or DateOffset
+        Frequency converting from
+
+    Returns
+    -------
+    code : string
+    """
+    assert code is not None
+    if getattr(code, '_typ', None) == 'dateoffset':
+        # i.e. isinstance(code, ABCDateOffset):
+        code = code.rule_code
+    return code.upper()
+
+
+cdef bint _quarter_months_conform(str source, str target):
+    snum = MONTH_NUMBERS[source]
+    tnum = MONTH_NUMBERS[target]
+    return snum % 3 == tnum % 3
+
+
+cdef bint _is_annual(str rule):
+    rule = rule.upper()
+    return rule == 'A' or rule.startswith('A-')
+
+
+cdef bint _is_quarterly(str rule):
+    rule = rule.upper()
+    return rule == 'Q' or rule.startswith('Q-') or rule.startswith('BQ')
+
+
+cdef bint _is_monthly(str rule):
+    rule = rule.upper()
+    return rule == 'M' or rule == 'BM'
+
+
+cdef bint _is_weekly(str rule):
+    rule = rule.upper()
+    return rule == 'W' or rule.startswith('W-')
+
+
+# ----------------------------------------------------------------------
+
+cpdef object get_rule_month(object source, object default='DEC'):
+    """
+    Return starting month of given freq, default is December.
+
+    Parameters
+    ----------
+    source : object
+    default : object (default "DEC")
+
+    Returns
+    -------
+    rule_month: object (usually string)
+
+    Examples
+    --------
+    >>> get_rule_month('D')
+    'DEC'
+
+    >>> get_rule_month('A-JAN')
+    'JAN'
+    """
+    if hasattr(source, 'freqstr'):
+        source = source.freqstr
+    source = source.upper()
+    if '-' not in source:
+        return default
+    else:
+        return source.split('-')[1]