Data sources

Data sources can be

  • external (e.g. a file on your webserver or a web service) or
  • internal (a string variable storing the data or a ValueSet2D object)

arcadiaCharts can work with the following data formats

  • CSV-format in an external file or as string
  • JSON-format in an external file or as string
  • XML-format in an external file or as string
  • ValueSet2D-Objects (a format specific to arcadiaCharts)

Setting the import type

When using external data or data stored in a string you have to tell arcadiaCharts first which format the data is in. If you specify nothing, CSV-format is assumed by default.

new ac.ACLineChartBuilder()
    // ...
    .setDataImportType(ac.DataImportType.JSON)
    // ...

The following DataImportTypes are supported. Users of the JavaScript version need to prefix DataImportType with ac., e.g. ac.DataImportType.JSON.

  • DataImportType.CSV
  • DataImportType.JSON (not yet implemented)
  • DataImportType.XML (not yet implemented)

CSV data in a string variable

CSV data stored in a string variable is a convenient way to feed data to your chart. When using this format you have to replace the line breaks of the CSV-file by “\n” characters as shown in the example below:

var myData = "Date,Temperature,Precipitation\n" +
    "Jan, 12, 22\n" +
    "Feb, 14, 23\n" +
    "Mar, 15, 30\n" +
    "Apr, 16, 40";

This is one long string variable which has been divided into separate lines for better readability.

Mandatory elements of a CSV data block

When using CSV data blocks please remember that every row and every column needs a heading for describing and allocating the data correctly. So the smallest possible csv block with only a single data entry contains two rows and two columns:

var myData = "Description, Value\n"+
             "Sales, 123 \n";

The following example will not work in arcadiaCharts:

Warning: Not working CSV data

var myData = “ValueOne\n123\n”;

Attaching csv-data to the chart

new ac.ACLineChartBuilder()
    // ...
    .setData(myData)
    // ...

CSV data stored in a file

If your data is stored in an external file, you have to use the setDataUrl() method to add it to the chart. The example code below shows an example:

new ac.ACLineChartBuilder()
    // ...
    // local file
    .setDataUrl("mydata/weather.csv")

    // or using a remote location
    .setDataUrl("http://www.example.com/data.csv")
    // ...

WARNING: The Same Origin Policy (SOP) of your browser will prevent you from accessing data from servers other than the one the original page was loaded from.

Data in CSV-format

When using data in CSV-format no import format has to be specified since CSV is the default.

CSV-standard format order

By default arcadiaCharts expects CSV data to be ordered in columns as shown in the example below:

Date,Temperature,Precipitation
Jan, 12, 22
Feb, 14, 23
Mar, 15, 30
Apr, 16, 40

CSV data in row order

If your data is ordered in rows (see example below) instead of columns you have to configure the import order with the setCSVDataOrder command.

Date; 1970; 1980; 1990; 2000; 2010;
Temperature; 13.4; 13.5; 14.5; 15.0; 13.4;
Precipitation; 100; 105; 99; 102; 89;

Configure CSV data to be read in rows:

new ac.ACLineChartBuilder()
    // ...
    .setCSVDataOrder(ac.DataOrder.ROW)
    // ...

CSV data in even more exotic formats

CSV data in a format different from the standard described above can be read as well. You just have to specify the format of the file in more detail using the following commands:

setCSVTitleIndex specifies in which row or column (depending on the specified import order) the ValueSet titles are located. The index starts at 0.

setCSVXValuesIndex specifies in which row or column (depending on the specified import order) the X-Axis values are found within the data. The index starts at 0.

In the example below the data

  • has a ROW orientation,
  • the X-axis values are found in the last line (index-value: 2) and
  • the last column (index value: 5) contains the ValueSet titles

13.4; 13.5; 14.5; 15.0; 13.4; Temperature; 
100; 105; 99; 102; 89; Precipitation;
1970; 1980; 1990; 2000; 2010; Year; 

This would be imported as follows:

new ac.ACLineChartBuilder()
    // ...
   .setCSVDataOrder(ac.DataOrder.ROW)
   .setCSVTitleIndex(5)
   .setCSVXValuesIndex(2)
    // ...

Remember: index values start at 0. The third line has an index value of 2.

Specifying data types

“Raw” CSV data does not contain any information about its type. By default arcadiaCharts tries to convert the values for the X-axis and Y-axis to floating point data. If that fails they will be stored as string values. If your data contains date values or your numbers contain special characters, you have to configure the value conversion manually.

