seolpyo_mplchart 사용 설명서

(11.12) 수정됨.

Donation

Bitcoin: 1MKCHW8smDZv5DFMiVkA5G3DeXcMn871ZX

 

Ethereum: 0x1c5fb8a5e0b1153cd4116c91736bd16fabf83520

 

English Document

https://github.com/white-seolpyo/seolpyo-mplchart/tree/main

 

기준버전

2.1.0

 

패키지 소개

 

40,000개 이상의 주가 정보 차트 그리기 샘플, with Intel i5 4690

 

seolpyo-mplchart는 matplotlib 기반 파이썬 패키지입니다.

파이썬을 이용해 캔들스틱 차트를 그리는데는 보통 finplot이나 plotly가 있으나, 각각의 패키지가 제가 원하는 기능들을 모두 제공하지 않았기 때문에 해당 패키지를 만들게 되었습니다.

본 패키지의 주요 특징은 다음과 같습니다.

 

주요 특징

• 3가지 유형의 Chart class를 제공합니다.
• 조회 영역을 표시하는 오버뷰 슬라이더가 제공됩니다.(SliderChart) 이를 통해 조회 영역을 선택하거나, 이동할 수 있습니다.
• 다양한 gui와 연결하여 사용할 수 있습니다. tkinter와도 연결이 가능하며, 부드럽게 동작합니다.
• 주가 정보 텍스트를 표시합니다.(CursorChart, SliderChart) 원하는 정보가 있는 경우, 해당 캔들 또는 볼륨바 위에 마우스 커서를 위치시키면 됩니다.
• 가격이동평균선의 on/off 기능을 기본적으로 제공합니다.

 

tkinter에 연결하여 캔들스틱 차트를 그리는 샘플은 다음 링크에서 확인할 수 있습니다.

tkinter 샘플 코드 확인하기

 

※ 32비트 파이썬 3.11, pandas 2.0.0, matplotlib 3.7.0 버전에서 작동하는 것을 직접 확인했습니다.

 

설치 방법

> pip install seolpyo-mplchart

 

Quick Start

OnlyChart

상호작용 없이 단순히 차트만 그리는 차트입니다.

import seolpyo_mplchart as mc

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

 

 

CursorChart

OnlyChart에서 마우스 커서와 상호작용하는 기능이 추가된 차트입니다.

마우스 커서 위치에 해당하는 날짜 정보를 차트 하단에, 가격 또는 거래량 정보를 차트 우측에 표시하며,

캔들 또는 거래량바 위에 마우스 커서가 위치하면 해당하는 정보 텍스트를 표시합니다.

import seolpyo_mplchart as mc

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

 

 

SliderChart

CursorChart에 차트 오버뷰를 제공하는 슬라이더가 추가된 차트입니다.

슬라이더를 통해 조회영역을 선택하거나, 이동할 수 있습니다. 또한 차트 영역을 클릭한 상태로 드래그하는 것으로 조회영역 이동이 가능합니다.

import seolpyo_mplchart as mc

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

 

Chart 설명

Chart 클래스 인자

CONFIG

차트 설정 파일

전달하지 않는 경우 사전에 정의된 CONFIG*를 사용합니다.

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

 

Chart 클래스 변수

watermark

차트 중앙에 출력되는 워터마크 텍스트. if not self.watermark가 참일시 워터마크를 그리지 않습니다.

 

candle_on_ma

참인 경우 캔들을 이동평균선 위에 그립니다. 거짓인 경우에는 다음 이미지와 같이 캔들을 이동평균선 아래에 그립니다.

 

limit_candle

화면에 그리는 캔들의 수가 이보다 작거나 같으면 캔들을, 크면 심지만 그립니다.

 

limit_wick

화면에 그리는 캔들의 수가 이보다 작거나 같으면 심지를, 크면 선형 차트를 그립니다.

 

limit_volume

화면에 그리는 캔들의 수가 self.limit_wick보다 작거나 같으면 전체 거래량을, 크면 일부 거래량만 그립니다.

일부만 그리는 경우, 거래량 내림차순 기준 상위 limit_volume개수만큼 그립니다.

넓은 범위 선택 후 이동시 버퍼링이 있다면 이 값을 낮게 설정하면 속도가 개선될 수 있습니다.

Slider 차트에서 차트 이동 중에만 적용됩니다.

limit_ma

화면에 그리는 캔들의 수가 이보다 작거나 같으면 이동평균선을 그립니다.

넓은 범위 선택 후 이동시 버퍼링이 있다면 이 값을 낮게 설정하면 속도가 개선될 수 있습니다.

