# Categorical association tester

- Human page: https://happytails.ai/en/calculators/categorical-association-tester/
- Markdown: https://happytails.ai/en/calculators/categorical-association-tester.md
- Structured JSON: https://happytails.ai/agents/en/calculators/categorical-association-tester/index.json
- Visibility: public

## Tool capabilities

| Property | Value |
| --- | --- |
| Tool ID | `categorical-association-tester` |
| Category | calculators |
| Implementation | Registered implementation. Registration alone is not a production-quality guarantee. |
| Browser execution | Use the visible action or interactive controls. |
| Browser processing | Browser; see tool notes for network behavior. |
| HTTP API | Not callable through HTTP. |
| Browser-agent interface | run_current_tool |

### Implementation notes

Runs on your device in the background. Paste a counts table up to 20 x 20 or up to 10,000 raw rows, at most 1,000,000 characters.

### Inputs and settings

Text input: Counts table or raw CSV.

Example or placeholder shown in the interface (not a validated fixture):

```text
label,category A,category B
```

Paste counts with row labels in the first column, or raw rows with two category columns. Up to 1,000,000 characters. Review the settings before running.

| Setting | Meaning | Control type | Default | Constraints |
| --- | --- | --- | --- | --- |
| `inputMode` | Data | select | "table" | Allowed: table, raw |
| `rowColumn` | Row category column | text | "row" |  |
| `columnColumn` | Column category column | text | "column" |  |
| `test` | Test | select | "association" | Allowed: association, mcnemar |
| `yates` | Yates continuity correction for 2 x 2 tables | checkbox | true |  |
| `fisher` | Fisher exact test | select | "auto" | Allowed: auto, exact-2x2, exact-rxc, monte-carlo, none |
| `replicates` | Monte Carlo replicates | text | "2000" |  |
| `seed` | Monte Carlo seed | text | "happytails" |  |
| `confidence` | Confidence level for the 2 x 2 odds ratio | text | "0.95" |  |

### Browser-agent workflow

1. Open the human page in a browser that supports WebMCP.
2. Discover the interface exposed by that page; use its actual schema.
3. Select files on the page first when the tool requires files.
4. Call `run_current_tool` with valid input and settings.
5. Inspect the returned result or error and the displayed output. Retrieve files from the displayed download links.

Calls do not automatically copy or download results. Browser permissions still apply. Interface availability alone is not proof of successful execution.

### Planning specification

Runs locally in your browser in a background worker; nothing is uploaded. CSV up to 1,000,000 characters. Counts tables have 2 to 20 rows and 2 to 20 count columns, whole-number counts and unique row labels; raw data has up to 10,000 rows and 2 to 20 categories per column, with labels of at most 80 characters. McNemar's test needs a 2 x 2 table. Exact r x c enumeration allows at most 100,000 observations and 10,000,000 search steps. Monte Carlo uses 100 to 10,000 replicates and at most 100,000 observations, with observations times replicates at most 50,000,000. Confidence level 0.5 to 0.9999. Setting numbers are plain decimals with a digit before the point, such as 0.95, without exponents. In CSV with two or more columns a blank line between rows is rejected, and in one-column CSV it is a blank cell; blank lines after the last row are ignored. Downloads: a JSON report and CSV tables (tests, observed, expected and residuals).

This describes intended requirements. Use the implementation notes, interface schema and observed output to determine current support.

### Complete machine-readable capability record

