# List View

{% hint style="info" %}
An Apollo license is required to use Cohort Browser on the DNAnexus Platform. Org approval may also be required. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

## When to Use List Views

List views can be used to visualize categorical data.

When creating a list view:

* The data must be from a field that contains either categorical or categorical multi-select data
* This field must contain no more than 20 distinct category values
* The values can be organized in a hierarchy

| Supported Data Types                                              |
| ----------------------------------------------------------------- |
| Categorical (<=20 distinct category values)                       |
| Categorical Multiple (<=20 distinct category values)              |
| Categorical Hierarchical (<=20 distinct category values)          |
| Categorical Hierarchical Multiple (<=20 distinct category values) |

### Using List Views to Visualize Hierarchically Organized Data

List views, unlike [row charts](/user/cohort-browser/chart-types/row-chart.md), can be used to visualize categorical data with values that are organized in a hierarchical fashion.

### Using List Views to Visualize Data from Two Different Fields

List views can be used to visualize categorical data from two different fields. The same restrictions apply to the fields whose values are displayed, as when creating a basic list view.

## Using List Views in the Cohort Browser

### Visualizing Data from a Single Field

In a list view in the Cohort Browser showing data from one field, each row displays a value, along with the number of records in the current cohort - the "count" - that contain this value. Also shown is a figure labeled "freq." - this is the percentage of all cohort records, that contain the value.

Below is a sample list view showing the distribution of values in a field *Episode type*. In the current cohort selection of 80 participants, 13 records contain the value "Delivery episode", which represents 16.25% of the current cohort size.

![List View in the Cohort Browser](/files/8JMFgH6LBkTSNxGSjK98)

{% hint style="info" %}
When records are missing values for the displayed field, the sum of the "count" figures is smaller than the total cohort size, and the sum of the "freq." figures is less than 100%. See [Chart Totals and Missing Data](/user/cohort-browser/chart-types.md#chart-totals-and-missing-data) for more information on how missing data affects chart calculations.
{% endhint %}

### Visualizing Data from Two Fields

To visualize data from two fields, select a categorical field, then select "List View" as your visualization type. In the field list, select a second categorical field as a secondary field.

Below is the default view of a sample list view visualizing data from two fields: *Critical care record origin* and *Critical care record format*:

![Primary Field Values in a List View Visualizing Data from Two Fields](/files/UIdPouPKvGeiOJikQeBS)

*Critical care record origin* is the primary field, *Critical care record format* is the secondary field.

Here, the user has clicked the ">" icon next to "Originating from Scotland" to display additional rows with detail on records that contain that value in the field *Critical care record origin*:

![Seeing Combinations of Field Values](/files/XF4ycfDe2xUlXpsctNlO)

Each of these additional rows shows the number of records that contain a particular value for *Critical care record format*, along with the value "Originating from Scotland" for *Critical care record origin*.

In these additional rows, "count" and "freq." figures refer to records having a particular combination of values, in the fields.

### Visualizing Complex Categorical Data

Below is an example of a list view used to visualize data in a categorical hierarchical field *Home State/Province*:

![List View of Hierarchical Categorical Data](/files/tUSj4GJrbJLmnTaYQa9U)

By default, only values in the category at the top level of the hierarchy are displayed.

Here, the user has clicked ">" next to one of these values, revealing additional rows that show how many records have the value "Canada" for the top-level category, in combination with different values in the category at the next level down:

![Seeing Combinations of Values in a Field Containing Hierarchical Categorical Data](/files/PpEPnuuqbgK87TFfGz0T)

In these additional rows, "count" and "freq." figures refer to records having a particular combination of values, in the fields. In the list view above, for example, a single record, representing 10% of the cohort, has both the value "Canada" for the top-level category, and "British Columbia" for the second-level category.

The following example shows how "count" and "freq." are calculated, for list views based on fields containing categorical data organized into multiple levels of hierarchy:

![Multiple Levels of Hierarchy](/files/3a6B2kkelzEtNyhO3toD)

For the bottommost row, "count" and "freq" refer to records having the following values:

* "Yes" for the category at the top of the hierarchy
* "9" for the category at the second level of the hierarchy
* "8" for the category at the third level of the hierarchy
* "7" for the category at the fourth level of the hierarchy
* "3" for the category at the bottom level of the hierarchy

### Locating Values in a List View

In cases where the field has categories at multiple levels and this makes it difficult to find a particular value, use the search box at the bottom of the list view to hone in on a row or rows containing that value:

![Using the Search Function in a List View](/files/OZ0kaZQ6sdjjfyMEISdq)

### List Views in Cohort Compare

In Cohort Compare mode, a list view can be used to compare the distribution of values in a field that's common to both cohorts. In this scenario, the list includes a color-coded column for each cohort, as well as color-coded "count" figures for each, as in this example:

![List view: Treatment/Medication Code in compare mode](/files/-MMUJKPpgYT83KBTlwda)

In each column, count and "freq." figures refer to the occurrence of values in the individual cohort, not across both cohorts.

## Preparing Data for Visualization in List Views

When [ingesting data using Data Model Loader](/developer/ingesting-data/data-model-loader/ingestion-data-types.md), the following data types can be visualized in list views:

* String Categorical
* String Categorical Hierarchical
* String Categorical Multi-Select
* String Categorical Multi-Select Hierarchical
* String Categorical Sparse
* String Categorical Sparse Hierarchical
* Integer Categorical
* Integer Categorical Hierarchical
* Integer Categorical Multi-Select
* Integer Categorical Multi-Select Hierarchical


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.dnanexus.com/user/cohort-browser/chart-types/list-view.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.