Slider 차트에서 차트 이동 중에만 적용됩니다.

 

key_date, key_open, key_high, key_low, key_close, key_volume

전달하는 data에서 사용하는 각 column의 key

Chart.set_data(df) 실행 시점에 if not self.key_volume이 참이면 거래량 차트를 그리지 않습니다.

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()

 

fraction

참인 경우 소수점 이하를 분수로 표시합니다.

 

slider_top

참인 경우 슬라이더를 차트 위에 배치합니다.

 

min_distance

슬라이더 영역 선택시 선택해야하는 최소 캔들 수

이보다 작은 영역을 선택하면 이전 영역을 유지합니다.

 

in_chart

마우스 커서가 주가 또는 거래량 차트 영역에 있는지 구분

 

in_slider

마우스 커서가 슬라이더 영역에 있는지 구분

 

in_price_chart

마우스 커서가 주가 차트 영역에 있는지 구분

 

in_volume_chart

마우스 커서가 거래량 차트 영역에 있는지 구분

 

Chart 클래스 메소드

Chart.__init__(config=DEFAULTCONFIG or SLIDERCONFIG)

차트 오브젝트를 생성합니다.

 

Chart.set_data(df, change_xlim=True)

차트 오브젝트에 주가 데이터를 전달합니다.

차트 오브젝트는 전달받은 데이터를 기반으로 차트 데이터를 생성합니다.

DataFrame에서 데이터를 가져올 때 사전에 정의된 Chart.key_date, Chart.key_open, Chart.key_high, Chart.key_low, Chart.key_close, Chart.key_volume를 사용하기 때문에 set_data 사용 전에 키를 적절하게 변경해야 합니다.

if change_lim이 참이면 set_data시 Chart.get_default_lim()의 값을 가져와 xlim을 변경합니다.

 

Chart.get_default_xlim()

Chart.set_data()시 설정하는 xlim 값을 가져옵니다.

 

Chart.refresh()

차트를 새로고침합니다.

새로고침시 self.CONFIG의 변경 내용을 반영합니다.

 

Chart.add_artists()

차트에 사용되는 Artist를 추가하는 함수. init시 호출

 

Chart.draw_chart()

차트 기본 요소를 그리는 함수.on_darw 이벤트 발생시 호출

차트 이동 중에도 호출됩니다.

 

Chart.draw_artists()

차트에 Artist를 그리는 함수. on_draw 이벤트 발생시 호출

차트 이동 중에는 호출되지 않습니다.

 

Chart.set_artists()

차트 Artist들의 설정을 반영하는 함수. refresh시 호출

 

Chart.set_collections()

차트 캔들과 거래량 Artist의 설정을 반영하는 함수. refresh 또는 표시영역 변경시시 호출

 

Chart.add_candle_color_column(), Chart.add_volume_color_column()

차트에 그려지는 캔들과 거래량 바의 색상을 결정하는 method입니다.

self.df에 ['facecolor', 'edgecolor'] 칼럼과 ['facecolor_volume', 'edgecolor_volume'] 칼럼을 각각 추가합니다.

이 칼럼의 값을 변경하면 원하는 색상을 설정할 수 있습니다.

 

캔들 색상

시가 < 종가, 전일 종가 < 종가 : self.CONFIG.CANDLE.FACECOLOR.bull_rise, self.CONFIG.CANDLE.EDGECOLOR.bull_rise

시가 < 종가, 전일 종가 > 종가 : self.CONFIG.CANDLE.FACECOLOR.bull_fall, self.CONFIG.CANDLE.EDGECOLOR.bull_fall

종가 < 시가, 종가 < 전일 종가: self.CONFIG.CANDLE.FACECOLOR.bear_fall, self.CONFIG.CANDLE.EDGECOLOR.bear_fall

종가 < 시가, 종가 > 전일 종가 : self.CONFIG.CANDLE.FACECOLOR.bear_rise, self.CONFIG.CANDLE.EDGECOLOR.bear_rise

시가 == 종가 : self.CONFIG.CANDLE.EDGECOLOR.doji

 

거래량 바 색상

전일 종가 < 종가 : self.CONFIG.VOLUME.FACECOLOR.rise, self.CONFIG.VOLUME.EDGECOLOR.rise

전일 종가 > 종가 : self.CONFIG.VOLUME.FACECOLOR.fall, self.CONFIG.VOLUME.EDGECOLOR.fall

