Metadata-Version: 2.4
Name: seolpyo-mplchart
Version: 2.1.0
Summary: Fast candlestick chart using Python. Includes navigator, slider, navigation, and text information display functions
Author-email: white-seolpyo <white-seolpyo@naver.com>
License: MIT License
Project-URL: Homepage, https://white.seolpyo.com/
Project-URL: Documentation(English), https://white.seolpyo.com/entry/148/
Project-URL: Documentation(한글), https://white.seolpyo.com/entry/147/
Project-URL: repository, https://github.com/white-seolpyo/seolpyo-mplchart
Project-URL: Issues, https://github.com/white-seolpyo/seolpyo-mplchart/issues
Keywords: chart,차트,stock,주식,invest,투자,finance,파이낸스,candle,캔들,candlestick,캔들스틱,matplotlib,mplfinance,pyqtgraph,finplot,virtual currency,가상화폐,coin,코인,bitcoin,비트코인,ethereum,이더리움
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Matplotlib
Classifier: Operating System :: Microsoft :: Windows
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: pandas>=2.0.0

# Donation
Bitcoin: 1MKCHW8smDZv5DFMiVkA5G3DeXcMn871ZX

Ethereum: 0x1c5fb8a5e0b1153cd4116c91736bd16fabf83520


# Document
[English Document](https://github.com/white-seolpyo/seolpyo-mplchart/tree/maind)

[한글 설명서](https://white.seolpyo.com/entry/147/?from=pypi)


# This document was originally written in Korean and translated using a machine translation tool.


reference version
----

2.1.0

Package Introduction
------

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/candle.png?raw=true)![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/40000.gif?raw=true)

Sample Charts with Over 40,000 Stock Price Data Points, with Intel i5 4690

seolpyo-mplchart is a Python package built on top of matplotlib.

While libraries like finplot and plotly are commonly used to draw candlestick charts in Python, I created this package because none of the existing tools fully met my needs.



**Key Features**

* Provides three types of Chart classes for flexible charting.
* Includes an overview slider (SliderChart) that highlights the visible range, allowing users to select or move the viewing window interactively.
* Integrates smoothly with various GUI frameworks, including tkinter, ensuring responsive performance.
* Displays stock price information as text (CursorChart, SliderChart). Simply hover your mouse over a candlestick or volume bar to view the corresponding data.
- Built-in support for toggling moving average lines on and off.

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/ma%20on%20off.gif?raw=true)

You can check out a sample of drawing candlestick charts integrated with tkinter at the following link:

[View tkinter sample code](https://white.seolpyo.com/entry/214/)

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/with%20tkinter.gif?raw=true)

✅ Verified to work with 32-bit Python 3.11, pandas 2.0.0, and matplotlib 3.7.0.

Installation
-----

    > pip install seolpyo-mplchart

Quick Start
-----

### OnlyChart

It is a chart that simply renders without any interaction.

    import seolpyo_mplchart as mc
    
    chart = mc.OnlyChart()
    df: pandas.DataFrame = {stock price data frame}
    chart.set_data(df)
    mc.show()
    

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/chart%20only.png?raw=true)

### CursorChart

This chart is an enhanced version of OnlyChart with mouse interaction capabilities.
It displays the date information corresponding to the mouse cursor position at the bottom of the chart, and price or volume data on the right side.
When the mouse cursor hovers over a candlestick or volume bar, the relevant information is shown as text.


    import seolpyo_mplchart as mc
    
    chart = mc.CursorChart()
    df: pandas.DataFrame = {stock price data frame}
    chart.set_data(df)
    mc.show()
    

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/chart%20cursor.png?raw=true)

### SliderChart

This chart is an extended version of CursorChart with an added overview slider.
The slider allows users to select or move the viewing range, and users can also click and drag within the chart area to shift the visible region.


    import seolpyo_mplchart as mc
    
    chart = mc.SliderChart()
    df: pandas.DataFrame = {stock price data frame}
    chart.set_data(df)
    mc.show()
    

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/sample.gif?raw=true)

Chart Description
--------

### Chart Class Variables

