Bar

Turning quantitative values into geometric shapes.

Overview

Novem offers 16 types of barcharts but they can be categorized into three main archetypes:

  • bar - reguar barchart
  • sbar - stacked barchart
  • gbar - grouped barchart

In addition to the above there is a special aggregate barchart, abar, which will be explained in detail below.

To accomodate horizontal as well as top/bottom anchoring novem further expands the barcharts with two subcategories, horizontal and inverted.

By prepending one of the above type with either h, i or both you can tell the bars to be anchored to the left side h, or right side ih. In addition to anchor a bart to the top (making it “grow” down) just appned i to the regular type. e.g. ibar

Below is a comprehensive list of possible barchart types.

/vis/plots/<name>/type

Regular  Horizontal  Inverted  Inverted Horizontal
-------  ----------  --------  -------------------
bar      hbar        ibar      ihbar
sbar     hsbar       isbar     ihsbar
gbar     hgbar       igbar     ihgbar
abar     habar       iabar     ihabar

Structure

Barcharts follow a regular novem chart structure as outlined below. For a more detailed introdution to the chart structure please see the chart structure details page.

en_letter_frequency      => Name
├── config               => Configuration options
│   ├── caption          => Caption below chart
│   ├── title            => Title of chart
│   └── type             => bar, sbar, gbar etc...
├── data                 => data to chart
├── description          => Description (meta)
├── name                 => Name (meta)
└── shared               => Sharing information
    ├── +org~group       => Shared with an org group
    ├── @username~group  => Shared with a user group
    └── public           => Shared with everyone

Data 

curl -X POST https://api.novem.io/vis/plots/<name>/data \
  -H "Authorization: Bearer <your_token>" \
  --data "@data.csv"

Like most novem charts the primary way to update the barchart is by writing the information you want visualised to the /data endpoint.

Novem will assume that the first column is the data for the category axis and the second column the data for the value axis. By default the category axis would be the x-axis, but this will be flipped in the example of h* and ih* versions.

Config

Barchart Types

As mentioned in the introduction there are 3 main types of barcharts available on the novem platform.

Regular

Stacked

Grouped

Aggregate

Aggregate plots are identical to regular plots, excpet they represent the sum of the columns for each category label.

Outputs

The novem barchart offers six outputs, four for the final visaulisation and two for the input data. They can all be found under the /files endpoint or by appending the extensions below. For details on the respective output formats please see the api file documentation.

  • pdf - a pdf representation /config/render/orientation orientation of the plot.
  • png - a png representation /config/render/orientation orientation of the plot.
  • txt - a utf-8 textual representation of the plot
  • ansi - a ansi escape sequency colored utf-8 textual representation of the plot
  • csv - a csv file containing the input data
  • xlsx - an xlsx file containing the input data

Examples

This section contains a few practical examples on how to use the api and common use cases. For more comprehensive examples we suggest visting some of our example charts or reading a couple of our getting started with novem blog posts.

Create your first barchart

Welcome to your first barchart, we’ll assume that you have a csv file called en_letter_freq.csv file two columns:

  • Charracter
  • Frequency

If you want to cheat you can find an example file here : url to en_letter_freq.csv.

    # this assumes that the novem client is installed in $PATH

cat en_letter_freq.csv | novem \
  -p <name>                       # -p for plot name will be created or updated
  -w config/type    "bar" \       # -w for write followed by relative plot path and value
  -w config/title   "Frequency of letters in the English language" \
  -w config/caption "Analysis of entries in the Concise Oxford dictionary "\
                    "as published by the compilers. The chart above represents "\
                    "data taken from Pavel Micka's website, which cites "\
                    "Robert Lewand's Cryptological Mathematics" \
  -g url                          # returns the url


    # Assume the novem fuse api is mounted on ~/novem

# create a new plot
mkdir ~/novem/vis/plots/<name>

# change the type to be bar
echo "bar" > ~/novem/vis/plots/<name>/config/type

# upload the data
cp en_letter_freq.csv ~/novem/vis/plots/<name>/data

# add title and caption
echo "Frequency of letters in the English language" >\
  ~/novem/vis/plots/<name>/config/title

echo "Analysis of entries in the Concise Oxford dictionary "\
     "as published by the compilers. The chart above represents "\
     "data taken from Pavel Micka's website, which cites "\
     "Robert Lewand's Cryptological Mathematics" >\
  ~/novem/vis/plots/<name>/config/caption

cat ~/novem/vis/plots/<name>/url

    import pandas as pd     # everything is easier with pandas
from novem import Plot  # get the novem plot object

# construct novem chart obejct
# if the name already exists it will be updated
barchart = Plot(<name>, \
  type='bar', \
  title='Frequency of letters in the English language', \
  caption = """Analysis of entries in the Concise Oxford dictionary
 as published by the compilers. The chart above represents
 data taken from Pavel Micka's website, which cites
 Robert Lewand's Cryptological Mathematics"""
)

df = pd.read_csv('en_letter_freq.csv')   # read csv
df.pipe(barchart)                        # create the barchart

# with our python api it's easy to update the chart using
# simple pandas idioms
# df.sort_values(by='frequency').pipe(barchart)

print(barchart.url)                      # get the url


    # The http PUT verb will create a new chart entity
# POST is used to write to files that "already" exists.

# Create our chart by PUTing a new name
curl -X PUT https://api.novem.io/vis/plots/<name> \
  -H "Authorization: Bearer <your_token>"

# Change our type to be a bar chart
curl -X PUT https://api.novem.io/vis/plots/<name>/config/type \
  -H "Authorization: Bearer <your_token>" \
  -d "bar"    # feel free to experiemnt with different types

# Write the data we want to visualize
curl -X POST https://api.novem.io/vis/plots/<name>/data \
  -H "Authorization: Bearer <your_token>" \
  --data "@en_letter_freq.csv"

# Add a title to our chart
curl -X PUT https://api.novem.io/vis/plots/<name>/config/title \
  -H "Authorization: Bearer <your_token>" \
  -d "Frequency of letters in the English language"

# And a nice caption
curl -X PUT https://api.novem.io/vis/plots/<name>/config/caption \
  -H "Authorization: Bearer <your_token>" \
  -d "Analysis of entries in the Concise Oxford dictionary "\
     "as published by the compilers. The chart above represents "\
     "data taken from Pavel Micka's website, which cites "\
     "Robert Lewand's Cryptological Mathematics"

# Finally GET our url so we can view the finished product
curl -X GET https://api.novem.io/vis/plots/<name>/url \
  -H "Authorization: Bearer <your_token>"
    ← Overview
    Overview →