=============================================
This library visualizes the availability of time-dependent data with a chart on a website. This is a fork of the Visavail original library https://github.com/flrs/visavail.
I modify the structure of library and implement new functionality for a better and dynamic library.
Table of contents- # 1. Description
- # 2. Demo
- # 3. Usage
- ## 3.1. Input Data Format
- ## 3.2. Display Style
- ## 3.3. Options
- ## 3.4. Implementation
- # 4. Download
- # 5. Dependencies
- # 6. Contribution
- # 7. License
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.
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.
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.
The input to the Visavail.js library is a JSON-like structure. There are three formats that Visavail.js accepts. Which format is right for you depends on your use case.
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
"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]
]
}];
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"]
]
}];
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"]
]
}];
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 color that is used for displaying the category in the chart.
The chart legend will not appear on charts with data in custom categories. Instead, the category name will be shown in the tooltip that appears when you hover over the bars in the chart. See the code below for an example.
var dataset = [{
"measure": "Fat Bike",
"categories": { // category names and their colors defined here
"Kim": { "color": "#377eb8" },
"Bert": { "color": "#ff7f00" },
"Zoe": { "color": "purple" },
},
"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"]
]
}];
If you want to add a link to your measure label, you can do so by adding an URL through the measure_url
property in the dataset
. Here is an example:
var dataset = [{
"measure": "Annual Report",
"measure_url": "http://www.github.com/flrs/visavail" // link definition
"interval_s": 365 * 24 * 60 * 60,
"data": [
["2015-01-01", 0],
["2016-01-01", 1],
["2017-01-01", 1],
["2018-01-01", 1]
]
}];
Measure labels can be expressed in full HTML via the
At the moment this type of labels is suspended due incompatibility with IE11 and wrapping textmeasure_html
property in the dataset
. Here is an example:
var dataset = [{
"measure_html": "<span title='Price of security at end of day'>🚪 Closing Price</span>", // HTML code
"interval_s": 365 * 24 * 60 * 60,
"data": [
["2015-01-01", 0],
["2016-01-01", 1],
["2017-01-01", 1],
["2018-01-01", 1]
]
}];
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.
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
}
};
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
Name | Type | Default | Description |
---|---|---|---|
id_div_container | string |
visavail_container | Id of div that contain the graph tag |
moment_locale | string |
autodetect | The lib autodetect language browser and set the moment library automatically. You can change this parameter with a string contained into locale moment.js lib. if you set to null moment use "en" format as default (see moment.js library) |
margin | Object{} |
more info | Json Object that contain margin of graphs include title, legent etc. |
padding | Object{} |
more info | Json Object that contain padding of graphs |
width | number |
960 | Width of the graph, this option was ignored if option resposive is enabled |
reduce_space_wrap | number |
36 | Space for three dots when you use a simple title of mesurment |
line_spacing | number |
16 | Space between two row of dataset |
emphasize_year_ticks | boolean |
true | Emphasize the year when the range of data cover one more year |
emphasize_month_ticks | boolean |
true | Emphasize the month when the range of data cover one more month and not exceed the year |
max_display_datasets | number |
0 | max. no. of datasets that is displayed, 0: all (is the same option of original library) |
ticks_for_graph | number |
6 | number of ticks that is displayed, null: max enter in the tick (may cause overlap problem). N.B the ticks are controlled by d3.js lib. in some case this value will be ignored but help you for prevent overlap xaxis top |
cur_display_first_dataset | number |
0 | current first dataset to display (is the same option of original library) |
display_date_range | Array[] |
[0,0] | range of dates that will be shown. If from-date (1st element) or to-date (2nd element) is zero, it will be determined according to your data (default: automatically) |
custom_categories | boolean |
false | Set to true if you want to use custom category |
is_date_only_format | boolean |
false | Check if the date is with date only ( will set Automatically) |
show_y_title | boolean |
true | If you set to fale, reminder to set properly margin and padding left |
date_in_utc | boolean |
true | Set true or false in base of your type of date. If true we use moment to set the date in the current user timezone or in the timezone set by script |
date_is_descending | boolean |
false | Set true if you want display your dataset is descending version (from now to old). If false the data was diplayed in standard view N.B.: the data in dataset is in ascending order |
defined_blocks | boolean |
false | If set to true the we ignore interval_s options in datasets and we use a block defined. This option is set automatically if in there is a date/time defined |
onClickBlock | function(d,i) |
null | return "d" an arry with date and value precessed and "i" value of block clicked item |
tooltip | Object{} |
more info | Json Object that contain tooltip option for the graph |
legend | Object{} |
more info | Json Object that contain legend option for the graph |
title | Object{} |
more info | Json Object that contain title option for the graph |
sub_title | Object{} |
more info | Json Object that contain sub-title option for the graph |
icon | Object{} |
more info | Json Object that contain icon option for the graph |
graph | Object{} |
more info | Json Object that contain option for custom type of graph |
responsive | Object{} |
more info | Json Object that contain option for responsive layout of graph |
zoom | Object{} |
more info | Json Object that contain option for zoom in the graph |
custom_time_format | Object{} |
more info | Json Object that contain option for customize the x-axes tick into graph |
Name | Type | Default | Description |
---|---|---|---|
top | number |
65 | Number express in px |
bottom | number |
40 | Number express in px |
right | number |
20 | Number express in px |
left | number |
100 | Number express in px |
Name | Type | Default | Description |
---|---|---|---|
top | number |
-50 | Number express in px |
bottom | number |
10 | Number express in px (not used at the moment) |
right | number |
0 | Number express in px (not used at the moment) |
left | number |
-100 | Number express in px, used for move the y title on the left |
Name | Type | Default | Description |
---|---|---|---|
class | string |
tooltip | Set a custrom class if you want |
height | number |
10 | height of tooltip , correspond to line-height of class tooltip from css) |
position | string |
top | Two type of tooltip: "top" is a div before bar follow the mouse only left, "overlay" follow the mouse left and height |
left_spacing | number |
0 | Left space from tooltip and mouse |
date_plus_time | boolean |
false | enable date and time on tooltip (override the is_date_only_format option) |
only_first_date | boolean |
false | show only first date on tooltip (we suggest to use this on rhombus or circle graph) |
duration | number |
150 | Number in ms for the animation duration (all tooltip otpion) |
hover_zoom | Object{} |
more info | option for zoom block on hover |
Name | Type | Default | Description |
---|---|---|---|
enabled | boolean |
false | Enable block zoom whe mouse hover |
ratio | number |
0.4 | Number from 0 to 1 that incrase the block size. It will be multiplied with option line_spacing |
Name | Type | Default | Description |
---|---|---|---|
enabled | boolean |
true | Enable the legend (If you use a custom categories the legend is hidden) |
line_space | number |
12 | height of legend font , correspond to line-height of class tooltip from css) |
offset | number |
5 | Distance from two data of legend |
has_no_data_text | string |
No Data available | String for no data available |
has_data_text | string |
Data available | String for no data available |
Name | Type | Default | Description |
---|---|---|---|
enabled | boolean |
true | Enable the title |
line_space | number |
16 | height of legend font , correspond to line-height of class tooltip from css) |
text | string |
Data Availability Plot | String Title |
Name | Type | Default | Description |
---|---|---|---|
enabled | boolean |
true | Enable the title |
line_space | number |
16 | height of legend font , correspond to line-height of class tooltip from css) |
from_text | string |
from | String for from date |
to_text | string |
to | String for to date |
Name | Type | Default | Description |
---|---|---|---|
class_has_data | string |
fas fa-fw fa-check | custom icon call (for example font awesome) |
class_has_no_data | string |
fas fa-fw fa-times | custom icon call (for example font awesome) |
Name | Type | Default | Description |
---|---|---|---|
type | string |
bar | There are three type of graph; "bar" is a classical horizzontal bar, "rhombus" use a rhombus for a simple alert, "circle" a drop for a event chart |
height | number |
20 | height of type of graph |
width | number |
20 | width of type of graph, used only for rhombus type and circle type |
Name | Type | Default | Description |
---|---|---|---|
enabled | boolean |
false | Enable the resposive chart for a responsive layout (this option recreate the chart when the page or div of chart will be resized) |
onresize | function |
null | at the moment not supported |
Name | Type | Default | Description |
---|---|---|---|
enabled | boolean |
false | Enable the zoom in the chart. We can zoom with mousewheel and you can mof left-right for move in the graph |
onZoom | function(e) |
null | return a current array with current domain of current zoom in date format |
onZoomStart | function(e) |
null | return a d3.event json object when zoom start |
onZoomEnd | function(e) |
null | return a array with current domain of current zoom in date format at the end of the zoom |
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.
Name | Type | Default | Description |
---|---|---|---|
format_millisecond | string |
moment convertion | custom format for millisecond |
format_second | string |
moment convertion | custom format for second |
format_minute | string |
moment convertion | custom format for minute |
format_hour | string |
moment convertion | custom format for hour |
format_day | string |
moment convertion | custom format for day |
format_week | string |
moment convertion | custom format for week |
format_month | string |
moment convertion | custom format for month |
format_year | string |
moment convertion | custom format for year |
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,
}
};
To use the chart in your project, follow these steps:
-
Copy the
visavail.js
andvisavail.css
into your css and js forder project. -
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">
-
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>
- Jina Yoon of Brown University used Visavail.js in her sleep tracker comparison
- GanttLab Live uses Visavail.js to present Gitlab and Github issues in a Gantt chart
An archive with the library can be downloaded from the releases page.
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.
I am happy about any contribution or feedback. Please let me know about your comments via the Issues tab on GitHub.
The Visavail.js library is distributed under the MIT License (MIT). Please also take note of the licenses of the dependencies.