# R to D3 Data Conversion

## Default conversion

R objects provided as `data` for D3 visualizations are converted to JSON using the jsonlite::toJSON() function, and use the same default serialization behavior as Shiny and htmlwidgets.

This corresponds to the following call to `jsonlite::toJSON()`:

    jsonlite::toJSON(
      dataframe = "columns", null = "null", na = "null", auto_unbox = TRUE,
      digits = getOption("shiny.json.digits", 16), use_signif = TRUE, force = TRUE,
      POSIXt = "ISO8601", UTC = TRUE, rownames = FALSE, keep_vec_names = TRUE,
      json_verabitm = TRUE
    )

#### Data frames

Data frames are serialized with a columns orientation as that is a more compact over the wire representation than rows orientation. When the data frame gets to the client r2d3 calls the HTMLWidgets.dataframeToD3() method to transform the data to a D3-friendly rows orientation.

Here is an example of the JSON columns-based representation of an R data frame:

    {
      "Sepal.Length": [5.1, 4.9, 4.7],
      "Sepal.Width": [3.5, 3, 3.2],
      "Petal.Length": [1.4, 1.4, 1.3],
      "Petal.Width": [0.2, 0.2, 0.2],
      "Species": ["setosa", "setosa", "setosa"]
    }

After we apply `HTMLWidgets.dataframeToD3()`, it will become:

    [
      {
        "Sepal.Length": 5.1,
        "Sepal.Width": 3.5,
        "Petal.Length": 1.4,
        "Petal.Width": 0.2,
        "Species": "setosa"
      },
      {
        "Sepal.Length": 4.9,
        "Sepal.Width": 3,
        "Petal.Length": 1.4,
        "Petal.Width": 0.2,
        "Species": "setosa"
      },
      {
        "Sepal.Length": 4.7,
        "Sepal.Width": 3.2,
        "Petal.Length": 1.3,
        "Petal.Width": 0.2,
        "Species": "setosa"
      }
    ]

## Custom conversion

If you don’t like the default JSON conversion provided for `data`, you can write your own function that uses jsonlite to perform a custom conversion. For example:

    data_to_json <- function(data) {
      jsonlite::toJSON(data, dataframe = "rows", auto_unbox = FALSE, rownames = TRUE)
    }

    r2d3(data = data_to_json(x), script = "barchart.js")

When a value returned from `jsonlite::toJSON()` is passed as the `data` argument r2d3 won’t attempt any additional conversion or transformation of the value.

## S3 conversion method

You can implement the `as_d3_data()` S3 method to provide custom converters for any R class. For example, you could create an S3 method for the `igraph` class to convert data into a JSON that is optimized for rendering by a D3 network visualization:

    as_d3_data.igraph <- function(x, ...) {
      # code to serialize igraph to D3 network friendly JSON
    }