전일 종가 == 종가 : self.CONFIG.VOLUME.FACECOLOR.doji, self.CONFIG.VOLUME.EDGECOLOR.doji

 

Chart.get_cnadle_segment(x, left, right, top, bottom, is_up, high, low)

차트의 그려지는 캔들 모양을 변경하기 위해 제공되는 method입니다.

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)
        self.get_candle_segment = self.get_bar_segment
        return

C = Chart()

data = {stock price data}
df = pd.DataFrame(data)

C.set_data(df)

mc.show()

 

 

Chart.get_info_kwargs(is_price, **kwargs)

"get_info_kwargs" mehod를 통해 텍스트 박스에 표시되는 데이터를 변경하거나, 추가할 수 있습니다.

**kwargs에는 사전에 설정된 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()

 

 

Chart.on_draw(e)

draw 이벤트 발생시 호출되는 method

CursorChart, SliderChart에서만 호출됩니다.

 

Chart.on_resize(e)

resize 이벤트 발생시 호출되는 method

SliderChart에서만 호출됩니다.

 

Chart.on_pick(e)

pick 이벤트 발생시 호출되는 method

 

Chart.on_move(e)

마우스 이동 시 이벤트 발생시 호출되는 method

CursorChart, SliderChart에서만 호출됩니다.

 

Chart.on_click(e)

마우스 클릭시 이벤트 발생시 호출되는 method

SliderChart에서만 호출됩니다.

 

Chart.on_release(e)

마우스 클릭 해제시 이벤트 발생시 호출되는 method

SliderChart에서만 호출됩니다.

 

CONFIG

FIGURE, AX, FORMAT, UNIT, CURSOR, CANDLE, VOLUME, MA, SLIDER 등의 설정 class object가 존재하는 설정.

 

DEFAULTCONFIG

OnlyChart, CursorChart에 적용되는 CONFIG

 

DEFAULTCONFIG_EN

OnlyChart, CursorChart에 적용되는 CONFIG, 주가 단위에 $, 거래량 단위에 Vol가 설정되어있으며, FORMAT이 영문을 기준으로 작성되어 있습니다.

 

SLIDERCONFIG

SliderChart에 적용되는 CONFIG

 

SLIDERCONFIG_EN

SliderChart에 적용되는 CONFIG, 주가 단위에 $, 거래량 단위에 Vol가 설정되어있으며, FORMAT이 영문을 기준으로 작성되어 있습니다.

 

# seolpyo_mplchart/_config/slider/config.py

from .. import config
from .figure import FIGURE, SliderFigureData
from .nav import NAV


class SliderData:
    def __init__(self):
        self.NAV = NAV

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

 

그 외

필요한 데이터

차트 오브젝트는 반드시 [기준시간, 시가, 고가, 저가, 종가, 거래량] column을 보유한 DataFrame을 전달해야 합니다.

 

언어와 텍스트 포맷 변경방법

언어는 기본적으로 한글을 사용합니다.
만약 필요한 경우, 가격과 거래량 단위를 변경할 수 있고, 표시되는 텍스트의 포맷을 원하는 형식의 문구로 변경할 수 있습니다.

 

표시 단위 변경방법

 

가격과 거래량 단위, 주가와 거래량의 소수점 표시 수는 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

 

정보 텍스트 포맷 변경방법

 

가격이동평균선의 명칭과 표시되는 텍스트 박스의 문구를 변경할 수 있습니다.
텍스트 포맷 설정은 CONFIG.FORMAT에서 관리됩니다.

문구에 전달할 kwargs는 Chart의 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

 

차트 스타일 변경하기

 

제가 하얀 바탕의 배경을 좋아하기 때문에 차트의 기본 스타일은 밝습니다.
만약 차트 스타일을 변경하고 싶다면 CONFIG에 설정된 색상 값을 변경하면 됩니다.

CONFIG 설정을 light 테마와 dark 테마로 변경할 수 있는 set_theme이라는 함수를 작성해두었으니 이를 사용하거나, 해당 함수에서 어떤 값을 변경하는지 확인하고 취향에 맞게 변경해서 사용하면 됩니다.

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()

 

차트 비율 변경

 

"ratio_ax_slider", "ratio_ax_legend", "ratio_ax_price", "ratio_ax_volume", "ratio_ax_none"의 값을 통해 각 차트 영역의 비율을 변경할 수 있습니다.
"ratio_ax_none"은 "slider_top"의 값이 거짓일 때만 사용됩니다.

# seolpyo_mplchart/_config/slider/figure.py


class RatioData:
    def __init__(self):
        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()