RAWGraphs Documentation

RAWGraphs is an open web tool for creating custom vector-based visualizations using the d3.js library.

Key Features:

• Data Input: Works with tabular data (spreadsheets, CSV) or copied-and-pasted text.
• Output: Generates SVG-based visualizations that can be edited in vector graphics editors (e.g., Inkscape, Adobe Illustrator) or embedded in web pages.
• Privacy: Data is processed locally in the web browser; no server-side storage or operations are performed.
• Extensibility: Supports custom layouts defined by users.

To run an instance of RAWGraphs on your local machine, follow these steps:

1. Ensure Requirements are met:

   • Git
   • Node.js (latest tested: 23.6.1)
   • Yarn (latest tested: 1.22)

2. Clone the repository:

   git clone https://github.com/rawgraphs/rawgraphs-app.git
   cd rawgraphs-app

3. Install dependencies:

   yarn install

4. Set OpenSSL environment variable: If you encounter OpenSSL issues, ensure you are using the legacy provider:

   export NODE_OPTIONS=--openssl-legacy-provider

5. Run in development mode:

   yarn start

Use deserializeProject to reconstruct a RAWGraphs project state from a serialized JSON object.

Requirements:

• The input object must have a version property equal to `

Use serializeProject to convert the current application state into a JSON-compatible object for exporting. This function captures user input, parsed data, data types, and chart-specific configurations (mapping and visual options).

// Note: This is a conceptual usage based on the function signature
const projectJson = serializeProject(
  userInput,
  userData,
  userDataType,
  parseError,
  unstackedData,
  unstackedColumns,
  data,
  separator,
  thousandsSeparator,
  decimalsSeparator,
  locale,
  stackDimension,
  dataSource,
  currentChart,
  mapping,
  visualOptions
);

The parseAndCheckData function is a wrapper around parseData that includes validation logic to ensure the resulting dataset is usable. It is specifically designed to handle errors and empty datasets gracefully.

Returns an array containing:

1. dataType: The identified format ('json', 'csv', or null).
2. data: The parsed data.
3. error: An error message string if parsing failed or the data is empty, otherwise null.
4. extra: An object containing metadata (e.g., the detected separator for CSV).

The parseData function attempts to identify and parse a data string into one of the supported formats: sparql, json, or csv. It iterates through available parsers and returns the first successful result.

Returns an array containing:

1. dataType: The identified format ('sparql', 'json', or 'csv'), or null if parsing fails.
2. parsed: The parsed data structure.
3. extra: An object containing metadata (e.g., the detected separator for CSV).

The normalizeJsonArray function transforms a JSON array into a flattened object structure suitable for tabular visualization. It handles several edge cases:

• Arrays within elements: Converts arrays into space-separated strings of scalar values.
• Nested objects: Flattens one level of nesting using dot notation (e.g., { a: { b: 1 } } becomes { 'a.b': 1 }).
• Arrays of arrays: Converts them into objects with keys like Column 1, Column 2, etc.
• Scalar values: Wraps them in an object with a value key.

It only preserves scalar types (string, number, boolean) or null values.