candlesticks_help.txt

This package creates so called candlestick plots. See here for examples:
http://gnuplot.sourceforge.net/demo_5.4/finance.html

Candlesticks are used to plot financial data. The height of the candlestick is
the difference between the opening and closing price, and is called "body".
Above and below the body are the "shadows" that indicate the maximum and
minimum price at observation t. If the opening price is lower than the closing
price, the body is white (in a monochrome plot) or green (in a color plot). If
the opening price is higher than the closing price, the body is black or red.
For more: https://en.wikipedia.org/wiki/Candlestick_chart

The data frequency must be a time-series with daily observations (5, 6 or 7 days
week). If one of the passed series includes missing values for the t-th
observation, this observation is ignored for plotting.

Please ask questions and report bugs on the gretl mailing list if possible.
Alternatively, create an issue ticket on the github repo (see below). Source
code and test script(s) can be found here:
https://github.com/atecon/candlesticks


Usage via the GUI
=================
As a user you can either call the main function via scripting (see below) or
the GUI. The menu entry is "View->Graph specified vars->Candlesticks plot". The
user has to pass a list with series in expected order: Open, Close, High, Low.
An optionally last item can refer to trade volume.

If you pass the optional 5th volume series, this is shown in a separate chart
below the candlestick plot.

Via scripting the user can control many more details as shown below.


PUBLIC FUNCTION:

-----------------------------------------------------------------------
Function:       plot_candlesticks(list L, bundle self)

Description:    Main function for creating chart

Arguments: list L: Mandatory list of series in expected order: Open, Close, Low,
High. A fifth series referring to trade volume is optional. Once added, it will
be plotted in a subplot.

bundle self: Optional parameters for controlling the chart. You can pass the
following parameters:

    show_colors:        bool, Plot colored chart (default: FALSE)
    filename:           string, Filename to store chart (default: empty)
    rotate_xtics:       scalar, Rotate x-labels by rotate_xtics degrees
                        (default: 0)
    title:              string, Set title of chart (default: "")
    number_of_xtics:    int, Show only every number_of_xtics xtic label
                        (default: 7)

Return: Nothing.
-----------------------------------------------------------------------


Changelog:
- v1.1, November 2022
    + Fix bug with volume color
    + Internal improvements
- v1.0, August 2022
    + initial release