#### CONFIG

Chart Configuration File
If not provided, the predefined CONFIG\* settings will be used.

\* CONFIG: mc.DEFAULTCONFIG(OnlyChart, CursorChart) 또는 mc.SLIDERCONFIG(SliderChart)


#### watermark

Watermark text displayed at the center of the chart.
If if not self.watermark evaluates to true, the watermark will not be rendered.


#### candle\_on\_ma

If true, candlesticks are drawn above the moving average line.
If false, candlesticks are drawn below the moving average line, as shown in the following image.


![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/ma%20above%20candle.png?raw=true)

#### limit\_candle

If the number of candlesticks to be drawn on the screen is less than or equal to this value, full candlesticks are rendered.
If it exceeds the value, only wicks are drawn.


![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/wick.png?raw=true)

#### limit\_wick

If the number of candlesticks to be drawn on the screen is less than or equal to this value, only wicks are rendered.
If it exceeds the value, a line chart is drawn instead.


![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/line.png?raw=true)

#### limit\_volume

If the number of candlesticks drawn on the screen is less than or equal to self.limit_wick, the entire volume data is rendered.
If it exceeds that value, only a subset of volume data is drawn — specifically, the top limit_volume entries sorted in descending order of volume.
If you experience buffering when moving across a wide range, lowering this value may help improve performance.
This only applies while the chart is being moved in the Slider chart.

#### limit\_ma

If the number of candlesticks drawn on the screen is less than or equal to this value, the moving average line is rendered.
If you experience buffering when navigating across a wide range, lowering this value may help improve performance.
This only applies while the chart is being moved in the Slider chart.

#### key\_date, key\_open, key\_high, key\_low, key\_close, key\_volume

Keys for each column used in the provided data
If if not self.key_volume evaluates to true at the time of executing Chart.set_data(df), the volume chart will not be rendered.


    import seolpyo_mplchart as mc
    
    df: pandas.DataFrame = {stock price data frame}
    
    c = mc.SliderChart()
    c.key_date= '시간'
    c.key_open = '시가'
    c.key_high = '고가'
    c.key_low = '저가'
    c.key_close = '종가'
    # c.key_volume = '거래량'
    c.key_volume = None
    c.set_data(df)
    
    mc.show() # same as matplotlib.pyplot.show()
    
    
    ### OR ###
    
    
    import json
    
    import seolpyo_mplchart as mc
    import pandas as pd
    
    file = {stock price data path}
    with open(file, 'r', encoding='utf-8') as txt:
        data = json.load(txt)
    df = pd.DataFrame(data)
    
    class Chart(mc.SliderChart):
      key_date = '시간'
      key_open, key_high, key_low, key_close = ('시가', '고가', '저가', '종가')
      # key_volume = '거래량'
      key_volume = None
    
    c = Chart()'
    c.set_data(df)
    
    mc.show() # same as matplotlib.pyplot.show()
    
    

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/en%20no%20vol%20(2).png?raw=true)

#### fraction

If true, decimal values are displayed as fractions.

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/fraction.png?raw=true)

#### slider\_top

If true, the slider is positioned above the chart.

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/slider%20bottom.png?raw=true)

#### min\_distance

Minimum number of candlesticks required when selecting a slider range
If the selected range contains fewer candlesticks than this value, the previous range will be retained.


![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/min%20distance.gif?raw=true)

#### in\_chart

Determines whether the mouse cursor is located within the price chart or volume chart area.


#### in\_slider

Determines whether the mouse cursor is located within the slider area.


#### in\_price\_chart

Determines whether the mouse cursor is located within the price chart area.


#### in\_volume\_chart

Determines whether the mouse cursor is located within the volume chart area.


### Chart class method
#### Chart.\_\_init\_\_(config=DEFAULTCONFIG or SLIDERCONFIG)

Creates a chart object.

#### Chart.set_data(df, change_xlim=True)

