Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Elsen API Library

Project description

<p align="center">
<a href="http://elsen.co">
<img src="https://elsen.co/img/apple-touch-icon-144x144.png"/>
</a>
</p>

Elsen Python
============

This library is the Python bindings to the Elsen API that integrate with the
existing Financial Python modeling tools like Pandas and NumPy/SciPy.

Easy Install
------------

For ease of use, it is recommended that you use Anaconda Python Distribution
which is available for Windows, Mac OSX and Linux. It is a self-contained Python
environment that is bundles all the common financial modeling tools.

**[Download Anaconda](https://store.continuum.io/cshop/anaconda/)**

**Mac OS X**

1) [Install Anaconda](http://docs.continuum.io/anaconda/install.html#mac-install)

2) Launch Terminal from the Applications:Utilities folder.

3) Clone the source code for the library.

```bash
$ git clone git@github.com:elsen-trading/elsen-python.git
```

If you do not have Git currently installed then a window will pop up to ask you to install Developer Tools. Click Continue and the run the above command again.

4) Move into the library source folder.

```bash
$ cd elsen-python
```

5) Install the Elsen Python library.

```bash
$ python setup.py install
```

6) Run the example code.

```bash
$ python Example.py
```

Or to launch straight into the IPython notebook.

```
$ ipython notebook
```

**Linux**

1) [Install Anaconda](http://docs.continuum.io/anaconda/install.html#linux-install)

2) If you do not have Git installed, then install it.

```bash
sudo apt-get install git
```

3) Open the Dash by clicking the Ubuntu icon in the upper-left, type "terminal",
and select the Terminal application from the results that appear.

4) Clone the source code for the library.

```bash
$ git clone git@github.com:elsen-trading/elsen-python.git
```

5) Move into the library source folder.

```bash
$ cd elsen-python
```

6) Install the Elsen Python library.

```bash
$ python setup.py install
```

7) Run the example code.

```bash
$ python Example.py
```

Or to launch straight into the IPython notebook.

```
$ ipython notebook
```

**Windows**

Custom Install
--------------

**Setuptools**

```bash
$ pip install -r requirements.txt
$ python setup.py install
```

Optionally several common libraries can be integrated:

```bash
$ pip install pandas
$ pip install numpy
$ pip install ipython
$ pip install matplotlib
```

Usage
-----

The library is entirely contained in the ``elsen`` module:

```python
from elsen import *
```

**Authentication**

To authenticate with the system you'll require four pieces of information
contained in your *Elsen Welcome* email:

* Authentication token
* Application id
* Username
* Password

```python
elsen = Elsen()

elsen.authenticate(
app_id = app_id,
username = 'bob',
password = 'trader'
)
```

Adding a new application.

```python
elsen.add_application(
email = 'bob@elsen.co'
app_id = app_id
)
```

Once logged in, new users can be added to an application.

```python
elsen.add_user(
app_id,
username,
password,
# Optional fields.
first_name = 'Bob',
last_name = 'Trader',
email = 'bob@elsen.co'
)
```

**Exchanges**

```python
In [1]: elsen.get_exchanges()
Out[1]: [u'NASDAQ', u'NYSE', u'AMEX']
```

**Indices**

```python
In [1]: elsen.get_indices()
Out[1]: [u'SP500']
```

**Filters**

To get the most common ( in terms of company count ) filters available in the
system query the common filters function. The top 10 available in the system
are as follows:

* ``avgvol30`` - Average amount of shares traded in a 30-day period.
* ``phigh250`` - Percentage to highest price that a stock has traded at during the previous year.
* ``dailyvolume`` - Average amount of shares traded in a day.
* ``currentprice`` - Real time price of a security or the most recent listed.
* ``plow250`` - Percentage to lowest price that a stock has traded at during the previous year.
* ``inc_eibt`` - Net income before taxes
- ``inc_sdws`` - Weighted average common shares outstanding including dilution due to options.
- ``inc_sdai`` - EPS (taking into account options) including expenses caused by unusual events.
- ``inc_sbas`` - Weighted average common shares outstanding less dilution.
- ``inc_sbai`` - EPS including expenses caused by unusual events such as natural disasters, etc.


```python
n [1]: elsen.get_filters()[0:10]
Out[1]:
[<<Filter: name=inc_vpti desc='Income before taxes excluding non-recurring charges and/or credits.' count=500>>,
<<Filter: name=inc_ndep desc='Depreciation Expense' count=2>>,
<<Filter: name=inc_xnic desc='Income available excluding expenses caused by extraordinary events.' count=504>>,
<<Filter: name=inc_nama desc='Amortization of Acquisition Costs' count=0>>,
<<Filter: name=inc_vrrp desc='Reported Ordinary Profit' count=0>>,
<<Filter: name=inc_sbtr desc='Bank Total Revenue' count=43>>,
<<Filter: name=inc_stps desc='Total Plan Service Cost' count=83>>,
<<Filter: name=inc_vdcd desc='Defined Contribution Expense - Domestic' count=30>>,
<<Filter: name=inc_vxtc desc='Transition Costs - Post-Retirement' count=8>>,
<<Filter: name=bal_qtsn1 desc='Number of common shares owned by the company itself and its subsidiaries' count=477>>]
```

