Annotating Charts and Adding Labels in mplfinance

When it comes to visualizing stock market data, mplfinance is one of the most efficient Python libraries for creating such plots. Beyond just showcasing candlestick charts or line plots, a key aspect of financial plotting is providing context through annotations and labels. These not only help in understanding the chart better but also highlight specific points or patterns within the data.

Introduction to Annotations and Labels

In any data visualization, annotations and labels help interpret the data. In the context of financial data, you might want to highlight trades, mark significant events, or simply label certain key indicators. Mplfinance makes this possible through methods to annotate charts and add labels effectively.

Getting Started with mplfinance

Before we start annotating, let's ensure you have mplfinance installed. To install mplfinance, execute the following command in your terminal:

pip install mplfinance

Let's create a simple candlestick chart using mplfinance, and then proceed to add annotations.

import mplfinance as mpf
import pandas as pd

data = pd.read_csv('your_stock_data.csv', index_col=0, parse_dates=True)

mpf.plot(data, type='candle', style='charles')

Annotating the Chart

With our basic plot set up, the goal is to add annotations. Using the addplot parameter, we can specify what extra plotting elements we’d like to add to our chart.

Consider that we want to highlight a buy signal on a specific date:

import mplfinance as mpf
from matplotlib import dates

highlight = [pd.Timestamp('2023-01-13')]

apdict = mpf.make_addplot(
    data.loc[highlight, 'Low']-1,
    scatter=True,
    markersize=100,
    marker='^',
    color='green'
)

mpf.plot(data, type='candle', style='charles', addplot=apdict)

This snippet highlights a buy signal just below the candle's low point, marked with a green upwards triangle.

Creating Text Annotations

To add textual annotations, such as depicting news events that might have caused major price movements, you can use the annotate function. Below is an example of annotating a major event:

import matplotlib.pyplot as plt

fig, axlist = mpf.plot(data, type='candle', style='charles', returnfig=True)
axlist[0].annotate(
    'Major Event',
    xy=(dates.datestr2num('2023-01-13'), data.loc['2023-01-13']['High'] + 3),
    xytext=(5, -40),
    textcoords='offset points',
    arrowprops=dict(facecolor='black', shrink=0.05)
)
plt.show()

In the example above, an arrow points to the event’s occurrence, labeling it as a "Major Event".

Adding Titles and Labels

Titling your charts and labeling axes make the graph readable and informative. Adding a title in mplfinance can be directly done when calling the plot function, like so:

mpf.plot(data, type='candle', style='charles', title='Stock XYZ Price Movement', ylabel='Price', ylabel_lower='Volume')

You can set the main title text along with y-axis labels both for the price and volume subplots.

Practical Example

Combine the components into a more practical example where both annotations and labels are used together, illustrating a historical point of interest on a stock's performance:

highlight_dates = [pd.Timestamp('2023-01-06'), pd.Timestamp('2023-01-13')]
markers = ['<', '^']
texts = ['Analyst Buy Recommendation', 'Great Quarterly Report']

add_plots = []
for i, date in enumerate(highlight_dates):
    add_plots.append(mpf.make_addplot(
        data.loc[date, 'Low']-1,
        scatter=True,
        markersize=50,
        marker=markers[i],
        color='blue' if i == 0 else 'green'
    ))

fig, axlist = mpf.plot(data, type='candle', style='charles', title='Annotated Stock Movements', ylabel='Price', addplot=add_plots, returnfig=True)

for i, date in enumerate(highlight_dates):
    axlist[0].annotate(
        texts[i],
        xy=(dates.datestr2num(date.strftime('%Y-%m-%d')), data.loc[date, 'Low']-2),
        xytext=(-70, -30),
        textcoords='offset points',
        arrowprops=dict(facecolor='black' if i == 0 else 'green', shrink=0.05),
        fontsize=8
    )

plt.show()

This complete example illustrates a multidimensional annotation scenario, perfect for real-world data exploration and interpretation, revealing the power and flexibility of using annotations and labels in mplfinance.