Passes stock price data to the chart object.
The chart object generates chart data based on the received input.
When retrieving data from a DataFrame, the predefined keys — Chart.key\_date, Chart.key\_open, Chart.key\_high, Chart.key\_low, Chart.key\_close, and Chart.key\_volume — are used.
Therefore, these keys should be properly set before calling set\_data.
`if change_lim is True`, it retrieves the values from Chart.get_default_lim() and updates the xlim accordingly.



#### Chart.get_default_xlim()

It retrieves the xlim values set when Chart.set_data() is called.

#### Chart.refresh()

Refreshes the chart.
During the refresh, any changes made to self.CONFIG are applied.


#### Chart.add\_artists()

Function that adds the Artists used in the chart. Called during initialization (init).


#### Chart.draw\_artists()

Function that renders the Artists on the chart.
Called when the on_draw event is triggered.


#### Chart.set\_artists()

Function that applies the settings of chart Artists.
Called during refresh.


#### Chart.set\_collections()

Function that applies the settings of candlestick and volume chart Artists.
Called during refresh or when the display area changes.


#### Chart.add\_candle\_color\_column(), Chart.add\_volume\_color\_column()

This method determines the colors of candlesticks and volume bars drawn on the chart.
It adds the following columns to self.df:
- ['facecolor', 'edgecolor'] for candlesticks
- ['facecolor_volume', 'edgecolor_volume'] for volume bars
By modifying the values in these columns, you can customize the colors as desired.


##### Candlestick Colors
- Open < Close, Previous Close < Close
→ self.CONFIG.CANDLE.FACECOLOR.bull_rise, self.CONFIG.CANDLE.EDGECOLOR.bull_rise
- Open < Close, Previous Close > Close
→ self.CONFIG.CANDLE.FACECOLOR.bull_fall, self.CONFIG.CANDLE.EDGECOLOR.bull_fall
- Close < Open, Close < Previous Close
→ self.CONFIG.CANDLE.FACECOLOR.bear_fall, self.CONFIG.CANDLE.EDGECOLOR.bear_fall
- Close < Open, Close > Previous Close
→ self.CONFIG.CANDLE.FACECOLOR.bear_rise, self.CONFIG.CANDLE.EDGECOLOR.bear_rise
- Open == Close
→ self.CONFIG.CANDLE.EDGECOLOR.doji




##### Volume Bar Colors
- Previous Close < Current Close
→ self.CONFIG.VOLUME.FACECOLOR.rise, self.CONFIG.VOLUME.EDGECOLOR.rise
- Previous Close > Current Close
→ self.CONFIG.VOLUME.FACECOLOR.fall, self.CONFIG.VOLUME.EDGECOLOR.fall
- Previous Close == Current Close
→ self.CONFIG.VOLUME.FACECOLOR.doji, self.CONFIG.VOLUME.EDGECOLOR.doji




#### Chart.get\_cnadle\_segment(x, left, right, top, bottom, is\_up, high, low)

This method is provided to modify the appearance of candlesticks drawn on the chart.


    import pandas as pd
    import seolpyo_mplchart as mc
    
    class Chart(mc.SliderChart):
        def __init__(self, *args, **kwargs):
            super().__init__(*args, **kwargs)
            self.collection_candle.set_linewidth(1.5)
            return
    
        def get_candle_segment(self, *, x, left, right, top, bottom, is_up, high, low):
            if is_up:
                return (
                    (x, high),
                    (x, top), (right, top), (x, top),
                    (x, bottom), (left, bottom),
                    (x, bottom), (x, low), (x, high)
                )
            else:
                return (
                    (x, high),
                    (x, bottom), (right, bottom), (x, bottom),
                    (x, top), (left, top), (x, top),
                    (x, low), (x, high)
                )
    
    
    C = Chart()
    
    data = {stock price data}
    df = pd.DataFrame(data)
    
    C.set_data(df)
    
    mc.show()

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/en%20bar%20chart.png?raw=true)

### Chart.get\_info\_kwargs(is\_price, \*\*kwargs)

You can modify or add the data displayed in the text box using the get_info_kwargs method.
The **kwargs parameter receives predefined keyword arguments.