The formatting symbols used here (###, MM-yy etc.) are described in detail in the Formatting Patterns section of this manual.

For a human a string like “2009-12-14” is evidently a date but for a computer it is just a string containing information it does not (yet) understand. Type conversion is performed using the setCSVDataSeriesConfig command.

For example if you wanted to convert the string values in the form of “2001-02-24” into a date format you would write:

new ac.ACLineChartBuilder()
    // ...
    .setCSVDataSeriesConfig("MyDateValues", ac.DataModel.DATE, "yyyy-MM-dd")
    // ...

But you could also convert a float value to a string if you wanted to use it on a category axis:

new ac.ACLineChartBuilder()
    // ...
    .setCSVDataSeriesConfig("Temperature", ac.DataModel.STRING, null)
    // ...

Consider having the following dataset:

MyDateValues,Temperature,Precipitation
Jan-06, 12 degrees, 22 mm
Feb-06, 14 degrees, 23 mm
Mar-06, 15 degrees, 30 mm
Apr-06, 16 degrees, 40 mm

Date, Temperature and Precipitation will be interpreted as strings by default since the importer cannot guess. In order to specify the first column as type date and the other two as integer and float you would use the following commands:

new ac.ACLineChartBuilder()
    // ...
    .setCSVDataSeriesConfig("MyDateValues", ac.DataModel.DATE, "MMM-yy")
    .setCSVDataSeriesConfig("Temperature", ac.DataModel.INTEGER, "# degrees")
    .setCSVDataSeriesConfig("Precipitation", ac.DataModel.FLOAT, "# mm")
    // ...

Setting separator and decimal separator

Locales

The method setLocale can be used to load predefined separators used in certain languages. By changing the locale, the decimal, thousands and datasets separators will be adjusted correspondingly. See here for a full list of all available locales.

  .setLocale( ac.Locale.EN_US)

Alternatively you can also use a query parameter: ?locale=EN_US

PLEASE NOTE: All locales must be provided in upper cases, e.g. EN_US. Otherwise the locale will not be parsed correctly by the builder. The usual standard form “en_US” can´t be used.

For EN_US: The decimal separator would be ””.”” and dataset separator would be ””,”” CSV data should have the form:

""Browser,Market Share\n""+
""Internet Explorer, 35.1\n""+
""Firefox, 26.1\n""+
""Google Chrome, 20.9\n""+
""Safari, 6.0\n""+
""Opera, 2.4\n""+
""Others, 9.5\n"";

to be intepreted correctly.

For DE_DE: The decimal separator would be ””,”” and dataset separator would be ””;”” CSV data should have the form:

""Browser; Market Share\n""+
""Internet Explorer; 35000,1\n""+
""Firefox; 26000,1\n""+
""Google Chrome; 20000,9\n""+
""Safari; 6000,0\n""+
""Opera; 2000,4\n""+
""Others; 9000,5\n"";"

Custom separators

A “separator” is the character that separates the values of a CSV data set. You have probably guessed from the name “Comma Separated Values” (CSV) that the default separator is a comma (”,”). But every other legal character can be used as a separator. For example to specify the semicolon (”;”) as separator you would use:

new ac.ACLineChartBuilder()
    // ...
    .setCSVSeparator(";")
    // ...

Custom decimal separator

A “decimal separator” (or “decimal mark”) is the character that is used to separate the integer and fractional parts of a decimal number. For example: 12.02 uses the point ”.” as decimal separator. In many countries the comma is used instead (as in 12,02). To set the comma as new decimal separator you have to use the command: setDecimalSeparator as in the example below:

new ac.ACLineChartBuilder()
    // ...
    .setCSVSeparator(",")
    // ...

Data in JSON-format

(not yet implemented)

  1. specify importType
  2. setData

Data in ValueSet2D format

In addition to data as string and in CSV format you can also directly define a ValueSet2D-object. Please note that in the current version it is not possible to create date objects for ValueSet2D objects. If you need date objects you have to import them as CSV and let the importer create them for you.

Missing Values

A “missing value” occurs if no data value is present for the current X-value. In this sample dataset the precipitation for the month of March is missing, perhaps due to a measurement error.

Date,Temperature,Precipitation
Jan, 12, 22
Feb, 14, 23
Mar, 15,
Apr, 16, 40

arcadiaCharts treats missing values as follows:

  • In line charts the ValueLine will be drawn from the point before the missing value to the point right after it (from 23 to 40 in the sample data shown above)
  • In clustered or stacked bar charts no bar will be drawn for the missing value.
  • In pie charts no pie segment will be drawn for a missing value (please note that you cannot create a pie chart from this sample data since pie charts only support one ValueSet per chart