Visavail.js - A Time Data Availability Chart

This library visualizes the availability of time-dependent data with a chart on a website.

Table of Contents

1. Description
2. Demo
3. Usage
4. Public Projects With Visavail.js
5. Download
6. Dependencies
7. Contribution
8. License

1. Description

The Visavail.js chart allows a quick insight into which periods of time a time-dependent dataset covers. It is visually similar to a Gantt chart and allows easy identification of missing pieces and gaps in large datasets. Missing periods of data are marked in red while blocks of complete periods of data are marked in green. The user discovers dates that define start and end of such periods by tooltips, as shown in the picture below.

Preview of Visavail.js chart

An example use case is the visualization of a dataset that contains time-dependent stock market data. The question the Visavail.js chart tries to answer is

"Do I have continuous stock market data in my dataset and if not, where are the gaps?"

The Visavail.js library takes single data points with dates and information about data availability as inputs, combines them into time blocks, and visualizes these blocks.

2. Demo

Some example of Visavail.js in action is displayed at Demo. The source code of the a basic demo is shown in the file basic.html.

3. Usage

Input data format, display style and dependencies have to be considered for using the Visavail.js library successfully. The respective code snippets are explained below.

3.1. Input Data Format

The input to the Visavail.js library is a JSON-like structure. There are four formats that Visavail.js accepts. Which format is right for you depends on your use case.

3.1.1. Continuous Data

You should use the continuous data format if you want to display continuous recordings. Visavail.js assumes that information about the availability of some data is valid until the next data point shows up. Thus, the library will plot a continuous bar from the first to the last data point. The last data point will be assumed valid for a period of "interval_s". The below code comments point out the elements that should be included in the input data.

var dataset = [{
    "measure": "Annual Report", // name of the data series, will become y-axis label
    "measure_description": "Descripion of Annual Report" // description of y-axis label, visible with mouse over
    "interval_s": 365 * 24 * 60 * 60, // time period in seconds a single data point is expected to cover
    "data": [
        ["2015-01-01", 0], // data as arrays of period start data string and bit determining
                           // if data are available for that period
        ["2016-01-01", 1],
        ["2017-01-01", 1],
        ["2018-01-01", 1]
    ]
}];

If you want to add some descpription regarding measure, you can add a "measure_description" key to single dataset. Without enable y_title_tooltip enablement you can see the description as a svg title (no html enablement), if you enable the tooltip funziton for y title you can use also html tag for tooltip.

3.1.2. Data With Time Gaps

You should use the time gap data format if you want to display recordings that are not continuous. The availability data are valid for a specific period of time. This period is defined by a start and an end date, as shown in the code below. In this case, no information about "interval_s" (as explained in the previous use case) is needed.

var dataset = [{
    "measure": "Annual Report", // name of the data series, will become y-axis label
    "data": [
        ["2015-01-01", 0, "2015-03-04"], // data as arrays of period start data string,
                                         // bit determining if data are available for that
                                         // period and period end data string
        ["2016-01-01", 1, "2016-03-03"],
        ["2017-01-01", 1, "2017-03-06"],
        ["2018-01-01", 1, "2018-04-01"]
    ]
}];

3.1.3. Data With Dates and Times

The library also supports the display of data in smaller units than days as in the previous examples. Visavail.js currently supports display of data in second intervals. The code below is based on the time gap data format outlined above. To display date and time data correctly, all data must be formatted in a 24-hour format.

var dataset = [{
    "measure": "Room Occupancy", // name of the data series, will become y-axis label
    "data": [
        ["2016-01-01 12:00:00", 1, "2016-01-01 13:00:00"], // 24-hour format
        ["2016-01-01 14:22:51", 1, "2016-01-01 16:14:12"],
        ["2016-01-01 19:20:05", 0, "2016-01-01 20:30:00"],
        ["2016-01-01 20:30:00", 1, "2016-01-01 22:00:00"]
    ]
}];

3.1.4. Data With Custom Categories

If you want to show data in other categories than "data available" and "no data available", the following example is for you. Visavail.js also supports displaying data in custom categories. In this case, you have to assign all of your categories a name and a class that is used for displaying the category in the chart.

The chart legend will not appear on charts with data in custom categories. In adding you have a tooltip_html key that you can use to display some html code when you hover over the bars in the chart. If tooltip_html is empty we display the name of value used on categories.

See the code below for an example.

var dataset = [{
    "measure": "Fat Bike",
    "categories": { // category names and their colors defined here
        "0": {class: "rect_has_no_data", tooltip_html: '<i class="fas fa-fw fa-exclamation-circle tooltip_has_no_data"></i>' },
        "1": {class: "rect_has_data", tooltip_html: '<i class="fas fa-fw fa-check tooltip_has_data"></i>'},
        "Zoe": {class: "rect_purple" , tooltip_html: '<i class="fas fa-fw fa-trophy tooltip_purple"></i>'},
    },
    "category_percentage": "Zoe", // if percentage enable, calculates the percentage of this category
    "data": [
        ["2016-01-01 12:00:00", "Kim", "2016-01-01 13:00:00"],
        ["2016-01-01 14:22:51", "Zoe", "2016-01-01 16:14:12"],
        ["2016-01-01 16:14:12", "Bert", "2016-01-01 17:14:12"],
        ["2016-01-01 19:20:05", "Zoe", "2016-01-01 20:30:00"]
    ]
}];

3.1.5. Display Style

The display style of the chart is defined by a CSS style. The names of the different CSS classes in the CSS style file are self-explanatory.

3.1.6. Type of Chart

The library support three type of chart for different type of visualization "bar" (default), "rhombus", "circle". If you want to change type of graph you can follow this code

var options = {
	graph:{
		type: "circle",
		height:30,
		width:30
	}
};

3.2. Data Options

The options of the data are in JSON format and you can customize everything. | Name | Type | Default | Description | | ---- |------| ------- | ---------- | | measure | string | Name of measure that will be displayed on left side | | measure_url | string | Url that you can set as a link of measure| | measure_description | string | Description of mesurament diplayed when y_title_tooltip is enabled| | interval_s | number | Used on dataset without defined block to define dimension of last block | | data | [ [] ... []] | Array of Array Object that contain data to be displayed | | icon | Object{} | more info | Json Object that contain icon setting that will be pre-append to y title | | percentage | Object{} | more info | Json Object used in cans og char option: y_percentage.enable and y_percentage.custom_percentage is setted a true |

#

Visavail

Install / Use

README