Charts.css.py Online Document

Introduction

Project charts.css.py provides a python API to convert your 2-dimension data lists into html snippet, which will be rendered into charts when serving inside a browser. Characteristic:

Once the html snippet is delivered into the browser window, the rendering is done by CSS, which is typically faster than JS-heavy chart libraries.
The output of charts.css.py is a normal HTML table. Search engines and screen readers will be able to consume your data even when CSS rendering is unavailable.
Since the output is normal HTML, you could further customize its size and position.

charts.css.py is built on top of its upstream project Charts.css.

Hello World

Let's start this document with a simple sample. Our first sample shows the basic usage pattern, visualizing single dataset with default effect. You still need to organize your single dataset as a 2-dimension list.

Loading......

Installation

If you are working on a normal Python project, you can install by pip:

pip install charts.css.py

If your project is powered by Brython, you can choose to use our JS package. For example, this online document is using this javascript file, hosted in our Github Release page:


<script src="https://github.com/rayluo/charts.css.py/releases/download/x.y.z/charts.css.py-brython.js"></script>

Configuration

First of all, insert this snippet into your html page, typically inside the <head>...</head> tag:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/charts.css/dist/charts.min.css">
<style>
.charts-css {  /* You have to use this class name */
  height: 400px;  /* Most charts need some height to operate */
  width: 80%;  /* Optional */
  margin: 1em auto;  /* Optional */
}
.charts-css.legend.legend-inline {  /* You have to use this class name */
  height: 3em;  /* Optional */
}
</style>

Data Format

All chart functions in charts.css.py have a unified data format as a 2-dimension list, optionally with headers in the first column and/or first row. They look like this:

data = [
    ["Continent", "1st year", "2nd year", "3rd year", "4th year", "5th year"],
    ["Asia", 20.0, 30.0, 40.0, 50.0, 75.0],
    ["Euro", 40.0, 60.0, 75.0, 90.0, 100.0],
    ]

Even when you are working with one-dimension data, you would still need to format them as 2-dimension list, which contains one column:

data = [
    [20.0],
    [40.0],
    ]

Some charts can also work with one row:

data = [
    [20.0, 30.0, 40.0, 50.0, 75.0],
    ]

Crash Course

2-dimension data

All chart functions in charts.css.py have a unified data format as a 2-dimension list, optionally with headers in the first column and/or first row. The following sample has a 2-dimension list which contains real 2-dimension numeric data, and then renders them as 4 different kind of charts.

Here come the different charts generated by the snippet above. Get yourself familiar with their common characteristics:

When the input contains 2 or more columns of numeric data, each column is treated as one dataset and rendered in one color.
Column headers (which are in the first data row) will show up as legends.
Row headers (which are in the first data column) will show up as labels along the chart's primary axis.

In a bar chart, the labels in primary axis also runs downward, same as their order in the raw data.

Loading......

Think a column chart as a bar chart being rotated 90 degrees counterclockwise.

Loading......

In a line chart, each numeric column in the 2-dimension raw data will be rendered as a line.

Loading......

Area chart is line chart being filled with color between each line and the primary axis. Generally, we would not want to use area chart when handling multiple numeric columns.

Loading......

1-dimension horizontal

Sometimes you are dealing with 1-dimension numeric data. You will have 2 options to organize your data: pack them as either a 1 horizontal row or 1 vertical column into the 2-dimension list.

This sample is showing the outcome of 1 horizontal row.

In such a one-dimension horizontal numeric data scenario, bar chart will look similar to the previous bar chart. It is just that its primary axis contains only one data point, and righfully so.

Loading......

Column chart also looks as a rotated bar chart, and still looks good.

Loading......

Line chart has no enough data points to show lines. So you probably won't want to create a line chart this way.

Loading......

Area chart generated by multiple numeric columns is still not recommended.

Loading......

1-dimension vertical

When your 2-dimension list contains only 1 vertical column of numeric data, charts.css.py will treat it as one dataset with multiple data points.

Bar chart will be rendered differently:

Since there is only one column but there are many rows, the colors will be applied on the rows rather than columns.
There is only one column to be shown as legend, and its legend color does not mean anything, and is even misleading. We still demonstrate a legend in this sample, but the better approach is to use heading instead of legend here.

Loading......

The column chart still looks like a rotated bar chart. Here we choose to show its heading rather than its legend.

Loading......

There will be enough enough data points to draw one line. And the color of its legend is also correct, although not really meaningful.

Loading......

The "1 vertical column of numeric data" is probably the only case that an area chart would look nice.

Loading......

Transpose

The above 2 sections tell us that the 2-dimension data would be rendered differently, based on which dimension is organized as a row or as a column. Sometimes our raw data is already in one shape, but we may want to "flip" their row and column, i.e. "flip" their x-axis and y-axis, for them to be rendered to a chart that we want. How do we achieve that?

We got you covered. That "flipping x-axis and y-axis" is also known as "to transpose a matrix" in math. So, charts.css.py provides a transpose(...). In particular, the following sample shows how to convert a "horizontally wide and vertically short" list of numeric data into a "horizontally narrow but vertically long" 2-dimension list, and render them as line chart.

Loading......

Stacked charts

bar() and column() support a boolean parameter stacked. Simply enable that, you will get a stacked bar chart (or column chart). A percentage=True can switch stacked column or bar chart to percentage view.

The sample below is stacked by value.

Loading......

The sample below is stacked by percentage.

Loading......

Customization

We have demonstrated some options so far. There are more. This sample shows how to customize: value representation, value appearance, whether shown when hover, secondary axes, spacing, ... Most of these options are applicable to all chart types.

Loading......

Reading from .csv file

Our input data format is a 2-dimension list, so it is easy to consume data from a .csv source file, such as this one. In fact, if you ever wonder why charts.css.py's line chart and area chart are designed to consume a "1-dimension vertical" matrix rather than a "1-dimension horizontal" matrix, it is roughly because the tall-and-thin, vertically-scrolling layout is more prevalent in CSV.

Loading......