plottoolbox.plottoolbox.bar

plottoolbox.plottoolbox.bar(input_ts='-', columns=None, start_date=None, end_date=None, clean=False, skiprows=None, index_type='datetime', names=None, ofilename='plot.png', xtitle='', ytitle='', title='', figsize='10,6.0', legend=None, legend_names=None, colors='auto', linestyles='auto', markerstyles=' ', bar_hatchstyles='auto', style='auto', xaxis='arithmetic', yaxis='arithmetic', xlim=None, ylim=None, grid=False, label_rotation=None, label_skip=1, force_freq=None, por=False, invert_xaxis=False, invert_yaxis=False, round_index=None, dropna='all', source_units=None, target_units=None, plot_styles='bright', hlines_y=None, hlines_xmin=None, hlines_xmax=None, hlines_colors=None, hlines_linestyles='-', vlines_x=None, vlines_ymin=None, vlines_ymax=None, vlines_colors=None, vlines_linestyles='-', **kwds)

[category index, N columns] Bar plot, sometimes called a “column” plot.

“bar” make a bar or column plot.

Parameters:

  • input_ts (str) –

    [optional though required if using within Python, default is ‘-’ (stdin)]

    Whether from a file or standard input, data requires a single line header of column names. The default header is the first line of the input, but this can be changed for CSV files using the ‘skiprows’ option.

    Most common date formats can be used, but the closer to ISO 8601 date/time standard the better.

    Comma-separated values (CSV) files or tab-separated values (TSV):

    File separators will be automatically detected.

