visavail v1.5.0

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

• 7.1. License](#71-license-71-license)
• 1. Description
• 2. Demo
• 3. Usage
  • 3.1. Input Data Format
    • 3.1.1. Continuous Data
    • 3.1.2. Data With Time Gaps
    • 3.1.3. Data With Dates and Times
    • 3.1.4. Data With Custom Categories
    • 3.1.5. Display Style
    • 3.1.6. Type of Chart
  • 3.2. Data Options
    • 3.2.0.1. Measure Labels with HTML
    • 3.2.1. Icon property
    • 3.2.2. Percentage property
    • 3.2.3. Compeld data example
  • 3.3. Chart Options
    • 3.3.1. Margin
    • 3.3.2. Padding
    • 3.3.3. Y Title Tooltip
    • 3.3.4. Tooltip
    • 3.3.4.1. 3.3.4.1 Hover Zoom Option
    • 3.3.5. Legend
    • 3.3.6. Title
    • 3.3.7. Sub Title
    • 3.3.8. Icon
    • 3.3.9. Graph
    • 3.3.10. Responsive
    • 3.3.11. Zoom
    • 3.3.12. Sub Chart
    • 3.3.12.1. Sub Chart Graph Option
    • 3.3.13. Custom Tick Format
    • 3.3.14. Y Percentage
    • 3.3.15. Example Usage
    • 3.3.16. Implementation
    • 3.3.17. Integrate on Angular
    • 3.3.18. Integrate on React.js
    • 3.3.19. 3.1.29.Visavail Function
• 4. Public Projects With Visavail.js
• 5. Download
• 6. Dependencies
• 7. Contribution
  • # 7.1. License

7.1. License](#-71-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.

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 |

#

3.2.0.1. Measure Labels with HTML

Measure labels can be expressed in full HTML via the measure_html property in the dataset. Here is an example: At the moment this type of labels are suspended due to incompatibility with IE11 and wrapping text

WE HAVE INTRODUCED measure_description that in combination with y_title_tooltip can support html tag

3.2.1. Icon property

3.2.2. Percentage property

3.2.3. Compeld data example

This is a simple compelx example with all data features enabled:

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"]
    ],
    "icon": {
      "url":"your_url_file",
      "width": 24,
      "height":24,
      "padding": {
          "left": 0,
          "right": 5
      },
      "background_class": "icon_class"
    },
    "percentage": { //used for customize right text
        "measure": "45 %",
        class: "y_percentace_test"
    }
}];

3.3. Chart Options

The options of the chart are in JSON format and you can customize everything. You can pass the JSON Object to library with custom settings

3.3.1. Margin

3.3.2. Padding

3.3.3. Y Title Tooltip

3.3.4. Tooltip

#

3.3.4.1. 3.3.4.1 Hover Zoom Option

3.3.5. Legend

3.3.6. Title

3.3.7. Sub Title

3.3.8. Icon

3.3.9. Graph

3.3.10. Responsive

3.3.11. Zoom

3.3.12. Sub Chart

#

3.3.12.1. Sub Chart Graph Option

3.3.13. Custom Tick Format

This library use moment.js to customize and convert the date format/language in base of moment.locale() function (we autodetect the browser language!). If you what change manually the tick format you can customize with this option.

With set this option you override the automatic tick format execute by library for a specific locale.

3.3.14. Y Percentage

3.3.15. Example Usage

In this example we use a custom id for a div container and div graph, custom icon for tooltip, enabled zoom and resposive layout

var options = {
	id_div_container: "visavail_container",
	id_div_graph: "visavail_graph",
	icon: {
		class_has_data: 'fas fa-fw fa-check',
		class_has_no_data: 'fas fa-fw fa-exclamation-circle'
	},
	zoom:{
		enabled:true,
	},
	responsive:{
		enabled:true,
	}
};

3.3.16. Implementation

To use the chart in your project, follow these steps:

1. Copy the visavail.js and visavail.css into your css and js forder project (for minify version).

2. Assuming that your website is in the root folder, add the following lines to the <head> of your website:

   <link href="https://fonts.googleapis.com/css?family=Muli" rel="stylesheet" type="text/css">
   <link href="./css/visavail.css" rel="stylesheet" type="text/css">
   <link href="./css/font-awesome.min.css" rel="stylesheet" type="text/css">

3. And the following lines to the <body> of your website:

   <script src="./js/moment-with-locales.min.js" type="text/javascript"></script>
   <script src="./js/d3.min.js" charset="utf-8"></script>
   <script src="./visavail/js/visavail.js"></script>
   
   <div style="overflow: hidden;" class="visavail" id="visavail_container">
   	<p id="visavail_graph"><!-- Visavail.js chart will be placed here --></p>
   </div>
   
   <script type="text/javascript">
   	moment.locale("en");
   	var dataset = ... // see examples/example_basic.htm
   	var options = {
   		id_div_container: "visavail_container",
   		id_div_graph: "visavail_graph",
   	};
   	
   	var chart = visavail.generate(options, dataset)
   </script>

3.3.17. Integrate on Angular

You can use this library in your Anular 2+ project (tested from 2 to 8 version). Follow this step to integrate it:

1. Add to your package.json d3, moment and visavail package with npm installation

2. In your component in the import section insert this line

   import * as visavail from "visavail";

3. Create JSON an object in your component class that can be contain the dataset, options and chart

4. Add the div in your html where you want to put the graph

5. Call visavail.generate(...) funtion to generate the graph

An example of implementation, you can found HERE

3.3.18. Integrate on React.js

You can use this library in your React project (not compleated tested). Follow this step to integrate it:

1. Add to your package.json d3, moment and visavail package with npm installation

2. In your component in the import section insert this line

   import * as visavail from "visavail";

3. Create JSON an object in your component class that can be contain the dataset, options and chart

4. Add the div in your render() function

5. Call visavail.generate(...) funtion to generate the graph into componentDidMount()

6. If you want update the chart with new data, you can call the updateGraph(dataset) function into componentDidUpdate() react function

An example of implementation, you can found HERE

3.3.19. 3.1.29.Visavail Function

The Visavail library have inside a series of function for update, change and delete the graph without using manual funtion. Below you can find a table that explain thi function. You can associate chart = visavail.generate(.....) and call chart.someFunctio() to change the graph

4. Public Projects With Visavail.js

• Jina Yoon of Brown University used Visavail.js in her sleep tracker comparison
• GanttLab uses Visavail.js to present Gitlab and Github issues in a Gantt chart

5. Download

An archive with the library can be downloaded from the releases page.

6. Dependencies

Visavail.js depends on a couple of libraries:

• D3.js JavaScript library as a visualization framework,
• Moment.js for formatting dates in tooltips and
• Font Awesome for icons in the tooltips.

7. Contribution

We are happy about any contribution or feedback. Please let us know about your comments via the Issues tab on GitHub.

7.1. License

The Visavail.js library is distributed under the MIT License (MIT). Please also take note of the licenses of the dependencies.