Skip to content

Latest commit

 

History

History
146 lines (91 loc) · 9.05 KB

CSV.md

File metadata and controls

146 lines (91 loc) · 9.05 KB
Raw

API Reference ▸ CSV

The D3 4.0 API Reference has moved. This page describes the D3 3.x API.

D3 provides built-in support for parsing comma-separated values, tab-separated values and arbitrary delimiter-separated values. These tabular formats are popular with spreadsheet programs such as Microsoft Excel. Tabular formats are often more space-efficient than JSON, which can improve loading times for large datasets.

# d3.csv(url[[, accessor], callback])

Issues an HTTP GET request for the comma-separated values (CSV) file at the specified url. The file contents are assumed to be RFC4180-compliant. The mime type of the request will be "text/csv". The request is processed asynchronously, such that this method returns immediately after opening the request. When the CSV data is available, the specified callback will be invoked with the parsed rows as the argument. If an error occurs, the callback function will instead be invoked with null. An optional accessor function may be specified, which is then passed to d3.csv.parse; the accessor may also be specified by using the return request object’s row function. For example:

d3.csv("path/to/file.csv")
    .row(function(d) { return {key: d.key, value: +d.value}; })
    .get(function(error, rows) { console.log(rows); });

See the unemployment choropleth for an example.

# d3.csv.parse(string[, accessor])

Parses the specified string, which is the contents of a CSV file, returning an array of objects representing the parsed rows. The string is assumed to be RFC4180-compliant. Unlike the parseRows method, this method requires that the first line of the CSV file contains a comma-separated list of column names; these column names become the attributes on the returned objects. For example, consider the following CSV file:

Year,Make,Model,Length
1997,Ford,E350,2.34
2000,Mercury,Cougar,2.38

The resulting JavaScript array is:

[
  {"Year": "1997", "Make": "Ford", "Model": "E350", "Length": "2.34"},
  {"Year": "2000", "Make": "Mercury", "Model": "Cougar", "Length": "2.38"}
]

Note that the values themselves are always strings; they will not be automatically converted to numbers. JavaScript may coerce strings to numbers for you automatically (for example, using the + operator). By specifying an accessor function, you can convert the strings to numbers or other specific types, such as dates:

d3.csv("example.csv", function(d) {
  return {
    year: new Date(+d.Year, 0, 1), // convert "Year" column to Date
    make: d.Make,
    model: d.Model,
    length: +d.Length // convert "Length" column to number
  };
}, function(error, rows) {
  console.log(rows);
});

Using + rather than parseInt or parseFloat is typically faster, though more restrictive. For example, "30px" when coerced using + returns NaN, while parseInt and parseFloat return 30.

# d3.csv.parseRows(string[, accessor])

Parses the specified string, which is the contents of a CSV file, returning an array of arrays representing the parsed rows. The string is assumed to be RFC4180-compliant. Unlike the parse method, this method treats the header line as a standard row, and should be used whenever the CSV file does not contain a header. Each row is represented as an array rather than an object. Rows may have variable length. For example, consider the following CSV file:

1997,Ford,E350,2.34
2000,Mercury,Cougar,2.38

The resulting JavaScript array is:

[
  ["1997", "Ford", "E350", "2.34"],
  ["2000", "Mercury", "Cougar", "2.38"]
]

Note that the values themselves are always strings; they will not be automatically converted to numbers. See parse for details.

An optional accessor function may be specified as the second argument. This function is invoked for each row in the CSV file, being passed the current row and index as two arguments. The return value of the function replaces the element in the returned array of rows; if the function returns null, the row is stripped from the returned array of rows. In effect, the accessor is similar to applying a map and filter operator to the returned rows. The accessor function is used by parse to convert each row to an object with named attributes.

# d3.csv.format(rows)

Converts the specified array of rows into comma-separated values format, returning a string. This operation is the reverse of parse. Each row will be separated by a newline (\n), and each column within each row will be separated by a comma (,). Values that contain either commas, double-quotes (") or newlines will be escaped using double-quotes.

Each row should be an object, and all object properties will be converted into fields. For greater control over which properties are converted, convert the rows into arrays containing only the properties that should be converted and use formatRows.

# d3.csv.formatRows(rows)

Converts the specified array of rows into comma-separated values format, returning a string. This operation is the reverse of parseRows. Each row will be separated by a newline (\n), and each column within each row will be separated by a comma (,). Values that contain either commas, double-quotes (") or newlines will be escaped using double-quotes.

TSV

Tab-separated values are equivalent to comma-separated values, except the tab character is used as a delimiter rather than the comma.

# d3.tsv(url[, accessor][, callback])

Equivalent to d3.csv, but for tab-separated values.

# d3.tsv.parse(string[, accessor])

Equivalent to csv.parse, but for tab-separated values.

# d3.tsv.parseRows(string[, accessor])

Equivalent to csv.parseRows, but for tab-separated values.

# d3.tsv.format(rows)

Equivalent to csv.format, but for tab-separated values.

# d3.tsv.formatRows(rows)

Equivalent to csv.formatRows, but for tab-separated values.

Arbitrary Delimiters

# d3.dsv(delimiter, mimeType)

Constructs a new parser for the given delimiter and mime type. For example, to parse values separated by "|", the vertical bar character, use:

var dsv = d3.dsv("|", "text/plain");

# dsv(url[, accessor][, callback])

Equivalent to d3.csv, but for delimiter-separated values.

# dsv.parse(string[, accessor])

Equivalent to csv.parse, but for delimiter-separated values.

# dsv.parseRows(string[, accessor])

Equivalent to csv.parseRows, but for delimiter-separated values.

# dsv.format(rows)

Equivalent to csv.format, but for delimiter-separated values.

# dsv.formatRows(rows)

Equivalent to csv.formatRows, but for delimiter-separated values.

Content Security Policy

If a content security policy is in place, note that csv.parse, tsv.parse and dsv.parse require unsafe-eval in the script-src directive, due to their (safe) use of dynamic code generation for fast parsing. This also applies to the default constructors d3.csv, d3.tsv and dsv, which issue an HTTP GET request for the resource and then parse the response to objects using csv.parse, tsv.parse or dsv.parse.

If unsafe-eval cannot be used, then csv.parseRows, tsv.parseRows or dsv.parseRows can be used as a workaround, in combination with d3.text to retrieve the resource if necessary.