If you'd like, I can help format this as a docstring or comment for your code. For example:
Allows customization of the data shown in the text box.
Predefined keyword arguments are passed via **kwargs.


    import pandas as pd
    import seolpyo_mplchart as mc
    
    
    class Chart(mc.SliderChart):
        format_candleinfo = mc.format_candleinfo_ko + '\nCustom info: {ci}'
    
        def get_info_kwargs(self, is_price, **kwargs):
            if is_price:
                kwargs['ci'] = 'this is custom add info kwargs'
                kwargs['close'] = 'Cusotom close value'
            return kwargs
    
    C = Chart()
    data = {stock price data}
    df = pd.DataFrame(data)
    
    C.set_data(df)
    
    mc.show()

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/change%20text%20info.png?raw=true)

#### Chart.on\_draw(e)

Method called when the draw event is triggered.
Only invoked in CursorChart and SliderChart.


#### Chart.on\_resize(e)

Method called when the resize event is triggered.
Only invoked in SliderChart.


#### Chart.on\_pick(e)

Method called when the pick event is triggered.


#### Chart.on\_move(e)

Method called when a mouse movement event occurs.
Only invoked in CursorChart and SliderChart.


#### Chart.on\_click(e)

Method called when a mouse click event occurs.

Only invoked in SliderChart.

#### Chart.on\_release(e)

Method called when a mouse release event occurs.

Only invoked in SliderChart.

### CONFIG

A configuration that includes setting class objects such as FIGURE, AX, FORMAT, UNIT, CURSOR, CANDLE, VOLUME, MA, and SLIDER.


### DEFAULTCONFIG

CONFIG applied to OnlyChart and CursorChart.


### DEFAULTCONFIG\_EN

CONFIG applied to OnlyChart and CursorChart, with the price unit set to $, the volume unit set to Vol, and the formatting based on English conventions.


### SLIDERCONFIG

CONFIG applied to SliderChart.


### SLIDERCONFIG\_EN

CONFIG applied to SliderChart, with the price unit set to $, the volume unit set to Vol, and the formatting based on English conventions.

```
    # seolpyo_mplchart/_config/slider/config.py
    
    from .. import config
    from .figure import FIGURE, SliderFigureData
    from .nav import NAVIGATOR
    
    
    class SliderData:
        def __init__(self):
            self.NAVIGATOR = NAVIGATOR
    
    SLIDER = SliderData()
    
    class SliderConfigData(config.ConfigData):
        FIGURE: SliderFigureData
        SLIDER: SliderData
    
    
    SLIDERCONFIG: SliderConfigData = config.DEFAULTCONFIG
    SLIDERCONFIG.FIGURE = FIGURE
    SLIDERCONFIG.SLIDER = SLIDER
    
    SLIDERCONFIG_EN: SliderConfigData = config.DEFAULTCONFIG_EN
    SLIDERCONFIG_EN.FIGURE = FIGURE
    SLIDERCONFIG_EN.SLIDER = SLIDER
```

```
    # seolpyo_mplchart/_config/config.py
    
    from . import figure, ax, candle, volume, ma, unit, cursor, format
    
    
    class ConfigData:
        def __init__(self):
            self.FIGURE = figure.FIGURE
            self.UNIT = unit.UNIT
            self.AX = ax.AX
            self.CANDLE = candle.CANDLE
            self.VOLUME = volume.VOLUME
            self.MA = ma.MA
            self.CURSOR = cursor.CURSOR
            self.FORMAT = format.FORMAT
    
    DEFAULTCONFIG = ConfigData()
    
    DEFAULTCONFIG_EN = ConfigData()
    DEFAULTCONFIG_EN.UNIT = unit.UNIT_EN
    DEFAULTCONFIG_EN.MA = ma.MA_EN
    DEFAULTCONFIG_EN.FORMAT = format.FORMAT_EN
```
    

# Others

---

# Required data
-------

A chart object must be provided with a DataFrame that contains the following columns:
[timestamp, open, high, low, close, volume]


## How to Change Language and Text Format
The default language is Korean.
If needed, you can change the units for price and volume, and customize the text format to match your preferred style.