```python
In [2]: elsen.search_filters('profit')
Out[2]:
[<<Filter: name=inc_vrrp desc='Reported Ordinary Profit' count=0>>,
<<Filter: name=inc_vnbp desc='Reported Net Business Profits' count=0>>,
<<Filter: name=inc_vopp desc='Reported Operating Profit' count=2>>,
<<Filter: name=inc_ndta desc='Dealer Trading Account Profit' count=1>>,
<<Filter: name=inc_migk desc='New Business Profit' count=0>>,
<<Filter: name=inc_ttax desc='All taxes on the basis of profits owned to federal, state and/or foreign government.' count=484>>,
<<Filter: name=inc_vgrp desc='Reported Gross Profit' count=0>>,
<<Filter: name=inc_vopr desc='Reported Operating Profit Margin' count=0>>,
<<Filter: name=inc_sgrp desc='Gross Profit' count=386>>,
<<Filter: name=inc_mibz desc='Underwriting Profit or Loss' count=5>>,
<<Filter: name=inc_snpm desc='The ratio of net profits to revenues (typically expressed in %).' count=477>>,
<<Filter: name=inc_ninc desc='A company's total earnings or profit.' count=504>>]
```

**Indicators**

```python
In [1]: elsen.get_indicators()
Out[1]:
[<<Indicator: trailing>>,
<<Indicator: cross>>,
<<Indicator: ema>>,
<<Indicator: rsi>>,
<<Indicator: macd>>,
<<Indicator: bollingerband>>,
<<Indicator: sma>>]
```

*Relative Strength Index*:

```python
In[1]: rsi = elsen.get_indicators('rsi')

In[2]: print rsi.short_desc
The Relative Strength Index (RSI) measures the trend of a securities’ price by
measuring the ratio of average gains to average losses, and converting it to an
index from 1 to 100.

In [3]: rsi.inputs()
{u'action': u'BUY|SELL',
u'lookback': u'# lookback periods',
u'lower': u'Smallest value that will trigger an activation, inclusive.',
u'name': u'RSI',
u'upper': u'Largest value that will trigger an activation, inclusive.'}
```

*Simple Moving Average*:

```python
In [1]: sma = elsen.get_indicators('sma')

In [2]: print sma.short_desc
The simple moving average is a trailing price indicator, indicating trends in
securities prices by measuring the average closing price of a select number of
periods prior to the current period.

In [3]: print sma.inputs()
{u'action': u'BUY|SELL',
u'upper': u'Largest value that will trigger an activation, inclusive.',
u'lower': u'Smallest value that will trigger an activation, inclusive.',
u'lookback': u'Window size',
u'name': u'SMA'}
```

**Strategies**

```python
# Buy when oversold
ind1 = Indicator(action=BUY, name=RSI, lower=1, upper=30, lookback=21)

# Sell when overbought
ind2 = Indicator(action=SELL, name=RSI, lower=70, upper=100, lookback=21)

# Filter out low price and low volume companies
flt1 = Filter(name='currentprice', min=0, max=200)
flt2 = Filter(name='avgvol30', min=10000000.0, max=3400000000.0)

# Setup the strategy
strategy = elsen.setup_strategy(
universe = 'SP900',
indicators = [ind1, ind2],
filters = [flt1, flt2],
interval = 1)
```

**Simulations**

To execute the backtest apply pass the strategy object as a argument to
``setup_backtest`` along with a date range.

```python
backtest = elsen.setup_backtest(
strategy = strategy,
start = '2014-5-1',
end = '2014-12-1')

# Run the backtest, wait for the results.
backtest.join(timing=True)
backtest.details()
```

To pull the specific details for a backtest in the system, given a specific
backtest id. Use the ``detailsfor`` function.

```python
In[1]: elsen.detailsfor('dfd7faf3-e13c-4293-b55d-33bbd4fb0f9f')
```

**Metrics**

```python
In[1]: print 'Returns: $%s' % backtest.returns()
Returns: $40193.9147

In[2]: print 'Sharpe Ratio: %s' % backtest.sharpe()
Sharpe Ratio: 0.77072534093809145889

In[3]: print 'Alpha: %s' % backtest.alpha()
Alpha: -0.140887764298623

In[4]: print 'Beta: %s' % backtest.beta()
Beta: 0.0000752396488764315
```

To get all of the metrics for the Backtest object you can call
``help(backtest)`` to get the list of all available properties and methods.

The backtest object itself can also be converted to a Pandas dataframe, JSON
object, or serialized to a file.

```python
In[1]: backtest.to_dataframe()
...
In[2]: backtest.to_json()
...

In [3]: backtest.to_dataframe()['drawdown']
Out[4]:
0 45.48239846246275415098
Name: drawdown, dtype: object
```

To pull the individual trades for a backtest use the ``trades`` function which
can generate the resulting dataframe object.

```python
In[1]: backtest.trades()
...
In[2]: backtest.trades().to_dataframe()
```

Documentation
-------------

```bash
$ cd docs
$ make html
$ make latexpdf
```

Filing Issues
-------------

If you file an issue with Elsen support then please put the following line at
the beginning of your script.

```python
enable_debugging()
```

In your bug report/email to support please include the following

* Script or IPython Notebook used to run your program.
* The output file ``elsen-python.log``.

IPython
-------

The use cases are also provided in IPython notebook form for interactive usage:

* [Visualization](Visualization.ipynb)

```bash
$ ipython notebook Visualization.ipynb
```

Project details


Release history Release notifications

This version

0.1.2

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for elsen, version 0.1.2
Filename, size File type Python version Upload date Hashes
Filename, size elsen-0.1.2.tar.gz (24.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page