visir
A Castor theme to visualize a synthesis on a corpus using pies and histograms, based on SB Admin v2.0.
Installation
You have to install mongodb first, and node too.
$ npm install visir -g
Usage
$ visir /path/to/data/repository
If you don't have a data repository, but already loaded data in mongodb, you can use:
$ visir $PWD/data
Before that, you have to configure your mongo connection, by creating a
./data.json
file containing something like:
Then, point your browser to http://localhost:3000/
Configuration
To make charts appear on the dashboard, you have to configure them.
The configuration is done in the JSON file of
castor (e.g.data.json
),
it's a file with the same name as the data directory
(besides that directory), appended with .json
.
The whole dashboard configuration is done inside the dashboard
key of the
JSON configuration file. Except, the documentFields
configuration is documented in castor-load-custom's
README,
and corpusFields
configuration is documented in
castor's
README
Each chart has to be described in the dashboard.charts
key.
Below is an example with an histogram, and a pie chart. There are two types of
charts: histogram
and pie
.
Dashboard
All dashboard settings are inside a dashboard
key.
At the moment, there is only the charts
setting.
Charts
Chart types
histogram
Used to represent evolution of the number of documents along the time (so, this field is often a publication year, or anything indicating a point in time).
Possible configuration: size
, legend
, and color
.
pie
Used to fill the pie chart quarters.
There are some configuration possible: size
of the pie, and
position of the legend
.
horizontalbars
Used to display the number of documents associated to a field value (for example, for keywords: how many documents match a keyword?). Bars are sorted by descending number of documents.
Possible configuration: size
, color
, legend
, and maxItems
.
maxItems
limit the number of bars to its value (default value: 100
).
Preferences
size
To specify the size of the pie, add the size
key to your chart.
Then, you can follow the C3's example to fill it.
Ex:
"field": "fields.Themes" "type": "pie" "size": "height": 400
You can add a columns
property too, knowing that the display has a "width"
of 12 columns (Twitter bootstrap).
Here is an example where the pie should take half of the page's width:
"field": "fields.Themes" "type": "pie" "size": "height": 400 "columns": 6
If you need to separate two charts, you can add an offset before a chart, using
offset
property. It is a number which represent the "width" of offset
columns.
Below is an example where the horizontal bars should take 5 columns, with a preceding offset of 1 column.
"field": "fields.Themes" "type": "horizontalbars" "title": "Thèmes" "size": "height": 420 "columns": 5 "offset": 1
legend
To specify where you want the legend to be, add the legend
key to your chart.
Then, you follow the C3's example to fill it.
There are currently only two positions: bottom
and right
.
Ex:
"field": "fields.Themes" "type": "pie" "legend": "position": "bottom"
You can also hide/show the legend, using "show": false
or "show": true
:
color
You can set a color
value (hexadecimal color value).
Example with a red histogram:
colors
In a pie, you can parameter a set of colors to be used:
help
You can add a helping text for a particular chart, in the help
key:
This help text is a markdown text, and will appear after the title of the page
pages.chart.title
, and possibly after the charts' help text
pages.chart.help
, which appear on all charts' pages.
Field configuration
Simple configuration
To indicate which field is used by a chart, you have to specify it inside the can use the JSON configuration field.
These are used to point inside the mongodb document, using the dot notation.
Often, they are placed in the content
field, or in fields
.
Ex:
"dashboard" : "charts": "field": "content.json.Py" "type": "histogram" "field": "content.json.DiscESI" "type": "pie"
Multivalued fields
Maybe your fields are multivalued, for example, if you load csv
files.
For example, in a Keywords
columns, you have such values:
Dashboard; Nodejs; Github
Web; Dashboard; Statistics
The direct way, is to point to content.json.keywords
, but that will
distinguish the Dashboard
from the first row to the one from the second row.
Moreover, they will be bound to other keywords on the same row.
The solution is to add a custom field in the JSON configuration file:
"documentFields" : "Keywords" : "path" : "content.json.Keywords" "separator" : ";"
Then, you have to add
"dashboard" : "charts": "field": "content.json.Py" "type": "histogram" "field": "fields.Keywords" "type": "pie"
Here is an example with a normal field Py
(Publication year, which
is unique in each row), and a multivalued one, Keywords
(several
keywords):
"documentFields" : "Keywords" : "content.json.Keywords" "separator" : ";" "dashboard" : "charts": "field": "content.json.Py" "type": "histogram" "field": "fields.Keywords" "type": "pie"
Operators
By default, the charts operator is distinct
, which count the distinct values
of one field.
There are other operators, and some of them take more than one field.
For these cases, use operator
and fields
keys (fields
replaces field
,
or you can set only one field in this table).
Example: to display, in an histogram
, the total of citations (by year):
See operators.
Documents table
In /chart.html
pages, you can see a chart, and a table with documents. This table display the fields you chose to put in the documentFields
key.
Here is an example, displaying Year
, Title
, Authors
, and Keywords
:
"documentFields" : "year" : "path" : "content.json.Py" "label": "Publication Year" "visible": true "title" : "path" : "content.json.Ti" "label": "Title" "visible": true "authors": "path" : "content.json.Af" "label": "Authors" "visible": true "keywords" : "path" : "content.json.DiscESI" "label": "Keywords" "visible": true
All custom fields which visible
key is set to true
will be
present in the table.
By default, visible
key value is false
.
Facets
In a chart page, you can add facets: others fields' values.
Thus, you can have facets in each chart. Example:
"charts": "field": "fields.Section" "type": "pie" "title": "Sections" "facets": "path": "content.json.Py" "label": "Year" "help": "Production per year" "path": "fields.Themes" "label": "Theme"
Here, you have a pie displaying sections, and two facets:
- pointing to
content.json.Py
in the document - pointing to
fields.Theme
in the document
The first facet has a help
field, which will appear as a tooltip.
Document's page
Title
To indicate the title of a document, use the documentFields
named title
.
Fields
In order to make the /display/id.html
page work, one filter has
to be declared in the configuration:
Then, you have to declare all the fields you want in the document's page.
They have to be in display.fields
, they'll be displayed in the same
order as their declaration's order.
Use "path": "label"
Ex:
Fields' number
To modify the number of fields displayed per page, change the
display.fieldsPerPage
value in the configuration.
Ex:
Pages settings
Each URL of the theme may be customized:
title
(appears in the head of the page, and is a part of the browser's tab)description
(short description of the page)help
(first paragraph in the page)
For example, you may customize the /index.html
page using:
"pages" : "index" : "title" : "Dashboard" "description" : "Study Foo's dashboard" "help" : "This comes from Web Of Science, and does only contain documents from Foo University."
Notice that the path for index
settings is pages.index
.
Loaders
By default, this castor theme is able to load CSV files (each line being a document).
Here is the default settings:
"loaders": "script": "castor-load-csv" "pattern": "**/*.csv"
These settings mean that all .csv
files within the data directory (and all
its descendants, thanks to **/
) will be loaded by
castor-load-csv
.
You can add any castor loader you find in castorjs repositories (except castor-load, which manages (all loaders).
For example, to enable castor to load XML files, each containing several documents (in /RDF/Topic
), use:
"loaders" : "script" : "castor-load-xmlcorpus" "pattern" : "**/*.xml" "options" : "cutter" : "/RDF/Topic"