Columns can be selected by name or index, where the index for
data columns starts at 1.

    Command line examples:

    Keyword Example

    Description

    –input_ts=fn.csv

    read all columns from ‘fn.csv’

    –input_ts=fn.csv,2,1

    read data columns 2 and 1 from ‘fn.csv’

    –input_ts=fn.csv,2,skiprows=2

    read data column 2 from ‘fn.csv’, skipping first 2 rows so header is read from third row

    –input_ts=fn.xlsx,2,Sheet21

    read all data from 2nd sheet all data from “Sheet21” of ‘fn.xlsx’

    –input_ts=fn.hdf5,Table12,T2

    read all data from table “Table12” then all data from table “T2” of ‘fn.hdf5’

    –input_ts=fn.wdm,210,110

    read DSNs 210, then 110 from ‘fn.wdm’

    –input_ts=’-’

    read all columns from standard input (stdin)

    –input_ts=’-’ –columns=4,1

    read column 4 and 1 from standard input (stdin)

    If working with CSV or TSV files you can use redirection rather than use –input_ts=fname.csv. The following are identical:

    From a file:

    command subcmd –input_ts=fname.csv

    From standard input (since ‘–input_ts=-’ is the default:

    command subcmd < fname.csv

    Can also combine commands by piping:

    command subcmd < filein.csv | command subcmd1 > fileout.csv

    Python library examples:

    You must use the `input_ts=...` option where `input_ts` can be
one of a [pandas DataFrame, pandas Series, dict, tuple, list,
StringIO, or file name].

  • columns –

    [optional, defaults to all columns, input filter]

    Columns to select out of input. Can use column names from the first line header or column numbers. If using numbers, column number 1 is the first data column. To pick multiple columns; separate by commas with no spaces. As used in toolbox_utils pick command.

    This solves a big problem so that you don’t have to create a data set with a certain column order, you can rearrange columns when data is read in.

  • start_date (str) –

    [optional, defaults to first date in time-series, input filter]

    The start_date of the series in ISOdatetime format, or ‘None’ for beginning.

  • end_date (str) –

    [optional, defaults to last date in time-series, input filter]

    The end_date of the series in ISOdatetime format, or ‘None’ for end.

  • clean –

    [optional, default is False, input filter]

    The ‘clean’ command will repair a input index, removing duplicate index values and sorting.

  • skiprows (list-like or integer or callable) –

    [optional, default is None which will infer header from first line, input filter]

    Line numbers to skip (0-indexed) if a list or number of lines to skip at the start of the file if an integer.

    If used in Python can be a callable, the callable function will be evaluated against the row indices, returning True if the row should be skipped and False otherwise. An example of a valid callable argument would be

    lambda x: x in [0, 2].

  • index_type (str) –

    [optional, default is ‘datetime’, output format]

    Can be either ‘number’ or ‘datetime’. Use ‘number’ with index values that are Julian dates, or other epoch reference.

  • names (str) –

    [optional, default is None, transformation]

    If None, the column names are taken from the first row after ‘skiprows’ from the input dataset.

    MUST include a name for all columns in the input dataset, including the index column.

  • ofilename (str) –

    [optional, defaults to ‘plot.png’]

    Output filename for the plot. Extension defines the type, for example ‘filename.png’ will create a PNG file.

    If used within Python, and ofilename is None will return the Matplotlib figure that can then be changed or added to as needed.

  • xtitle (str) –

    [optional, default depends on type]

    Title of x-axis.

  • ytitle (str) –

    [optional, default depends on type]

    Title of y-axis.

  • title (str) –

    [optional, defaults to ‘’]

    Title of chart.

  • figsize (str) –

    [optional, defaults to ‘10,6.5’]

    The ‘width,height’ of plot in inches.

  • legend (bool) –

    [optional, default is True]

    Whether to create a legend or not.

  • legend_names –

    [optional, default is None]

    If the default of None will take legend names from columns tiles in the input dataset. Otherwise will take names from the legend_names list.

  • colors –

    [optional, default is ‘auto’]

    The default ‘auto’ will cycle through matplotlib colors in the chosen style.

    At the command line supply a comma separated matplotlib color codes, or within Python a list of color code strings.

    Can identify colors in four different ways.

    1. Use ‘CN’ where N is a number from 0 to 9 that gets the Nth color from the current style.

    2. Single character code from the table below.

    Code

    Color

    b

    blue

    g

    green

    r

    red

    c

    cyan

    m

    magenta

    y

    yellow

    k

    black

    3. Number between 0 and 1 that represents the level of gray, where 0 is white an 1 is black.

    4. Any of the HTML color names.

    HTML Color Names

    red

    burlywood

    chartreuse

    …etc.

    Color reference: http://matplotlib.org/api/colors_api.html

  • linestyles –

    [optional, default to ‘auto’]

    If ‘auto’ will iterate through the available matplotlib line types. Otherwise on the command line a comma separated list, or a list of strings if using the Python API.

    To not display lines use a space (’ ‘) as the linestyle code.

    Separated ‘colors’, ‘linestyles’, and ‘markerstyles’ instead of using the ‘style’ keyword.

    Code

    Lines

    -

    solid

    –

    dashed

    -.

    dash_dot

    :

    dotted

    None

    draw nothing

    ’ ‘

    draw nothing

    ’’

    draw nothing

    Line reference: http://matplotlib.org/api/artist_api.html

  • markerstyles –

    [optional, default to ‘ ‘]

    The default ‘ ‘ will not plot a marker. If ‘auto’ will iterate through the available matplotlib marker types. Otherwise on the command line a comma separated list, or a list of strings if using the Python API.

    Separated ‘colors’, ‘linestyles’, and ‘markerstyles’ instead of using the ‘style’ keyword.

    Code

    Markers

    .

    point

    o

    circle

    v

    triangle down

    ^

    triangle up

    <

    triangle left

    >

    triangle right

    1

    tri_down

    2

    tri_up

    3

    tri_left

    4

    tri_right

    8

    octagon

    s

    square

    p

    pentagon

    *

    star

    h

    hexagon1

    H

    hexagon2

    +

    plus

    x

    x

    D

    diamond

    d

    thin diamond

    _

    hline

    None

    nothing

    ’ ‘

    nothing

    ’’

    nothing

    Marker reference: http://matplotlib.org/api/markers_api.html

  • bar_hatchstyles –

    [optional, default to “auto”, only used if type equal to “bar”, “barh”, “bar_stacked”, and “barh_stacked”]

    If ‘auto’ will iterate through the available matplotlib hatch types. Otherwise on the command line a comma separated list, or a list of strings if using the Python API.

    bar_hatchstyles

    Description

    /

    diagonal hatching

    \

    back diagonal

    |

    vertical

    -

    horizontal

    +

    crossed

    x

    crossed diagonal

    o

    small circle

    O

    large circle

    .

    dots

    *

    stars

  • style –

    [optional, default is None]

    Still available, but if None is replaced by ‘colors’, ‘linestyles’, and ‘markerstyles’ options. Currently the ‘style’ option will override the others.

    Comma separated matplotlib style strings per time-series. Just combine codes in ‘ColorMarkerLine’ order, for example ‘r*–’ is a red dashed line with star marker.

  • xaxis (str) –

    [optional, default is ‘arithmetic’]

    Defines the type of the xaxis. One of ‘arithmetic’, ‘log’.

  • yaxis (str) –

    [optional, default is ‘arithmetic’]

    Defines the type of the yaxis. One of ‘arithmetic’, ‘log’.

  • xlim –

    [optional, default is based on range of x values]

    Comma separated lower and upper limits for the x-axis of the plot. For example, ‘–xlim 1,1000’ would limit the plot from 1 to 1000, where ‘–xlim ,1000’ would base the lower limit on the data and set the upper limit to 1000.

  • ylim –

    [optional, default is based on range of y values]

    Comma separated lower and upper limits for the y-axis of the plot. See xlim for examples.

  • grid –

    [optional, default is False]

    Whether to plot grid lines on the major ticks.

  • label_rotation (int) –

    [optional]

    Rotation for major labels for bar plots.

  • label_skip (int) –

    [optional]

    Skip for major labels for bar plots.

  • force_freq (str) –

    [optional, output format]

    Force this frequency for the output. Typically you will only want to enforce a smaller interval where toolbox_utils will insert missing values as needed. WARNING: you may lose data if not careful with this option. In general, letting the algorithm determine the frequency should always work, but this option will override. Use PANDAS offset codes.

  • por –

    [optional]

    Plot from first good value to last good value. Strips NANs from beginning and end.

  • invert_xaxis –

    [optional, default is False]

    Invert the x-axis.

  • invert_yaxis –

    [optional, default is False]

    Invert the y-axis.

  • round_index –

    [optional, default is None which will do nothing to the index, output format]

    Round the index to the nearest time point. Can significantly improve the performance since can cut down on memory and processing requirements, however be cautious about rounding to a very course interval from a small one. This could lead to duplicate values in the index.

  • dropna (str) –

    [optional, defauls it ‘no’, input filter]

    Set dropna to ‘any’ to have records dropped that have NA value in any column, or ‘all’ to have records dropped that have NA in all columns. Set to ‘no’ to not drop any records. The default is ‘no’.

  • source_units (str) –

    [optional, default is None, transformation]

    If unit is specified for the column as the second field of a ‘:’ delimited column name, then the specified units and the ‘source_units’ must match exactly.

    Any unit string compatible with the ‘pint’ library can be used.

  • target_units (str) –

    [optional, default is None, transformation]

    The purpose of this option is to specify target units for unit conversion. The source units are specified in the header line of the input or using the ‘source_units’ keyword.

    The units of the input time-series or values are specified as the second field of a ‘:’ delimited name in the header line of the input or in the ‘source_units’ keyword.

    Any unit string compatible with the ‘pint’ library can be used.

    This option will also add the ‘target_units’ string to the column names.

  • plot_styles (str) –

    [optional, default is “default”]

    Set the style of the plot. One or more of Matplotlib styles “classic”, “Solarize_Light2”, “bmh”, “dark_background”, “fast”, “fivethirtyeight”, “ggplot”, “grayscale”, “seaborn”, “seaborn-bright”, “seaborn-colorblind”, “seaborn-dark”, “seaborn-dark-palette”, “seaborn-darkgrid”, “seaborn-deep”, “seaborn-muted”, “seaborn-notebook”, “seaborn-paper”, “seaborn-pastel”, “seaborn-poster”, “seaborn-talk”, “seaborn-ticks”, “seaborn-white”, “seaborn-whitegrid”, “tableau-colorblind10”, and

    The main SciencePlots styles are “science”, “grid”, “ieee”, “scatter”, “notebook”, “high-vis”, “bright”, “vibrant”, “muted”, and “retro”.

    Other SciencPlots styles that are less common or intended to modify other styles are, “cjk-jp-font.mplstyle”, “cjk-kr-font.mplstyle”, “cjk-sc-font.mplstyle”, “cjk-tc-font.mplstyle”, “high-contrast.mplstyle”, “latex-sans.mplstyle”, “light.mplstyle”, “nature.mplstyle”, “no-latex.mplstyle”, “pgf.mplstyle”, “russian-font.mplstyle”, and “std-colors.mplstyle”.

    If multiple styles then each over rides some or all of the characteristics of the previous.

    Color Blind Appropriate Styles

    The styles “seaborn-colorblind”, “tableau-colorblind10”, “bright”, “vibrant”, and “muted” are all styles that are setup to be able to be distinguished by someone with color blindness.

    Black, White, and Gray Styles

    The “ieee” style is appropriate for black, white, and gray, however the “ieee” also will change the chart size to fit in a column of the “IEEE” journal.

    The “grayscale” is another style useful for photo-copyable black, white, nd gray.

    Matplotlib styles: https://matplotlib.org/3.3.1/gallery/style_sheets/style_sheets_reference.html

    SciencePlots styles: https://github.com/garrettj403/SciencePlots

  • hlines_y –

    [optional, defaults to None]

    Number or list of y values where to place a horizontal line.

  • hlines_xmin –

    [optional, defaults to None]

    List of minimum x values to start the horizontal line. If a list must be same length as hlines_y. If a single number will be used as the minimum x values for all horizontal lines. A missing value or None will start at the minimum x value for the entire plot.

  • hlines_xmax –

    [optional, defaults to None]

    List of maximum x values to end each horizontal line. If a list must be same length as hlines_y. If a single number will be the maximum x value for all horizontal lines. A missing value or None will end at the maximum x value for the entire plot.

  • hlines_colors –

    [optional, defaults to None]

    List of colors for the horizontal lines. If a single color then will be used as the color for all horizontal lines. If a list must be same length as hlines_y. If None will take from the color pallette in the current plot style.

  • hlines_linestyles –

    [optional, defaults to None]

    List of linestyles for the horizontal lines. If a single linestyle then will be used as the linestyle for all horizontal lines. If a list must be same length as hlines_y. If None will take for the standard linestyles list.

  • vlines_x –

    [optional, defaults to None]

    List of x values where to place a vertical line.

  • vlines_ymin –

    [optional, defaults to None]

    List of minimum y values to start the vertical line. If a list must be same length as vlines_x. If a single number will be used as the minimum x values for all vertical lines. A missing value or None will start at the minimum x value for the entire plot.

  • vlines_ymax –

    [optional, defaults to None]

    List of maximum x values to end each vertical line. If a list must be same length as vlines_x. If a single number will be the maximum x value for all vertical lines. A missing value or None will end at the maximum x value for the entire plot.

  • vlines_colors –

    [optional, defaults to None]

    List of colors for the vertical lines. If a single color then will be used as the color for all vertical lines. If a list must be same length as vlines_x. If None will take from the color pallette in the current plot style.

  • vlines_linestyles –

    [optional, defaults to None]

    List of linestyles for the vertical lines. If a single linestyle then will be used as the linestyle for all vertical lines. If a list must be same length as vlines_x. If None will take for the standard linestyles list.