Usage
Usage¶
To use arcos4py in a project
import arcos4py
Basic usage example to track collective events in time-series data¶
To use the main class, generate a new class instance of ARCOS
from arcos4py import ARCOS
ts = ARCOS(data,["x, y"], 't', 'id', 'm', 'clTrackID')
| t | x | y | m | id | Position | |
|---|---|---|---|---|---|---|
| 0 | 1 | 0.228724716134052 | -0.158939933368972 | 0 | 1 | 0 |
| 1 | 1 | 0.880322831777765 | -0.117711550077457 | 0 | 2 | 0 |
| 2 | 1 | 1.93057074895645 | 0.0786037381335957 | 0 | 3 | 0 |
| 3 | 1 | 2.95877070488632 | 0.189801493820322 | 0 | 4 | 0 |
| 4 | 1 | 3.90293266588805 | -0.0413798066471996 | 0 | 5 | 0 |
| .. | . | ............... | ................. | . | .. | . |
Prepare the input data.¶
interpolate Measurments¶
If the measurement column contains missing values, run interpolate_measurements() first.
ts.interpolate_measurements()
Clip measurement to provided quantile range¶
Clipping can be performed to remove extreme outliers from the dataset, but it is not necessary.
ts.clip_meas(clip_low: = 0.001, clip_high=0.999)
Rescale and Binarize the measurement¶
Rescaling and detrending are optional for the algorithm to work but recommended. There are three options available: ['none', 'lm', 'runmed']. Rumned is the default.
However, ARCOS requires binarized data to detect and track collective event clusters. Binarization is done by setting a threshold (binThr) and defining measurements below this threshold as 0 and above as 1.
ts.bin_measurements(smoothK: int = 1, biasK = 1, peakThr = 1,binThr = 1, polyDeg = 1, biasMet = "runmed",)
Detect collective events¶
events_df = ts.trackCollev(eps = 1, minClsz = 1, nPrev = 1)
print(events_df)
| t | id | x | y | clTrackID | m | Position | |
|---|---|---|---|---|---|---|---|
| 0 | 2 | 41 | 4.15698907764003 | 3.91461390425413 | 1 | 1 | 0 |
| 1 | 3 | 32 | 3.89042167730585 | 2.98886585399189 | 1 | 1 | 0 |
| 2 | 3 | 40 | 3.08624924975602 | 4.193936843095 | 1 | 1 | 0 |
| 3 | 3 | 41 | 3.99750905085216 | 3.9553900675078 | 1 | 1 | 0 |
| 4 | 3 | 42 | 5.06006349489829 | 4.0631364410516 | 1 | 1 | 0 |
| .. | . | .. | ... | .. | . | . | . |
TrackCollev returns a pandas DataFrame object containing a column with the collecive event id.
Basic usage example to track collective events in images¶
Currently there is no object oriented approach to track events in images. However, the track_events_image function can be used to track events in images.
from arcos4py.tools import track_events_image
img_tracked = track_events_image(np.where(img > 0, 0, 1), eps=1.5)
For more advanced usage, please checkout the scripts and notebooks here: ARCOSpx-publication
Perform calculations without main class¶
All functions from the ARCOS class are also accessible individually through the tools module, such as:
from arcos4py.tools import trackCollev
from arcos4py import track_events_dataframe
Additional modules¶
In addition to the ARCOS algorithm and its helper classes, plots are generated with the plotting module, collective event statistics using the stats module. Please see the Modules Page for further details.