{"record":{"id":"40f40f7eb2773fa7","repo":"pandas-dev/pandas","slug":"expected-dimension-1-data","errorCode":null,"errorMessage":"expected dimension <= 1 data","messagePattern":"expected dimension <= 1 data","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/sparse/array.py","lineNumber":2146,"sourceCode":"    \"\"\"\n    Convert ndarray to sparse format\n\n    Parameters\n    ----------\n    arr : ndarray\n    kind : {'block', 'integer'}\n    fill_value : NaN or another value\n    dtype : np.dtype, optional\n    copy : bool, default False\n\n    Returns\n    -------\n    (sparse_values, index, fill_value) : (ndarray, SparseIndex, Scalar)\n    \"\"\"\n    assert isinstance(arr, np.ndarray)\n\n    if arr.ndim > 1:\n        raise TypeError(\"expected dimension <= 1 data\")\n\n    if fill_value is None:\n        fill_value = na_value_for_dtype(arr.dtype)\n\n    if isna(fill_value):\n        mask = notna(arr)\n    else:\n        # cast to object comparison to be safe\n        if is_string_dtype(arr.dtype):\n            arr = arr.astype(object)\n\n        if is_object_dtype(arr.dtype):\n            # element-wise equality check method in numpy doesn't treat\n            # each element type, eg. 0, 0.0, and False are treated as\n            # same. So we have to check the both of its type and value.\n            mask = splib.make_mask_object_ndarray(arr, fill_value)\n        else:\n            mask = arr != fill_value","sourceCodeStart":2128,"sourceCodeEnd":2164,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/sparse/array.py#L2128-L2164","documentation":"Thrown by the internal _make_sparse helper (pandas/core/arrays/sparse/array.py:2146) which converts a numpy ndarray into pandas' sparse representation. SparseArray is fundamentally 1-D, so the helper hard-rejects any array whose ndim exceeds 1 before computing the sparsity mask. The TypeError (not ValueError) signals the input shape is structurally wrong for the sparse code path, not merely an invalid value.","triggerScenarios":"Constructing a SparseArray from a 2-D numpy array or DataFrame values: pd.arrays.SparseArray(np.zeros((3,4))). Calling any SparseArray operation that routes the backing ndarray through _make_sparse with >1-D data. Indirectly triggered by pd.Series(...).astype('Sparse[int]') when the Series was built from a DataFrame column slice that retained 2-D shape.","commonSituations":"User flattens a DataFrame incorrectly (df.values instead of df[col].values) and feeds it to a sparse dtype. Aggregation pipelines that preserve 2-D shape through to a sparse cast. Reading a single-column DataFrame and passing df rather than df.iloc[:,0].","solutions":["Flatten the input to 1-D before construction: pd.arrays.SparseArray(arr.ravel()) or pass a Series (pd.Series(arr.ravel(), dtype='Sparse[int]').","Select a single column from a DataFrame before sparse conversion: df['col'].astype('Sparse[int]') instead of df.astype(...).","Validate shape upstream with assert arr.ndim == 1 before calling sparse APIs."],"exampleFix":"// before\nimport numpy as np, pandas as pd\narr = np.zeros((3, 4))\npd.arrays.SparseArray(arr)  # raises TypeError\n\n// after\npd.arrays.SparseArray(arr.ravel())","handlingStrategy":"validation","validationCode":"import numpy as np\ndef to_sparse_safe(arr):\n    arr = np.asarray(arr)\n    if arr.ndim > 1:\n        arr = arr.ravel()\n    return pd.arrays.SparseArray(arr)","typeGuard":"def is_1d(nd: np.ndarray) -> bool:\n    return getattr(nd, 'ndim', None) == 1","tryCatchPattern":"try:\n    sa = pd.arrays.SparseArray(arr)\nexcept TypeError as e:\n    if 'expected dimension' in str(e):\n        sa = pd.arrays.SparseArray(np.asarray(arr).ravel())\n    else:\n        raise","preventionTips":["Always select a single Series (df[col]) before sparse conversion rather than passing df or df.values.","Add assert arr.ndim == 1 guards in pipelines that feed sparse dtypes.","Prefer pd.Series(...).astype('Sparse[...]') over pd.arrays.SparseArray for dataflow clarity."],"tags":["sparse","numpy","dimension","shape-validation"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}