### How to Change Display Units

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/en%20no%20vol%20(2).png?raw=true)

The price and volume units, as well as the number of decimal places for price and volume, are managed in CONFIG.UNIT.

    from .utils import convert_unit, convert_unit_en
    # seolpyo_mplchart._config.unit.py
    
    class UnitData:
        def __init__(self):
            self.price = '원'
            self.volume = '주'
            self.digit = 0
            self.digit_volume = 0
            self.func = convert_unit
    
    UNIT = UnitData()
    
    UNIT_EN = UnitData()
    UNIT_EN.price = ' $'
    UNIT_EN.volume = ' Vol'
    UNIT_EN.digit = 2
    UNIT_EN.func = convert_unit_en
    
    

### How to Change the Information Text Format

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/en%20no%20vol%20(2).png?raw=true)![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/kor%20vol.png?raw=true)

You can customize the name of the price moving average line and the text displayed in the information box.
Text formatting is managed through CONFIG.FORMAT.
Additional kwargs for customizing the text can be passed via the chart’s get_info_kwargs method.


    # seolpyo_mplchart/_config/format.py
    
    format_candleinfo_ko = """\
    {dt}
    
    종가:　 {close}
    등락률: {rate}
    대비:　 {compare}
    시가:　 {open}({rate_open})
    고가:　 {high}({rate_high})
    저가:　 {low}({rate_low})
    거래량: {volume}({rate_volume})\
    """
    format_volumeinfo_ko = """\
    {dt}
    
    거래량:　　　 {volume}
    거래량증가율: {rate_volume}
    대비:　　　　 {compare}\
    """
    
    class FormatData:
        def __init__(self):
            self.candle = format_candleinfo_ko
            self.volume = format_volumeinfo_ko
    
    FORMAT = FormatData()
    
    format_candleinfo_en = """\
    {dt}
    
    close:      {close}
    rate:        {rate}
    compare: {compare}
    open:      {open}({rate_open})
    high:       {high}({rate_high})
    low:        {low}({rate_low})
    volume:  {volume}({rate_volume})\
    """
    format_volumeinfo_en = """\
    {dt}
    
    volume:      {volume}
    volume rate: {rate_volume}
    compare:     {compare}\
    """
    
    FORMAT_EN = FormatData()
    FORMAT_EN.candle = format_candleinfo_en
    FORMAT_EN.volume = format_volumeinfo_en
    
    

How to Change Chart Style
-----------

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/theme%20light.png?raw=true)![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/theme%20dark.png?raw=true)

Since I prefer a white background, the default chart style is set to light mode.
If you want to change the chart style, simply modify the color values defined in CONFIG.
A function named set_theme has been created to switch between light and dark themes.
You can either use this function directly, or check which values it modifies and adjust them to suit your preferences.


    import json
    
    import seolpyo_mplchart as mc
    import pandas as pd
    
    
    class Chart(mc.SliderChart):
        def __init__(self, config, *args, **kwargs):
            config = mc.set_theme(config, theme='dark')
    
    
    file = {stock price data path}
    with open(file, 'r', encoding='utf-8') as txt:
        data = json.load(txt)
    df = pd.DataFrame(data)
    
    c = Chart()
    c.set_data(df)
    
    mc.show()
    

How to Change Chart Aspect Ratio
--------

![](https://github.com/white-seolpyo/seolpyo-mplchart/blob/main/images/ratio.png?raw=true)

You can adjust the proportions of each chart area using the values of
ratio_ax_slider, ratio_ax_legend, ratio_ax_price, ratio_ax_volume, and ratio_ax_none.
Note: ratio_ax_none is only used when the value of slider_top is set to False.


    # seolpyo_mplchart/_config/slider/figure.py
    
    
    class RatioData:
        def __init__(self):
            self.legend = 2
            self.price = 18
            self.volume = 5
            self.slider = 3
            self.none = 2
    
    RATIO = RatioData()
    
    class SliderFigureData(figure.FigureData):
        def __init__(self):
            super().__init__()
            self.RATIO: RatioData = RATIO
    
    FIGURE = SliderFigureData()
