Delimiter-Separated Values API

D3.js - Delimiter-Separated Values (DSV) API

Delimiter-Separated Values (DSV) are a common plain text format for storing tabular data. CSV (Comma-Separated Values) and TSV (Tab-Separated Values) are well-known examples. D3’s d3-dsv module provides robust tools for parsing DSV strings into JavaScript objects or arrays, and for formatting JavaScript objects/arrays back into DSV strings.

Configuring the DSV API

The d3-dsv module is included in the main D3.js bundle. If using modules individually, you can install d3-dsv.

<!-- Option 1: Include the full D3 library -->
<script src="https://d3js.org/d3.v7.min.js"></script>

<!-- Option 2: Include the standalone d3-dsv module -->
<!-- <script src="https://d3js.org/d3-dsv.v3.min.js"></script> -->

<script>
  // Example: Parsing a CSV string
  // const csvString = "name,value\nAlice,10\nBob,20";
  // const parsedData = d3.csvParse(csvString, d3.autoType);
  // console.log(parsedData);
</script>

Note: d3-dsv handles parsing and formatting of strings. To fetch DSV files from a URL, you’d typically use d3-fetch (e.g., d3.csv(url)) which internally uses d3-dsv for parsing after fetching the text content.

Core DSV Parsing Methods

• d3.csvParse(string[, rowConverter]) − Parses the given string as CSV data. Returns an array of objects, where each object represents a row. The optional rowConverter function is invoked for each row object, allowing you to transform values (e.g., convert strings to numbers or dates). d3.autoType is a common row converter for automatic type inference.
• d3.csvParseRows(string[, rowConverter]) − Parses the string as CSV data, but returns an array of arrays (strings), representing rows and columns. The rowConverter here processes an array of strings for each row.
• d3.tsvParse(string[, rowConverter]) − Similar to csvParse, but for TSV data (tab-separated).
• d3.tsvParseRows(string[, rowConverter]) − Similar to csvParseRows, but for TSV data.
• d3.dsvFormat(delimiter) − Returns a DSV parser/formatter object for a custom delimiter. This object has parse, parseRows, format, formatBody, formatRows, formatRow, formatValue methods.

Example: Parsing CSV String

const csvString = `year,make,model,price
1997,Ford,E350,3000.00
2000,Mercury,Cougar,2500.50
2005,Toyota,Camry,8000.00`;

// 1. Basic parsing (all values as strings)
const rawData = d3.csvParse(csvString);
console.log("Raw Data:", rawData);
// Output: Each price is a string e.g., "3000.00"

// 2. Parsing with d3.autoType for type conversion
const autoTypedData = d3.csvParse(csvString, d3.autoType);
console.log("Auto-Typed Data:", autoTypedData);
// Output: price is now a number e.g., 3000

// 3. Parsing with a custom row converter
const customParsedData = d3.csvParse(csvString, (d) => {
  return {
    year: new Date(+d.year, 0, 1), // Convert year to Date object
    make: d.make.toUpperCase(),    // Convert make to uppercase
    model: d.model,
    price: parseFloat(d.price)     // Convert price to float
  };
});
console.log("Custom Parsed Data:", customParsedData);

Core DSV Formatting Methods

• d3.csvFormat(rows[, columns]) − Formats an array of rows (objects) into a CSV string. The optional columns array specifies which properties to include and their order. If omitted, columns are inferred from the first row.
• d3.csvFormatBody(rows[, columns]) - Like d3.csvFormat but omits the header row.
• d3.csvFormatRows(rowsArray) − Formats an array of rowsArray (where each row is an array of strings) into a CSV string.
• d3.tsvFormat(rows[, columns]) − Similar to csvFormat, but for TSV.
• d3.tsvFormatBody(rows[, columns]) - Like d3.tsvFormat but omits the header row.
• d3.tsvFormatRows(rowsArray) − Similar to csvFormatRows, but for TSV.

Example: Formatting Data to CSV String

const dataToFormat = [
  { name: "Alice", score: 95, city: "New York" },
  { name: "Bob", score: 88, city: "London" },
  { name: "Charlie", score: 92, city: "Paris" }
];

// 1. Format with inferred columns
const csvString1 = d3.csvFormat(dataToFormat);
console.log("Formatted CSV (inferred columns):\n", csvString1);
// Output:
// name,score,city
// Alice,95,New York
// Bob,88,London
// Charlie,92,Paris

// 2. Format with specified columns
const csvString2 = d3.csvFormat(dataToFormat, ["name", "city", "score"]);
console.log("\nFormatted CSV (specified columns):\n", csvString2);
// Output:
// name,city,score
// Alice,New York,95
// Bob,London,88
// Charlie,Paris,92

// 3. Format array of arrays (rows)
const rowsArray = [
  ["fruit", "color"],
  ["apple", "red"],
  ["banana", "yellow"]
];
const csvString3 = d3.csvFormatRows(rowsArray);
console.log("\nFormatted CSV from rows array:\n", csvString3);
// Output:
// fruit,color
// apple,red
// banana,yellow

Practical Applications

The d3-dsv module is essential for:

• Data Import: Parsing CSV/TSV data pasted by users or read from local files (using browser File API combined with d3.text from d3-fetch or a FileReader, then d3.csvParse).
• Data Export: Allowing users to download data from your visualizations in CSV or TSV format.
• Interoperability: Working with data from spreadsheets or other systems that use DSV formats.
• Data Preprocessing: Often used in conjunction with d3-fetch when loading external DSV files.

For advanced DSV operations or handling files with unusual quoting or delimiters, explore the d3-dsv documentation.