Skip to content

Utilities

data2rad(data, k=360)

Convert data measured on a circular scale to corresponding angular directions.

\[ \alpha = \frac{2\pi \times \mathrm{data}}{k} \]

Parameters:

Name Type Description Default
data ndarray or float

Data measured on a circular scale.

 required
k float or int

Number of intervals in the full cycle. Default is 360.

 360

Returns:

Name Type Description
angle ndarray or float

Angular directions in radian.
Source code in pycircstat2/utils.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def data2rad(
    data: Union[np.ndarray, float, int],
    k: Union[float, int] = 360,  # number of intervals in the full cycle
) -> Union[np.ndarray, float]:  # eq(26.1), zar 2010
    r"""Convert data measured on a circular scale to 
    corresponding angular directions.

    $$ \alpha = \frac{2\pi \times \mathrm{data}}{k} $$

    Parameters
    ----------
    data : np.ndarray or float
        Data measured on a circular scale.
    k : float or int
        Number of intervals in the full cycle. Default is 360.

    Returns
    -------
    angle: np.ndarray or float
        Angular directions in radian.
    """
    return 2 * np.pi * data / k

time2float(x, sep=':')

Convert an array of strings in time (hh:mm) to an array of floats.

Source code in pycircstat2/utils.py 
39
40
41
42
43
44
45
46
47
48
def time2float(x: Union[np.ndarray, list, str], sep: str = ":") -> np.ndarray:
    """Convert an array of strings in time (hh:mm) to an array of floats."""

    def _t2f(x: str, sep: str):
        """Convert string of time to float. E.g. 12:45 -> 12.75"""
        hr, min = x.split(sep)
        return float(hr) + float(min) / 60

    t2f = np.vectorize(_t2f)
    return t2f(x, sep)

angular_distance(a, b)

Angular distance between two angles.

Parameters:

Name Type Description Default
a Union[ndarray, list, float]

angle(s).

 required
b float

target angle.

 required

Returns:

Name Type Description
e ndarray

angular distance
Reference

P642, Section 27.2, Zar, 2010

Source code in pycircstat2/utils.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def angular_distance(
    a: Union[np.ndarray, list, float], b: float
) -> np.ndarray:
    """Angular distance between two angles.

    Parameters
    ----------
    a: np.ndarray or float
        angle(s).

    b: float
        target angle.

    Returns
    -------
    e: np.ndarray
        angular distance

    Reference
    ---------
    P642, Section 27.2, Zar, 2010
    """

    a = np.array(a) if type(a) is list else a

    c = angrange(a - b)
    d = 2 * np.pi - c
    e = np.min([c, d], axis=0)

    return e

is_within_circular_range(value, lb, ub)

Check if a value lies within the circular range [lb, ub].

Parameters:

Name Type Description Default
value float

The value to check.

 required
lb float

The lower bound of the range.

 required
ub float

The upper bound of the range.

 required

Returns:

Type Description
bool

True if the value is within the circular range, False otherwise.
Source code in pycircstat2/utils.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def is_within_circular_range(value, lb, ub):
    """
    Check if a value lies within the circular range [lb, ub].

    Parameters
    ----------
    value : float
        The value to check.
    lb : float
        The lower bound of the range.
    ub : float
        The upper bound of the range.

    Returns
    -------
    bool
        True if the value is within the circular range, False otherwise.
    """
    value = np.mod(value, 2 * np.pi)
    lb = np.mod(lb, 2 * np.pi)
    ub = np.mod(ub, 2 * np.pi)

    if lb <= ub:
        # Standard range
        return lb <= value <= ub
    else:
        # Wrapping range
        return value >= lb or value <= ub