In [1]:

import numpy as np

PyCircStat2 Utility Functions¶

pycircstat2 includes a handful of useful utility functions:

load_data
time2float
data2rad
angrange

Load Data¶

All data sets from Fisher (1993) and Zar (2010; Ch26 and 27), some from Pewsey, et al. (2014) and Mardia (1972) are included in pycircstat2, which can be loaded by load_data in pycircstat2.utils. Meta data of the data set can be printed if print_meta = True, or return along with the data set if return_meta = True.

In [2]:

from pycircstat2.utils import load_data

data, meta = load_data(name='B1', source='fisher', print_meta=True, return_meta=True)

{
    "Title": "B.1 Arrival times at an intensive care unit",
    "Description": "Arrival times on a 24-hour clock of 254 patients at an intnsive care unit, over a period of about 12 months",
    "Type": "Vectors",
    "Source": "Cox & Lewis (1966, pp. 254-5)",
    "Examples": "2.1, 2.3, 2.4, 2.5, 2.6, 2.8, 2.10",
    "Columns": {
        "time": {
            "name": "time",
            "type": "vectors"
        }
    }
}

In [3]:

meta

Out[3]:

{'Title': 'B.1 Arrival times at an intensive care unit',
 'Description': 'Arrival times on a 24-hour clock of 254 patients at an intnsive care unit, over a period of about 12 months',
 'Type': 'Vectors',
 'Source': 'Cox & Lewis (1966, pp. 254-5)',
 'Examples': '2.1, 2.3, 2.4, 2.5, 2.6, 2.8, 2.10',
 'Columns': {'time': {'name': 'time', 'type': 'vectors'}}}

In [4]:

data[:3]

Out[4]:

	time
1	11:00
2	17:00
3	23:15

Converting time string into float¶

Some of the typical circular data are encoded in string in time units (e.g. 12:45 h), we need to convert them into float for further computation.

In [5]:

from pycircstat2.utils import time2float
data_float = time2float(data['time'].values)
data_float[:5]

Out[5]:

array([11.  , 17.  , 23.25, 10.  , 12.  ])

Converting data onto a circular scale (in radian) and vice versa¶

data2rad(data, k) convert data into radian and rad2data(rad, k) convert radian back to the original unit.

In [6]:

from pycircstat2.utils import data2rad, rad2data

In [7]:

data_rad = data2rad(data=data_float, k=24) # k is the time units in the full cycle.
data_rad[:5]                               # e.g. for hours, k=24; for years, k=365.

Out[7]:

array([2.87979327, 4.45058959, 6.08683577, 2.61799388, 3.14159265])

In [8]:

data_hour = rad2data(rad=data_rad, k=24)
data_hour[:5]

Out[8]:

array([11.  , 17.  , 23.25, 10.  , 12.  ])

In [9]:

np.allclose(data_float, data_hour)

Out[9]:

True

Range¶

pycircstat2 assumed all data fall onto a unit circle, meaning that all data points are within the range of [0, 2π). In the Circular class, all input data will be converted into this range by calling angrange(rad) in pycircstat2.utils.

In [10]:

from pycircstat2.utils import angrange
angrange(np.array([0., 3., 6., np.pi * 2, 7.]))

Out[10]:

array([0.        , 3.        , 6.        , 0.        , 0.71681469])

In [11]:

%load_ext watermark
%watermark --time --date --timezone --updated --python --iversions --watermark -p pycircstat2

Last updated: 2024-11-21 16:44:20CET

Python implementation: CPython
Python version       : 3.10.13
IPython version      : 8.29.0

pycircstat2: 0.1.0

numpy      : 2.1.3
pycircstat2: 0.1.0

Watermark: 2.5.0