Merge pull request #8 from DanielGoldfarb/master

Version 0.12.x - Ability to plot arbitrary user data (in addition to basic OHLCV data)

Author: DanielGoldfarb

README.md

@@ -11,7 +11,19 @@
 
 ---
 
-# Usage
+# Contents
+
+  - **[Basic Usage](#usage)**
+  - **[Adding Custom Data to Ohlcv Plots](https://github.com/matplotlib/mplfinance/blob/master/examples/addplot.ipynb)**
+  - Customizing the Appearance of Plots (presently in development)
+  - Technical Studies (presently in development)
+  - **[Latest Release Info](#release)**
+  - **[Some Background History About This Package](#history)**
+  - **[Old API Availability](#oldapi)**
+
+---
+
+# <a name="usage"></a>Basic Usage
 Start with a Pandas DataFrame containing OHLC data.  For example,
 
 ```python
@@ -158,7 +170,7 @@ mpf.plot(daily,type='line')
 <br>
 
 We can also plot moving averages with the `mav` keyword
-- use a scaler for a single moving average 
+- use a scalar for a single moving average 
 - use a tuple or list of integers for multiple moving averages
 
 
@@ -500,14 +512,19 @@ For more examples of using mplfinance, please see the jupyter notebooks in the `
 - technical studies, such as:
   - Trading Envelope, Bollinger Bands
   - MACD
-- custom studies and/or additional data on plot
-  - Ability to plot specified additional columns from DataFrame either within the main ohlc plot, or only the lower axis where volume may be displayed.
 - save plot to file
 
+# <a name="release"></a>Release Notes
+
+| Version  |  Description   | Release Date |
+|----------|--------------|----------------|
+| 0.12.x   | Ability plot arbitrary user data (in addition to basic OHLCV data).<br> - both line and scatter plots available.<br> - optionally plot on either the "main" or "lower" (aka "volume") axis. | 2020-01-09 |
+| 0.11.x   | Basic Plotting from Pandas DataFrame of OHLC bars and candlesticks.<br> - optional display of volume<br> - optional display of (up to 3 different) moving averages.<br> - old API still available by importing from "mplfinance/original_flavor" | 2019-13-20  |
+| 0.10.x   | Old mpl-finance API set up as its own package<br> (i.e. removed from the matplotlib package). | 2016-09-08   |
 
 ---
 
-## Some History
+## <a name="history"></a>Some History
 My name is Daniel Goldfarb.  In November 2019, I became the maintainer of `matplotlib/mpl-finance`.  That module is being deprecated in favor of the current `matplotlib/mplfinance`.  The old `mpl-finance` consisted of code extracted from the deprecated `matplotlib.finance` module along with a few examples of usage.  It has been mostly un-maintained for the past three years.  
 
 It is my intention to archive the `matplotlib/mpl-finance` repository soon, and direct everyone to `matplotlib/mplfinance`.  The main reason for the rename is to avoid confusion with the hyphen and the underscore: As it was, `mpl-finance` was *installed with the hyphen, but imported with an underscore `mpl_finance`.*  Going forward it will be a simple matter of both installing and importing `mplfinance`.
@@ -535,7 +552,7 @@ The most common usage is to then call `mpf.plot(data)` where `data` is a `Pandas
 I am very interested to hear from you regarding how you were using the old `mpl-finance` (if you were), what you think of the new `mplfinance`, plus any suggestions you may have for improvement.  You can reach me at [email protected]
 
 ---
-### old API availability
+### <a name="oldapi"></a>old API availability
 
 With this new ` mplfinance ` package installed, in addition to the new API, users can still access the old API (at least for the next several months) by changing their import statments<br>
 **from:**

examples/addplot.ipynb

@@ -0,0 +1,19 @@
+import pandas as pd
+daily = pd.read_csv('data/SP500_NOV2019_Hist.csv',index_col=0,parse_dates=True)
+daily.head(3)
+
+#   idf = pd.read_csv('data/SP500_NOV2019_IDay.csv',index_col=0,parse_dates=True)
+#   idf = idf.drop('Volume',axis=1) # Volume is zero anyway for this intraday data set
+#   idf.index.name = 'Date'
+#   daily = pd.read_csv('data/SP600_NOV2019_Hist.csv',index_col=0,parse_dates=True)
+#   daily = pd.read_csv('data/SP500_NOV2019_Hist.csv',index_col=0,parse_dates=True)
+#   daily = pd.read_csv('data/SP500_NOV2019_Hist.csv',index_col=0,parse_dates=True)
+
+import mplfinance as mpf
+mpf.__file__
+mpf.plot(daily,mav=7)
+mpf.plot(daily,volume=True)
+
+df = pd.read_csv('data/yahoofinance-SPY-20080101-20180101.csv',index_col=0,parse_dates=True)
+mpf.plot(df[700:850],type='bars',no_xgaps=True,mav=(20,40),figscale=0.7)
+mpf.plot(df[700:850],type='bars',volume=True,no_xgaps=True,mav=(20,40),figscale=0.7)

examples/data/SP500_20191106_IDayBollinger.csv

@@ -297,7 +297,7 @@
    "source": [
     "---\n",
     "We can also plot moving averages with the `mav` keyword\n",
-    "- use an scaler for a single moving average \n",
+    "- use an scalar for a single moving average \n",
     "- use a tuple or list of integers for multiple moving averages"
    ]
   },

examples/data/SPY_20110701_20120630_Bollinger.csv

@@ -1,2 +1,3 @@
-from mplfinance.plotting import plot
-from mplfinance._version import __version__
+from mplfinance.plotting       import plot
+from mplfinance.plotting       import make_addplot
+from mplfinance._version       import __version__

examples/test_df.rolling.ipynb

@@ -0,0 +1,57 @@
+import matplotlib.dates  as mdates
+import pandas as pd
+import numpy  as np
+
+def _check_and_prepare_data(data):
+    '''
+    Check and Prepare the data input:
+    For now, data must be a Pandas DataFrame with a DatetimeIndex
+    and columns named 'Open', 'High', 'Low', 'Close', and optionally 'Volume'
+
+    Later (if there is demand for it) we may accept all of the following data formats:
+      1. Pandas DataFrame with DatetimeIndex (as described above)
+      2. Pandas Series with DatetimeIndex:
+             Values are close prices, and Series generates a line plot
+      3. Tuple of Lists, or List of Lists:
+             The inner Lists are each columns, in the order: DateTime, Open, High, Low, Close, Volume
+      4. Tuple of Tuples or List of Tuples:
+             The inner tuples are each row, containing values in the order: DateTime, Open, High, Low, Close, Volume
+
+    Return a Tuple of Lists: datetimes, opens, highs, lows, closes, volumes
+    '''
+    if not isinstance(data, pd.core.frame.DataFrame):
+        raise TypeError('Expect data as DataFrame')
+
+    if not isinstance(data.index,pd.core.indexes.datetimes.DatetimeIndex):
+        raise TypeError('Expect data.index as DatetimeIndex')
+
+    dates   = mdates.date2num(data.index.to_pydatetime())
+    opens   = data['Open'].values
+    highs   = data['High'].values
+    lows    = data['Low'].values
+    closes  = data['Close'].values
+    if 'Volume' in data.columns:
+        volumes = data['Volume'].values
+    else:
+        volumes = None
+
+    return dates, opens, highs, lows, closes, volumes
+
+
+def _mav_validator(mav_value):
+    ''' 
+    Value for mav (moving average) keyword may be:
+    scalar int greater than 1, or tuple of ints, or list of ints (greater than 1).
+    tuple or list limited to length of 3 moving averages (to keep the plot clean).
+    '''
+    if isinstance(mav_value,int) and mav_value > 1:
+        return True
+    elif not isinstance(mav_value,tuple) and not isinstance(mav_value,list):
+        return False
+
+    if not len(mav_value) < 4:
+        return False
+    for num in mav_value:
+        if not isinstance(num,int) and num > 1:
+            return False
+    return True

examples/tplot.py

@@ -1,4 +1,4 @@
-version_info = (0, 11, 1, 'alpha', 1)
+version_info = (0, 12, 0, 'alpha', 0)
 
 _specifier_ = {'alpha': 'a', 'beta': 'b', 'candidate': 'rc', 'final': ''}