Tutorial: a HuBMAP heatmap

This tutorial builds a heatmap of HuBMAP dataset counts by source organ and assay type. Each step adds to the previous spec; the highlighted lines are what changed. The charts read live metadata from the HuBMAP Data Portal.

1. Simple Table

The simplest specification just lists the source of the data. That is it! If no representation is specified a table will display all fields in the data.

{
  "source": {
    "name": "datasets",
    "source": "https://portal.hubmapconsortium.org/metadata/v0/udi/datasets.tsv"
  }
}

Open this step in the editor →

2. Table with Derived Fields

We can modify the previous spec to derive a new field from the existing data. In this case, we derive the organ of origin for each dataset from the origin_samples_unique_mapped_organs field, then group the datasets by this derived organ field and count how many datasets correspond to each organ.

{
  "source": {
    "name": "datasets",
    "source": "https://portal.hubmapconsortium.org/metadata/v0/udi/datasets.tsv"
  },
  "transformation": [
    {
      "derive": {
        "organ": "d.origin_samples_unique_mapped_organs"
      }
    },
    {
      "groupby": [
        "organ"
      ]
    },
    {
      "rollup": {
        "count": {
          "op": "count"
        }
      }
    }
  ]
}

Open this step in the editor →

3. Bar Chart

To create a simple bar chart that shows the number of datasets per organ, we can add a representation that specifies the mark type ("bar") and the x and y encodings to represent the organ and count, respectively.

{
  "source": {
    "name": "datasets",
    "source": "https://portal.hubmapconsortium.org/metadata/v0/udi/datasets.tsv"
  },
  "transformation": [
    {
      "derive": {
        "organ": "d.origin_samples_unique_mapped_organs"
      }
    },
    {
      "groupby": [
        "organ"
      ]
    },
    {
      "rollup": {
        "count": {
          "op": "count"
        }
      }
    }
  ],
  "representation": [
    {
      "mark": "bar",
      "mapping": [
        {
          "encoding": "x",
          "field": "organ",
          "type": "nominal"
        },
        {
          "encoding": "y",
          "field": "count",
          "type": "quantitative"
        }
      ]
    }
  ]
}

Open this step in the editor →

4. Stacked Bar Chart

We can further enhance the bar chart by stacking it based on the assay category. This allows us to see not only the number of datasets per organ but also how many datasets correspond to each assay type within those organs. We achieve this by adding an additional encoding for color, which represents the assay category.

{
  "source": {
    "name": "datasets",
    "source": "https://portal.hubmapconsortium.org/metadata/v0/udi/datasets.tsv"
  },
  "transformation": [
    {
      "derive": {
        "organ": "d.origin_samples_unique_mapped_organs"
      }
    },
    {
      "groupby": [
        "organ",
        "assay_category"
      ]
    },
    {
      "rollup": {
        "count": {
          "op": "count"
        }
      }
    }
  ],
  "representation": {
    "mark": "bar",
    "mapping": [
      {
        "encoding": "x",
        "field": "organ",
        "type": "nominal"
      },
      {
        "encoding": "y",
        "field": "count",
        "type": "quantitative"
      },
      {
        "encoding": "color",
        "field": "assay_category",
        "type": "nominal"
      }
    ]
  }
}

Open this step in the editor →

5. Heatmap

Now we can visualize the same data as a heatmap by modifying the mark type and mappings.

{
  "source": {
    "name": "datasets",
    "source": "https://portal.hubmapconsortium.org/metadata/v0/udi/datasets.tsv"
  },
  "transformation": [
    {
      "derive": {
        "organ": "d.origin_samples_unique_mapped_organs"
      }
    },
    {
      "groupby": [
        "organ",
        "assay_category"
      ]
    },
    {
      "rollup": {
        "count": {
          "op": "count"
        }
      }
    }
  ],
  "representation": [
    {
      "mark": "rect",
      "mapping": [
        {
          "encoding": "x",
          "field": "organ",
          "type": "nominal"
        },
        {
          "encoding": "y",
          "field": "assay_category",
          "type": "nominal"
        },
        {
          "encoding": "color",
          "field": "count",
          "type": "quantitative",
          "range": [
            "#eafab9",
            "#528aeb"
          ]
        }
      ]
    }
  ]
}

Open this step in the editor →

6. Heatmap with Text Overlay

Finally, we add an additional representation spec to overlay the count text onto the heatmap.

{
  "source": {
    "name": "datasets",
    "source": "https://portal.hubmapconsortium.org/metadata/v0/udi/datasets.tsv"
  },
  "transformation": [
    {
      "derive": {
        "organ": "d.origin_samples_unique_mapped_organs"
      }
    },
    {
      "groupby": [
        "organ",
        "assay_category"
      ]
    },
    {
      "rollup": {
        "count": {
          "op": "count"
        }
      }
    }
  ],
  "representation": [
    {
      "mark": "rect",
      "mapping": [
        {
          "encoding": "x",
          "field": "organ",
          "type": "nominal"
        },
        {
          "encoding": "y",
          "field": "assay_category",
          "type": "nominal"
        },
        {
          "encoding": "color",
          "field": "count",
          "type": "quantitative",
          "range": [
            "#eafab9",
            "#528aeb"
          ]
        }
      ]
    },
    {
      "mark": "text",
      "mapping": [
        {
          "encoding": "x",
          "field": "organ",
          "type": "nominal"
        },
        {
          "encoding": "y",
          "field": "assay_category",
          "type": "nominal"
        },
        {
          "encoding": "text",
          "field": "count",
          "type": "quantitative"
        }
      ]
    }
  ]
}

Open this step in the editor →