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, verbose='info')

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', overwrite=True)

Import example dataset from github.

Parameters:

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

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=None)

Detect optimal optima and minima.

Parameters:

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

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.

get_verbose()

Get the current verbose level for this instance.

Returns:

Current verbose level

Return type:

str or int

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)

Gridsearch to find best fit.

Parameters:

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

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), visible=True)

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.

set_verbose(verbose)

Set the verbose level for this instance.

Parameters:

verbose (str or int) – Verbose level (‘silent’, ‘critical’, ‘warning’, ‘info’, ‘debug’)

class caerus.caerus.wget

Retrieve file from url.

download(writepath)

Download.

Parameters:

  • url (str.) – Internet source.

  • writepath (str.) – Directory to write the file.

Return type:

None.

filename_from_url(ext=True)

Return filename.