> For the complete documentation index, see [llms.txt](https://docs.sdv.dev/sdmetrics/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sdv.dev/sdmetrics/data-metrics/diagnostic/categoryadherence.md).

# CategoryAdherence

This metric measures whether a synthetic column adheres to the same category values as the real data. (The synthetic data should not be inventing new category values that are not originally present in the real data.)

## Data Compatibility

* **Categorical:** This metric is meant for discrete, categorical data
* **Ordinal**: This metric is meant for discrete, ordinal data 
* **Boolean:** This metric is meant for boolean data

*If you have missing values in the real data, then the metric will consider them valid in the synthetic data. Otherwise, they will be marked as an invalid category. All types of missing values (NaN, None, etc. will be counted as the same category of 'missing'.)*

## Score

* **(best) 1.0**: All category values in the synthetic data were present in the real data
* **(worst) 0.0**: None of the category values in the synthetic data were present in the real data

Any score in between tells us the proportion of data points that are adhering to the correct values. For example, 0.6 means that 60% of synthetic data points have a value present in in the real data. Meanwhile, the remaining 40% contain new values that were never present in the real data.

## How does it work?

This metric extracts the set of unique categories, that are present in the real column, *Cr*. 

Then it finds the of data points of the synthetic data, *s*, that are found in the set *C*. The score is the proportion of these data points as compared to all the synthetic data points.

$$
score = \frac{| s, s \in C\_r |}{|s|}
$$

In some cases the allowable set of categories (*C*) as well as the allowable missing values may be more expansive than what is present in the real data. This can happen when your real data is actually a smaller subset of the entire database. In this case you can override the allowable ranges by providing the `range_values` and `range_is_nullable` parameters. If provided, these values will be used for checking the synthetic data rather than category values derived from the real data. 

## **Usage**

{% hint style="success" %}
**Recommended Usage:** The [Diagnostic Report ](/sdmetrics/data-metrics/diagnostic/diagnostic-report-api.md)applies this metric to applicable columns.
{% endhint %}

To manually apply this metric, access the `single_column` module and use the `compute` method.

```python
from sdmetrics.single_column import CategoryAdherence

CategoryAdherence.compute(
    real_data=real_table['column_name'],
    synthetic_data=synthetic_table['column_name']
)
```

**Parameters**

* (required) `real_data`: A pandas.Series object with the column of real data
* (required) `synthetic_data`: A pandas.Series object with the column of synthetic data 
* `range_values`: A list containing all the allowable category values that the data can possible have. This may be more expansive than the values present in the real training data. If provided, this will be used as the set of unique categories, rather than compute it from the `real_data`.
* `range_is_nullable`: A boolean describing whether the column is allowed to be null. This can be `True` even if the real training data does not have any missing values. If provided, this value will be used instead of computing it from the `real_data`.

## **FAQs**

<details>

<summary>Is there an equivalent metric for continuous data?</summary>

For continuous datasets, many values are possible. Use the [BoundaryAdherence](/sdmetrics/data-metrics/diagnostic/boundaryadherence.md) metric to ensure they within the correct min/max bounds.

</details>

<details>

<summary>Does this metric measure quality or data coverage? </summary>

No. This metric is a measure of validity, as we generally consider discrete data to be *valid* only if it contains the correct category values.

* **Data quality** refers to the frequency of each particular category value. To compare this, use the [TVComplement](/sdmetrics/data-metrics/quality/tvcomplement.md) metric.
* **Data coverage** refers to the idea that the synthetic data should cover at least 1 of each category value. To measure this, use the [CategoryCoverage](/sdmetrics/data-metrics/quality/categorycoverage.md) metric.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sdv.dev/sdmetrics/data-metrics/diagnostic/categoryadherence.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.