```json
{
  "id": "categorical-association-tester",
  "category": "calculators",
  "built": true,
  "requirements": "Runs locally in your browser in a background worker; nothing is uploaded. CSV up to 1,000,000 characters. Counts tables have 2 to 20 rows and 2 to 20 count columns, whole-number counts and unique row labels; raw data has up to 10,000 rows and 2 to 20 categories per column, with labels of at most 80 characters. McNemar's test needs a 2 x 2 table. Exact r x c enumeration allows at most 100,000 observations and 10,000,000 search steps. Monte Carlo uses 100 to 10,000 replicates and at most 100,000 observations, with observations times replicates at most 50,000,000. Confidence level 0.5 to 0.9999. Setting numbers are plain decimals with a digit before the point, such as 0.95, without exponents. In CSV with two or more columns a blank line between rows is rejected, and in one-column CSV it is a blank cell; blank lines after the last row are ignored. Downloads: a JSON report and CSV tables (tests, observed, expected and residuals).",
  "implementation": {
    "fields": [
      {
        "key": "inputMode",
        "label": "Data",
        "value": "table",
        "type": "select",
        "values": [
          "table",
          "raw"
        ],
        "labels": {
          "table": "Counts table (first column holds row labels)",
          "raw": "Raw rows with two category columns"
        }
      },
      {
        "key": "rowColumn",
        "label": "Row category column",
        "value": "row",
        "type": "text",
        "maxLength": 200,
        "help": "Exact header of the first category column.",
        "showWhen": {
          "inputMode": [
            "raw"
          ]
        }
      },
      {
        "key": "columnColumn",
        "label": "Column category column",
        "value": "column",
        "type": "text",
        "maxLength": 200,
        "help": "Exact header of the second category column.",
        "showWhen": {
          "inputMode": [
            "raw"
          ]
        }
      },
      {
        "key": "test",
        "label": "Test",
        "value": "association",
        "type": "select",
        "values": [
          "association",
          "mcnemar"
        ],
        "labels": {
          "association": "Association (chi-square, G and Fisher)",
          "mcnemar": "McNemar for paired yes/no outcomes (2 x 2)"
        }
      },
      {
        "key": "yates",
        "label": "Yates continuity correction for 2 x 2 tables",
        "value": true,
        "type": "checkbox"
      },
      {
        "key": "fisher",
        "label": "Fisher exact test",
        "value": "auto",
        "type": "select",
        "values": [
          "auto",
          "exact-2x2",
          "exact-rxc",
          "monte-carlo",
          "none"
        ],
        "labels": {
          "auto": "Automatic: exact when possible, Monte Carlo for large tables",
          "exact-2x2": "Exact 2 x 2 with odds ratio interval",
          "exact-rxc": "Exact for any table size (small tables only)",
          "monte-carlo": "Seeded Monte Carlo",
          "none": "Do not run"
        },
        "showWhen": {
          "test": [
            "association"
          ]
        }
      },
      {
        "key": "replicates",
        "label": "Monte Carlo replicates",
        "value": "2000",
        "type": "text",
        "maxLength": 200,
        "help": "Whole number from 100 to 10,000.",
        "showWhen": {
          "test": [
            "association"
          ],
          "fisher": [
            "auto",
            "monte-carlo"
          ]
        }
      },
      {
        "key": "seed",
        "label": "Monte Carlo seed",
        "value": "happytails",
        "type": "text",
        "maxLength": 100,
        "help": "Any text of 1 to 100 characters. The same seed gives the same p-value.",
        "showWhen": {
          "test": [
            "association"
          ],
          "fisher": [
            "auto",
            "monte-carlo"
          ]
        }
      },
      {
        "key": "confidence",
        "label": "Confidence level for the 2 x 2 odds ratio",
        "value": "0.95",
        "type": "text",
        "maxLength": 200,
        "help": "A proportion from 0.5 to 0.9999.",
        "showWhen": {
          "test": [
            "association"
          ]
        }
      }
    ],
    "registrationFamily": "statistical-comparison-tests",
    "inputMaxLength": 1000000,
    "inputErrorCode": "STATISTICAL_COMPARISON_TESTS_TOO_LONG",
    "note": "Runs on your device in the background. Paste a counts table up to 20 x 20 or up to 10,000 raw rows, at most 1,000,000 characters.",
    "experience": {
      "automatic": false,
      "single": false,
      "inputMaxLength": 1000000,
      "inputMode": "text",
      "label": "Counts table or raw CSV",
      "placeholder": "label,category A,category B",
      "help": "Paste counts with row labels in the first column, or raw rows with two category columns. Up to 1,000,000 characters. Review the settings before running.",
      "action": null
    },
    "mode": "explicit",
    "interactive": false
  },
  "execution": "Browser interface",
  "api": null,
  "browser_agent": {
    "supported": true,
    "name": "run_current_tool",
    "discovery": "WebMCP on the human page in a supporting browser",
    "verification": "See audit/API-AUDIT.md; availability is not verification"
  }
}
```

## Page guide

Test association in a contingency table up to 20 x 20 with Pearson chi-square, Yates, the G test and Cramer's V, with expected-count checks and residuals. Fisher's exact test covers 2 x 2 tables and small larger tables, with a seeded Monte Carlo version for the rest, and McNemar's test covers paired yes/no data.

How can we improve this tool?

Report a problem or share an idea.

Please leave out private information. Your message and the tool name go to our team via PostHog.

### How to use Categorical association tester

1. Paste a counts table with row labels in the first column, or raw rows with two category columns.
2. Choose the association test or McNemar for paired yes/no outcomes.
3. Pick how the Fisher test runs, and a seed if Monte Carlo is used.
4. Run the tests, check the expected counts and residuals, and download the report.

## Useful next steps

- [Multiple testing correction](https://happytails.ai/en/calculators/multiple-testing-correction/) ([Markdown](https://happytails.ai/en/calculators/multiple-testing-correction.md))

- [Confidence interval calculator](https://happytails.ai/en/calculators/confidence-interval-calculator/) ([Markdown](https://happytails.ai/en/calculators/confidence-interval-calculator.md))

- [Sample size calculator](https://happytails.ai/en/calculators/sample-size-calculator/) ([Markdown](https://happytails.ai/en/calculators/sample-size-calculator.md))

## Chi-square and G tests

Pearson's chi-square compares observed counts with the counts expected under independence (Pearson 1900). For 2 x 2 tables the Yates correction is applied by R's rule (Yates 1934, Journal of the Royal Statistical Society Supplement 1:217). The G test is the likelihood-ratio version. Cramer's V scales chi-square to 0 to 1, and adjusted standardized residuals show which cells drive the result (Agresti 2013, Categorical Data Analysis, 3rd ed., section 2.4). Expected counts below 5 make the chi-square p-value unreliable and are flagged.

### Fisher exact test

For 2 x 2 tables the exact test follows R fisher.test, with the conditional maximum likelihood odds ratio and its exact interval. For larger tables the exact p-value adds the probability of every table with the same row and column totals that is no more likely than the observed one (Freeman and Halton 1951, Biometrika 38:141), up to 10,000,000 search steps. Automatic mode always runs the exact test for 2 x 2 tables. For larger tables it runs the exact enumeration when an expected count is below 5, and falls back to the seeded Monte Carlo estimate (1 + hits)/(B + 1), as R simulate.p.value, when the table is too large.

### McNemar test

For paired yes/no outcomes in a 2 x 2 table, McNemar's test uses the two discordant cells (McNemar 1947, Psychometrika 12:153), with an optional continuity correction and the exact binomial p-value.

### Limits

Each observation must be counted once and independently. Association is not causation, and a small p-value in a large table says nothing about which categories matter without the residuals.