{"record":{"id":"bd6b04f0352bc0fb","repo":"pandas-dev/pandas","slug":"1-ndim-categorical-are-not-supported-at-this-tim","errorCode":null,"errorMessage":"> 1 ndim Categorical are not supported at this time","messagePattern":"> 1 ndim Categorical are not supported at this time","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/categorical.py","lineNumber":435,"sourceCode":"\n        # sanitize input\n        vdtype = getattr(values, \"dtype\", None)\n        if isinstance(vdtype, CategoricalDtype):\n            if dtype.categories is None:\n                dtype = CategoricalDtype(values.categories, dtype.ordered)\n        elif isinstance(values, range):\n            from pandas.core.indexes.range import RangeIndex\n\n            values = RangeIndex(values)\n        elif not isinstance(values, (ABCIndex, ABCSeries, ExtensionArray)):\n            values = com.convert_to_list_like(values)\n            if isinstance(values, list) and len(values) == 0:\n                # By convention, empty lists result in object dtype:\n                values = np.array([], dtype=object)\n            elif isinstance(values, np.ndarray):\n                if values.ndim > 1:\n                    # preempt sanitize_array from raising ValueError\n                    raise NotImplementedError(\n                        \"> 1 ndim Categorical are not supported at this time\"\n                    )\n                values = sanitize_array(values, None)\n            else:\n                # i.e. must be a list\n                arr = sanitize_array(values, None)\n                null_mask = isna(arr)\n                if null_mask.any():\n                    # We remove null values here, then below will re-insert\n                    #  them, grep \"full_codes\"\n                    arr_list = [values[idx] for idx in np.where(~null_mask)[0]]\n\n                    # GH#44900 Do not cast to float if we have only missing values\n                    if arr_list or arr.dtype == \"object\":\n                        sanitize_dtype = None\n                    else:\n                        sanitize_dtype = arr.dtype\n","sourceCodeStart":417,"sourceCodeEnd":453,"githubUrl":"https://github.com/pandas-dev/pandas/blob/71959b8cb9b2459c16e14b34f28b178ccfe14735/pandas/core/arrays/categorical.py#L417-L453","documentation":"Raised in the Categorical constructor when the input values array has more than one dimension (ndim > 1). Categorical only models 1-D enumeration data; multi-dimensional arrays are preemptively rejected before sanitize_array would raise a vaguer error.","triggerScenarios":"Passing a 2-D numpy array or a nested list-of-lists to `pd.Categorical(...)`, e.g. `pd.Categorical(np.zeros((3, 3)))` or `pd.Categorical([[1,2],[3,4]])`.","commonSituations":"Accidentally passing an entire DataFrame's values or a matrix instead of a single column; reshaping data and forgetting to flatten.","solutions":["Flatten or select a single column: `pd.Categorical(arr.ravel())` or `pd.Categorical(df['col'])`.","If you need per-column categoricals, apply Categorical to each column of the 2-D structure separately.","Validate `np.asarray(values).ndim == 1` before constructing."],"exampleFix":"# before\npd.Categorical(np.zeros((3, 3)))\n# after\npd.Categorical(np.zeros((3, 3)).ravel())","handlingStrategy":"validation","validationCode":"import numpy as np\n\ndef to_categorical_1d(values, **kw):\n    arr = np.asarray(values)\n    if arr.ndim > 1:\n        raise ValueError(f\"expected 1-D, got ndim={arr.ndim}\")\n    import pandas as pd\n    return pd.Categorical(arr, **kw)","typeGuard":"def is_1d_arraylike(x) -> bool:\n    import numpy as np\n    return hasattr(x, 'ndim') and np.asarray(x).ndim == 1","tryCatchPattern":"try:\n    cat = pd.Categorical(values)\nexcept NotImplementedError as e:\n    if 'ndim' in str(e):\n        import numpy as np\n        cat = pd.Categorical(np.asarray(values).ravel())\n    else:\n        raise","preventionTips":["Select a single column rather than passing a DataFrame/2-D array.","Check np.asarray(values).ndim == 1 before constructing.","Use .ravel() or .flatten() when you genuinely want all elements."],"tags":["categorical","constructor","ndim","notimplementederror"],"analyzedSha":"71959b8cb9b2459c16e14b34f28b178ccfe14735","analyzedAt":"2026-08-07T01:30:20.476Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}