API References

References.

Name : caerus.py Author : E.Taskesen Contact : erdogant@gmail.com Date : May 2020

class caerus.caerus.caerus(window=50, minperc=3, nlargest=10, threshold=0.25, extb=0, extf=10)

Compute the local minima with the corresponding local-maxima within the given time-frame.

Description

In Greek mythology, Caerus (same as kairos) was the personification of opportunity, luck and favorable moments. He was shown with only one lock of hair. His Roman equivalent was Occasio or Tempus. Caerus was the youngest child of Zeus.

caerus is a python package providing that determines the local-minima with the corresponding local-maxima within the given time-frame. The method is build using a forward rolling window to iteratively evaluate thousands of windows. For each window a score of percentages is computed from the start-to-stop position. The resulting matrix is a [window x length dataframe] for which only the high scoring percentages, e.g. those above a certain value (minperc) are used. The best scoring percentages is then aggregated by sum per time-point followed by a cut using the threshold. The resulting regions are subsequently detected, and represent the starting-locations of the trade. The stop-locations are determined based on the distance and percentage of te start-locations. As an example, if you want to have best regions, use threshold=1, minperc=high and nlargest=1 (small).

Here are just a few of the things that caerus does well:

  • Ouput contains detected start-stop regions of local minima and maxima.

  • Figures are created.

  • Parameter gridsearch.

  • Designed for the detection of complex trend movements.

param window

Window size that is used to determine whether there is an increase in percentage. start location + window. 50 : (default) Smaller window size is able to pickup better local-minima. 1000 : Larger window size will more stress on global minma.

type window

int [1,..,len(X)], default : 50

param minperc

Minimum percentage to declare a starting position with window relevant. Note that nlargest is used to identify the top n largest percentages as stopping location.

type minperc

float [0,..,100], default : 3

param nlargest

Identify the top n percentages, and thus stop-regions (couples to start-region). The larger this number, the larger the stop-region untill it is limited by minperc.

type nlargest

float [1,..,inf], default : 10

param threshold

Required to optimize for the maximum depth of the local-minima. At the ith location, k windows (eg 50) are overlaid and the percentages are determined. The socre is determined by (percentage(i-start,k-stop)) >= minperc (eg 3), and normalized for the maximum number of windows used at position i. In best case scenarion, all window result in percentage>minperc and will have score 50/50=1.

type threshold

float [0,..,1], default : 0.25

param return_as_dict

Return results in a dictionary.

type return_as_dict

Bool (default : True)

Examples

>>> from caerus import caerus
>>> cs = caerus()
>>> X = cs.download_example()
>>> cs.fit(X)
>>> cs.plot()
download_example(name='btc', verbose=3)

Import example dataset from github.

Parameters

  • name (str, optional) – name of the file to download.

  • verbose (int, optional) – Print message to screen. The default is 3.

Return type

tuple containing dataset and response variable (X,y).

fit(X, window=None, minperc=None, threshold=None, nlargest=None, return_as_dict=True, verbose=3)

Detect optimal optima and minima.

Parameters

  • X (array-like : 1D array.) – Data such as stock prices in a 1D vector.

  • verbose (Int, [0..5]. The higher the number, the more information is printed.) – 0: None, 1: ERROR, 2: WARN, 3: INFO (default), 4: DEBUG, 5 : TRACE

Raises

Exception – 1D array should be of type 1D numpy array or list.

Returns

  • Object.

  • X (array-like : 1D array.) – Input 1D vector.

  • simmat (np.array) – Simmilarity matrix

  • loc_start (list of int) – list of indexes containing start positions

  • loc_stop (list of int) – list of indexes containing stop positions

  • loc_start_best (list of int) – list of indexes containing the best starting positions

  • loc_stop_best (list of int) – list of indexes containing the best stopping positions

  • agg (1D array-like) – Aggregated 1D array

  • df (pd.DataFrame) – Results in the form of a dataframe.

  • verbose (Int, [0..5]. Default : 3) – The higher the number, the more information is printed. 0: None, 1: ERROR, 2: WARN, 3: INFO, 4: DEBUG, 5 : TRACE

gridsearch(X, window=array([50, 100, 150, 200, 250, 300, 350, 400, 450, 500]), minperc=array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]), threshold=0.25, return_as_dict=False, verbose=3)

Gridsearch to find best fit.

Parameters

  • X (array-like : 1D array.) – Input 1D vector.

  • verbose (Int, [0..5]. Default : 3) – The higher the number, the more information is printed. 0: None, 1: ERROR, 2: WARN, 3: INFO, 4: DEBUG, 5 : TRACE

Returns

  • Object containing dict with key [‘gridsearch’] such as cs.gridsearch

  • balances (np-array) – results of balances across various levels of: window x minperc

  • trades (np-array) – results of trades across various levels of: window x minperc

plot(threshold=None, figsize=(25, 15))

Plot results.

Parameters

  • threshold (float [0,..,1], default : 0.25) – Required to optimize for the maximum depth of the local-minima. At the ith location, k windows (eg 50) are overlaid and the percentages are determined.

  • figsize (tuple, optional) – Figure size. The default is (25,15).

Return type

None.