column.md

Column is the base class for data columns (sometimes also called data series) in Datawrapper. A column has a column type and stores a list of values as rows. Also they support common computations such as calculating the sum and the range of the data it holds.

import Column from '@datawrapper/chart-core/lib/dw/dataset/column';
const col = Column('my column', values);

# column(name, rows, type)

Instantiates a new column with the name name and the data rows. Specifying the type is optional, if not provided the type will be guessed. Usually you don't need to instantiate columns yourself as they provided by the dataset.

Operating on columns

# column.name(name)

If called with no arguments, returns the internal name of the column. If you provide the name argument, it will be set as new column name. Setting the column name is intended for configuration persistence and should not be used for presentation (use the column.title method for that purpose).

# column.title(title)

If called with no arguments, returns the human-readable title of the column. If the title was not set, returns the name of the column. If you provide the title argument, it will be set as new column title. Setting the column title is intended for presentation.

# column.length

Returns the number of rows in the column.

# column.val(index)

Returns the parsed value in row index. The value will be parsed by the column type whenever you call this function. To make our lives easier, you can use negative indexes to get values from the end of the rows, e.g. column.val(-1) for the last value.

var first = column.val(0);
var last = column.val(column.length-1);
// this also works:
last = column.val(-1);

# column.values()

Returns the parsed values as an array.

# column.each(func)

Applies a function over all parsed values. This invokes a simple for loop over all rows and calls func with the arguments value and index.

sum = 0;
column.each(function(value, index) {
   sum += value;
});
// note that you can also use this:
sum = column.total();

# column.type(asObjectorNewType)

If called without an argument type returns the column type as string, which would be either text, number or date. If called with true as first argument the column type is returned as [object](Column Types). If called with a string as first argument type() will set a new column type.

datecolumn.type()  // returns column type as string, eg. 'date'
datecolumn.type(true);  // returns column type as object, eg. dw.column.types.date()
datecolumn.type('text');  // sets the column type to 'text'

# column.raw(row, newValue)

If called without any arguments raw() returns an array of all the raw, unparsed values stored in the column. If you provide only the row argument you will only get the raw value of this row. If newValue is also provided the function will set it as new value.

# column.range()

Returns an array with the minimum and maximum of all values in the column. Only works for column types that are convertable to numbers (which is true if they implement the toNum() function).

# column.total()

Returns the sum of all values in the column. Only works for column types that are convertable to numbers (which is true if they implement the toNum() function).

# column.filterRows(indexes)

Temporarily removes all rows whose index is not within the array indexes. A copy of the original rows is stored for reference. If called without arguments, filterRows restores the original rows.

# column.indexOf(value)

Returns the index of the row with given value or -1 if the value was not found in the column.