# Classic Stock Charts in Python
Create classic technical analysis stock charts in Python with minimal code.
The library is built around [matplotlib](https://github.com/matplotlib/matplotlib)
and [pandas](https://github.com/pandas-dev/pandas).
Charts can be defined using a declarative interface,
based on a set of drawing primitives like `Candleststicks`, `Volume`
and technical indicators like `SMA`, `EMA`, `RSI`, `ROC`, `MACD`, etc ...
> **Warning**
> This project is experimental and the interface can change.
> For a similar project with a mature api you may want to look into
> [mplfinance](https://pypi.org/project/mplfinance/).
## Typical Usage
```python
import yfinance as yf
from mplchart.chart import Chart
from mplchart.primitives import Candlesticks, Volume
from mplchart.indicators import SMA, EMA, ROC, RSI, MACD
ticker = 'AAPL'
prices = yf.Ticker(ticker).history('5y')
max_bars = 250
indicators = [
Candlesticks(),
Volume(),
SMA(50),
SMA(200),
RSI(),
MACD(),
]
chart = Chart(title=ticker, max_bars=max_bars)
chart.plot(prices, indicators)
chart.show()
```
## Conventions
Price data is expected to be presented as a pandas DataFrame
with columns `open`, `high`, `low`, `close` `volume`
and a datetime index named `date` or `datetime`.
Please note, the library will automatically convert column
and index names to lower case for its internal use.
## Drawing Primitives
The library contains drawing primitives that can be used like an indicator in the plot api.
Primitives are classes and must be instantiated as objects before being used with the plot api.
```python
from mplchart.chart import Chart
from mplchart.primitives import Candlesticks
indicators = [Candlesticks()]
chart = Chart(title=title, max_bars=max_bars)
chart.plot(prices, indicators)
```
The main drawing primitives are :
- `Candlesticks` for candlestick plots
- `OHLC` for open, high, low, close bar plots
- `Price` for price line plots
- `Volume` for volume bar plots
- `Peaks` to mark peaks and valleys
- `SameAxes` to use same axes as last plot
- `NewAxes` to use new axes above or below
- `LinePlot` draw an indicator as line plot
- `AreaPlot` draw an indicator as area plot
- `BarPlot` draw an indicator as bar plot
## Builtin Indicators
The libary includes some standard technical analysis indicators implemented in pandas/numpy.
Indicators are classes and must be instantiated as objects before being used with the plot api.
Some of the indicators included are:
- `SMA` Simple Moving Average
- `EMA` Exponential Moving Average
- `WMA` Weighted Moving Average
- `HMA` Hull Moving Average
- `ROC` Rate of Change
- `RSI` Relative Strength Index
- `ATR` Average True Range
- `ATRP` Average True Range Percent
- `ADX` Average Directional Index
- `DMI` Directional Movement Index
- `MACD` Moving Average Convergence Divergence
- `PPO` Price Percentage Oscillator
- `SLOPE` Slope (time linear regression)
- `STOCH` Stochastic Oscillator
- `BBANDS` Bollinger Bands
## Talib Functions
If you have [ta-lib](https://github.com/mrjbq7/ta-lib) installed you can use the library abstract functions as indicators.
The indicators are created by calling `Function` with the name of the indicator and its parameters.
```python
from mplchart.primitives import Candlesticks
from talib.abstract import Function
indicators = [
Candlesticks(),
Function('SMA', 50),
Function('SMA', 200),
Function('RSI'),
Function('MACD'),
]
```
## Override indicator rendering with the plotting primitives
Most indicators are drawn as line plots with default colors and settings. You can override the rendering of an indicator by piping it with the `|` operator into a primitive like `LinePlot`, `AreaPlot` or `BarPlot` as in the example below. If the indicator returns a dataframe instead of a series you need to specify an `item` (column name) in the primitive.
```python
from mplchart.indicators import SMA, EMA, ROC
from mplchart.primitives import Candlesticks, LinePlot
indicators = [
Candlesticks(),
SMA(20) | LinePlot(style="dashed", color="red", alpha=0.5, width=3)
]
```
## Override target axes with `NewAxes` and `SameAxes` primitives
Indicators usually plot in a new axes below, except for a few indicators that plot by default in the main axes. You can change the target axes for any indicator by piping it into an axes primitive as in the example below.
```python
from mplchart.indicators import SMA, EMA, ROC
from mplchart.primitives import Candlesticks, NewAxes, SameAxes
indicators = [
Candlesticks(),
ROC(20) | NewAxes(),
ROC(50) | SameAxes(),
]
```
## Custom Indicators
Any callable that accepts a prices dataframe and returns a series or dataframe can be used as an indicator.
You can also implement a custom indicator as a subclass of `Indicator`.
```python
from mplchart.model import Indicator
from mplchart.library import get_series, calc_ema
class DEMA(Indicator):
"""Double Exponential Moving Average"""
same_scale = True
# same_scale is an optional class attribute
# to specify that the indicator can be drawn
# on the same axes as the previous indicator
def __init__(self, period: int = 20):
self.period = period
def __call__(self, prices):
series = get_series(prices)
ema1 = calc_ema(series, self.period)
ema2 = calc_ema(ema1, self.period)
return 2 * ema1 - ema2
```
## Examples
You can find example notebooks and scripts in the `examples` folder.
## Installation
You can install the current version of this package with pip
```console
python -mpip install git+https://github.com/furechan/mplchart.git
```
## Dependencies
- python >= 3.9
- matplotlib
- pandas
- numpy
## Related Projects & Resources
- [stockcharts.com](https://stockcharts.com/) Classic stock charts and technical analysis reference
- [mplfinance](https://pypi.org/project/mplfinance/) Matplotlib utilities for the visualization, and visual analysis, of financial data
- [matplotlib](https://github.com/matplotlib/matplotlib) Matplotlib: plotting with Python
- [pandas](https://github.com/pandas-dev/pandas) Flexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more
- [yfinance](https://github.com/ranaroussi/yfinance) Download market data from Yahoo! Finance's API
- [ta-lib](https://github.com/mrjbq7/ta-lib) Python wrapper for TA-Lib
Raw data
{
"_id": null,
"home_page": null,
"name": "mplchart",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "candlesticks, charting, finance, matplotlib",
"author": null,
"author_email": "Furechan <furechan@xsmail.com>",
"download_url": null,
"platform": null,
"description": "# Classic Stock Charts in Python\n\n\nCreate classic technical analysis stock charts in Python with minimal code.\nThe library is built around [matplotlib](https://github.com/matplotlib/matplotlib)\nand [pandas](https://github.com/pandas-dev/pandas). \nCharts can be defined using a declarative interface,\nbased on a set of drawing primitives like `Candleststicks`, `Volume`\nand technical indicators like `SMA`, `EMA`, `RSI`, `ROC`, `MACD`, etc ...\n\n\n> **Warning**\n> This project is experimental and the interface can change.\n> For a similar project with a mature api you may want to look into\n> [mplfinance](https://pypi.org/project/mplfinance/).\n\n\n![Showcase Chart](https://github.com/furechan/mplchart/raw/main/output/showcase.svg \"Showcase\")\n\n\n## Typical Usage\n\n```python\nimport yfinance as yf\n\nfrom mplchart.chart import Chart\nfrom mplchart.primitives import Candlesticks, Volume\nfrom mplchart.indicators import SMA, EMA, ROC, RSI, MACD\n\nticker = 'AAPL'\nprices = yf.Ticker(ticker).history('5y')\n\nmax_bars = 250\n\nindicators = [\n Candlesticks(),\n Volume(),\n SMA(50),\n SMA(200),\n RSI(),\n MACD(),\n]\n\nchart = Chart(title=ticker, max_bars=max_bars)\nchart.plot(prices, indicators)\nchart.show()\n```\n\n\n## Conventions\n\nPrice data is expected to be presented as a pandas DataFrame\nwith columns `open`, `high`, `low`, `close` `volume`\nand a datetime index named `date` or `datetime`.\nPlease note, the library will automatically convert column\nand index names to lower case for its internal use.\n\n\n## Drawing Primitives\n\nThe library contains drawing primitives that can be used like an indicator in the plot api.\nPrimitives are classes and must be instantiated as objects before being used with the plot api.\n\n```python\nfrom mplchart.chart import Chart\nfrom mplchart.primitives import Candlesticks\n\nindicators = [Candlesticks()]\nchart = Chart(title=title, max_bars=max_bars)\nchart.plot(prices, indicators)\n```\n\nThe main drawing primitives are :\n- `Candlesticks` for candlestick plots\n- `OHLC` for open, high, low, close bar plots\n- `Price` for price line plots\n- `Volume` for volume bar plots\n- `Peaks` to mark peaks and valleys\n- `SameAxes` to use same axes as last plot\n- `NewAxes` to use new axes above or below\n- `LinePlot` draw an indicator as line plot\n- `AreaPlot` draw an indicator as area plot\n- `BarPlot` draw an indicator as bar plot\n\n\n\n\n## Builtin Indicators\n\nThe libary includes some standard technical analysis indicators implemented in pandas/numpy.\nIndicators are classes and must be instantiated as objects before being used with the plot api.\n\nSome of the indicators included are:\n\n- `SMA` Simple Moving Average\n- `EMA` Exponential Moving Average\n- `WMA` Weighted Moving Average\n- `HMA` Hull Moving Average\n- `ROC` Rate of Change\n- `RSI` Relative Strength Index\n- `ATR` Average True Range\n- `ATRP` Average True Range Percent\n- `ADX` Average Directional Index\n- `DMI` Directional Movement Index\n- `MACD` Moving Average Convergence Divergence\n- `PPO` Price Percentage Oscillator \n- `SLOPE` Slope (time linear regression)\n- `STOCH` Stochastic Oscillator\n- `BBANDS` Bollinger Bands\n\n\n\n## Talib Functions\n\nIf you have [ta-lib](https://github.com/mrjbq7/ta-lib) installed you can use the library abstract functions as indicators.\nThe indicators are created by calling `Function` with the name of the indicator and its parameters.\n\n```python\nfrom mplchart.primitives import Candlesticks\nfrom talib.abstract import Function\n\nindicators = [\n Candlesticks(),\n Function('SMA', 50),\n Function('SMA', 200),\n Function('RSI'),\n Function('MACD'),\n]\n```\n\n\n## Override indicator rendering with the plotting primitives\n\nMost indicators are drawn as line plots with default colors and settings. You can override the rendering of an indicator by piping it with the `|` operator into a primitive like `LinePlot`, `AreaPlot` or `BarPlot` as in the example below. If the indicator returns a dataframe instead of a series you need to specify an `item` (column name) in the primitive.\n\n\n```python\nfrom mplchart.indicators import SMA, EMA, ROC\nfrom mplchart.primitives import Candlesticks, LinePlot\n\nindicators = [\n Candlesticks(),\n SMA(20) | LinePlot(style=\"dashed\", color=\"red\", alpha=0.5, width=3)\n]\n```\n\n\n## Override target axes with `NewAxes` and `SameAxes` primitives\n\nIndicators usually plot in a new axes below, except for a few indicators that plot by default in the main axes. You can change the target axes for any indicator by piping it into an axes primitive as in the example below.\n\n```python\nfrom mplchart.indicators import SMA, EMA, ROC\nfrom mplchart.primitives import Candlesticks, NewAxes, SameAxes\n\nindicators = [\n Candlesticks(),\n ROC(20) | NewAxes(),\n ROC(50) | SameAxes(),\n]\n```\n\n\n## Custom Indicators\n\nAny callable that accepts a prices dataframe and returns a series or dataframe can be used as an indicator.\nYou can also implement a custom indicator as a subclass of `Indicator`.\n\n```python\nfrom mplchart.model import Indicator\nfrom mplchart.library import get_series, calc_ema\n\nclass DEMA(Indicator):\n \"\"\"Double Exponential Moving Average\"\"\"\n\n same_scale = True\n # same_scale is an optional class attribute\n # to specify that the indicator can be drawn\n # on the same axes as the previous indicator\n\n def __init__(self, period: int = 20):\n self.period = period\n\n def __call__(self, prices):\n series = get_series(prices)\n ema1 = calc_ema(series, self.period)\n ema2 = calc_ema(ema1, self.period)\n return 2 * ema1 - ema2\n```\n\n\n\n## Examples\n\nYou can find example notebooks and scripts in the `examples` folder. \n\n## Installation\n\nYou can install the current version of this package with pip\n\n```console\npython -mpip install git+https://github.com/furechan/mplchart.git\n```\n\n## Dependencies\n\n- python >= 3.9\n- matplotlib\n- pandas\n- numpy\n\n\n## Related Projects & Resources\n- [stockcharts.com](https://stockcharts.com/) Classic stock charts and technical analysis reference\n- [mplfinance](https://pypi.org/project/mplfinance/) Matplotlib utilities for the visualization, and visual analysis, of financial data\n- [matplotlib](https://github.com/matplotlib/matplotlib) Matplotlib: plotting with Python\n- [pandas](https://github.com/pandas-dev/pandas) Flexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more\n- [yfinance](https://github.com/ranaroussi/yfinance) Download market data from Yahoo! Finance's API\n- [ta-lib](https://github.com/mrjbq7/ta-lib) Python wrapper for TA-Lib\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Classic Stock Charts in Python",
"version": "0.0.14",
"project_urls": {
"homepage": "https://github.com/furechan/mplchart"
},
"split_keywords": [
"candlesticks",
" charting",
" finance",
" matplotlib"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "571e3685752f653d30c274f89ad8c0d32c09782763d81d40b730b01811c5ebf8",
"md5": "6e391e98b44925d8928b1731b82b3405",
"sha256": "c2d9c57d1a07496a2bebf448f7b1238d83078ec48ed679cefaed4538d2f7ff7c"
},
"downloads": -1,
"filename": "mplchart-0.0.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e391e98b44925d8928b1731b82b3405",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 562254,
"upload_time": "2024-10-17T12:04:18",
"upload_time_iso_8601": "2024-10-17T12:04:18.130811Z",
"url": "https://files.pythonhosted.org/packages/57/1e/3685752f653d30c274f89ad8c0d32c09782763d81d40b730b01811c5ebf8/mplchart-0.0.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-17 12:04:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "furechan",
"github_project": "mplchart",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "mplchart"
}
JSON
