castor-theme-sbadmin

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 castor-cli -g
$ npm install castor-theme-sbadmin -g

Usage

$ castor --theme ./castor-theme-sbadmin/ /path/to/data/repository

Alternatively, you can use ezviz, which does not need the theme parameter:

$ ezviz /path/to/data/repository

If you don't have a data repository, but already loaded data in mongodb, you can use:

$ castor --theme ./castor-theme-sbadmin/ $PWD/data

Before that, you have to configure your mongo connection, by creating a ./data.json file containing something like:

{
  "port": 3000,
  "collectionName" : "insu"
}

Or, if you prefer (assuming you use insu collection):

$ castor --theme ./castor-theme-sbadmin/ --collectionName insu

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.

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.

{
  "theme": "/path/to/castor-theme-sbadmin",
  "documentFields": {
    "Themes" : {
      "path" : "content.json.DiscESI",
      "separator" : ";"
    }
  },
  "dashboard" : {
    "charts": [
        {
            "field": "content.json.Py",
            "type": "histogram"
        },
        {
            "field": "fields.Themes",
            "type": "pie"
        }
    ]
  }
}

Dashboard

type

A documents' field which number of distinct values has to be displayed. Replaced (see corpusFields).

For example: a type of paper (for scientific articles).

keys

• path: path to the field, in dotted notation (default value: mimetype)
• label (default value: MIME Types)

example

{
  "dashboard" : {
    "type" : {
      "path": "content.json.Pt",
      "label": "Document types"
    }
  }
}

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:

{
  "field": "fields.Themes",
  "type": "pie",
  "legend": {
    "show": false
  }
}

color

You can set a color value (hexadecimal color value). Example with a red histogram:

{
  "dashboard": {
    "charts" : [
      {
        "field": "content.json.Year",
        "type": "histogram",
        "color": "#ff0000"
      }
    ]
  }
}

colors

In a pie, you can parameter a set of colors to be used:

{
  "dashboard": {
    "charts" : [
      {
        "field": "content.json.Keywords",
        "type": "pie",
        "colors": [ "#BB9FF5", "#ff7a85", "#44b2ba", "#ffa65a", "#34cdb8"]
      }
    ]
  }
}

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"
      }
  ]
}

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"
        },
        {
          "path": "fields.Themes",
          "label": "Theme"
        }
      ]
    },

Here, you have a pie displaying sections, and two facets:

1. pointing to content.json.Py in the document
2. pointing to fields.Theme in the document

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:

{
  "filters": {
    "objectPath": "objectPath"
  }
}

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:

{
  "display" : {
    "fields" : {
      "fields.title": "Titre",
      "fields.authors": "Auteurs",
      "fields.year": "Année de publication",
      "content.json.SourceCorrigee": "Source",
      "content.json.DiscESI": "Discipline ESI",
      "content.json.SectionEtude": "Marquage INSU - Section",
      "content.json.La": "Langue de la publication",
      "content.json.PaysFRERegroupe": "Pays",
      "content.json.Di": "DOI",
      "content.json.Ut": "Identifiant WoS"
    }
  }
}

Fields' number

To modify the number of fields displayed per page, change the display.fieldsPerPage value in the configuration.

Ex:

{
  "display" : {
    "fieldsPerPage": 10
  }
}

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"
      }
    }
  ]