<h4 dir="auto">Code Sample</h4>
<div class="highlight highlight-source-python notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="import pandas as pd
df = pd.DataFrame([&quot;x&quot;, &quot;y&quot;, &quot;z&quot;], dtype='category')
df.replace({&quot;x&quot;: &quot;y&quot;})"><pre class="notranslate"><span class="pl-k">import</span> <span class="pl-s1">pandas</span> <span class="pl-k">as</span> <span class="pl-s1">pd</span>
<span class="pl-s1">df</span> <span class="pl-c1">=</span> <span class="pl-s1">pd</span>.<span class="pl-v">DataFrame</span>([<span class="pl-s">"x"</span>, <span class="pl-s">"y"</span>, <span class="pl-s">"z"</span>], <span class="pl-s1">dtype</span><span class="pl-c1">=</span><span class="pl-s">'category'</span>)
<span class="pl-s1">df</span>.<span class="pl-en">replace</span>({<span class="pl-s">"x"</span>: <span class="pl-s">"y"</span>})</pre></div>
<h4 dir="auto">Problem description</h4>
<h5 dir="auto">Current output</h5>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="~/.local/lib/python3.6/site-packages/pandas/core/internals.py in __init__(self, values, placement, ndim, fastpath)
    109             ndim = values.ndim
    110         elif values.ndim != ndim:
--&gt; 111             raise ValueError('Wrong number of dimensions')
    112         self.ndim = ndim
    113 

ValueError: Wrong number of dimensions"><pre class="notranslate"><code class="notranslate">~/.local/lib/python3.6/site-packages/pandas/core/internals.py in __init__(self, values, placement, ndim, fastpath)
    109             ndim = values.ndim
    110         elif values.ndim != ndim:
--&gt; 111             raise ValueError('Wrong number of dimensions')
    112         self.ndim = ndim
    113 

ValueError: Wrong number of dimensions
</code></pre></div>
<h5 dir="auto">Expected output</h5>
<p dir="auto">The following DataFrame:</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="   0
0  y
1  y
2  z"><pre class="notranslate"><code class="notranslate">   0
0  y
1  y
2  z
</code></pre></div>
<h5 dir="auto">Explanation</h5>
<p dir="auto">At the very least, the error message is confusing. But I think this is a bug in the <code class="notranslate">replace</code> method, that should just work with categorical data.</p>
<p dir="auto">This problem has confused other people before: <a href="https://stackoverflow.com/questions/48807344/how-to-replace-values-in-multiple-categoricals-in-a-pandas-dataframe" rel="nofollow">https://stackoverflow.com/questions/48807344/how-to-replace-values-in-multiple-categoricals-in-a-pandas-dataframe</a></p>
<h4 dir="auto">Output of <code class="notranslate">pd.show_versions()</code></h4>
<details>
<p dir="auto">commit: None<br>
python: 3.6.5.final.0<br>
python-bits: 64<br>
OS: Linux<br>
OS-release: 4.17.3-200.fc28.x86_64<br>
machine: x86_64<br>
processor: x86_64<br>
byteorder: little<br>
LC_ALL: None<br>
LANG: en_GB.UTF-8<br>
LOCALE: en_GB.UTF-8</p>
<p dir="auto">pandas: 0.22.0<br>
pytest: 3.3.2<br>
pip: 9.0.3<br>
setuptools: 39.2.0<br>
Cython: 0.27.3<br>
numpy: 1.14.1<br>
scipy: 0.19.1<br>
pyarrow: None<br>
xarray: None<br>
IPython: 6.4.0<br>
sphinx: None<br>
patsy: None<br>
dateutil: 2.6.1<br>
pytz: 2018.3<br>
blosc: None<br>
bottleneck: None<br>
tables: None<br>
numexpr: None<br>
feather: None<br>
matplotlib: 2.0.2<br>
openpyxl: None<br>
xlrd: None<br>
xlwt: None<br>
xlsxwriter: None<br>
lxml: None<br>
bs4: None<br>
html5lib: 0.9999999<br>
sqlalchemy: 1.2.7<br>
pymysql: None<br>
psycopg2: None<br>
jinja2: 2.10<br>
s3fs: None<br>
fastparquet: None<br>
pandas_gbq: None<br>
pandas_datareader: None</p>
</details>
<h4 dir="auto">Code Sample, a copy-pastable example if possible</h4>
<div class="highlight highlight-source-python notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="In [2]: pd.Series([1, 2, 3, 2], dtype='category').replace(2, 1) # good
Out[2]: 
0    1
1    1
2    3
3    1
dtype: category
Categories (3, int64): [1, 2, 3]

In [3]: pd.Series([1, 2, 3, 2], dtype='category').replace(2, 15) # bad
Out[3]: 
0     1
1    15
2     3
3    15
dtype: int64

"><pre class="notranslate"><span class="pl-v">In</span> [<span class="pl-c1">2</span>]: <span class="pl-s1">pd</span>.<span class="pl-v">Series</span>([<span class="pl-c1">1</span>, <span class="pl-c1">2</span>, <span class="pl-c1">3</span>, <span class="pl-c1">2</span>], <span class="pl-s1">dtype</span><span class="pl-c1">=</span><span class="pl-s">'category'</span>).<span class="pl-en">replace</span>(<span class="pl-c1">2</span>, <span class="pl-c1">1</span>) <span class="pl-c"># good</span>
<span class="pl-v">Out</span>[<span class="pl-c1">2</span>]: 
<span class="pl-c1">0</span>    <span class="pl-c1">1</span>
<span class="pl-c1">1</span>    <span class="pl-c1">1</span>
<span class="pl-c1">2</span>    <span class="pl-c1">3</span>
<span class="pl-c1">3</span>    <span class="pl-c1">1</span>
<span class="pl-s1">dtype</span>: <span class="pl-s1">category</span>
<span class="pl-v">Categories</span> (<span class="pl-c1">3</span>, <span class="pl-s1">int64</span>): [<span class="pl-c1">1</span>, <span class="pl-c1">2</span>, <span class="pl-c1">3</span>]

<span class="pl-v">In</span> [<span class="pl-c1">3</span>]: <span class="pl-s1">pd</span>.<span class="pl-v">Series</span>([<span class="pl-c1">1</span>, <span class="pl-c1">2</span>, <span class="pl-c1">3</span>, <span class="pl-c1">2</span>], <span class="pl-s1">dtype</span><span class="pl-c1">=</span><span class="pl-s">'category'</span>).<span class="pl-en">replace</span>(<span class="pl-c1">2</span>, <span class="pl-c1">15</span>) <span class="pl-c"># bad</span>
<span class="pl-v">Out</span>[<span class="pl-c1">3</span>]: 
<span class="pl-c1">0</span>     <span class="pl-c1">1</span>
<span class="pl-c1">1</span>    <span class="pl-c1">15</span>
<span class="pl-c1">2</span>     <span class="pl-c1">3</span>
<span class="pl-c1">3</span>    <span class="pl-c1">15</span>
<span class="pl-s1">dtype</span>: <span class="pl-s1">int64</span>
</pre></div>
<h4 dir="auto">Problem description</h4>
<p dir="auto">I think <code class="notranslate">replace()</code> called with unknown category should either raise an error, or just replace the element in the list of categories.</p>
<p dir="auto">The current behavior is even more annoying if you do</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="In [4]: pd.Series([1, 2, np.nan, 2], dtype='category').replace(np.nan, 15)
Out[4]: 
0     1.0
1     2.0
2    15.0
3     2.0
dtype: float64"><pre class="notranslate"><code class="notranslate">In [4]: pd.Series([1, 2, np.nan, 2], dtype='category').replace(np.nan, 15)
Out[4]: 
0     1.0
1     2.0
2    15.0
3     2.0
dtype: float64
</code></pre></div>
<p dir="auto">because precisely the operation of removing NaNs from integers makes then floats! Notice, for comparison, that <code class="notranslate">pd.Series([1, 2, np.nan, 2], dtype='category').fillna(15)</code> raises a <code class="notranslate">ValueError</code>.</p>
<p dir="auto">This is related to (the discussion about) <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="272476776" data-permission-text="Title is private" data-url="https://github.com/pandas-dev/pandas/issues/18185" data-hovercard-type="issue" data-hovercard-url="/pandas-dev/pandas/issues/18185/hovercard" href="https://github.com/pandas-dev/pandas/issues/18185">#18185</a> .</p>
<h4 dir="auto">Expected Output</h4>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="In [3]: pd.Series([1, 2, 3, 2], dtype='category').replace(2, 15)
Out[3]: 
0    1
1    15
2    3
3    15
dtype: category
Categories (3, int64): [1, 3, 15]"><pre class="notranslate"><code class="notranslate">In [3]: pd.Series([1, 2, 3, 2], dtype='category').replace(2, 15)
Out[3]: 
0    1
1    15
2    3
3    15
dtype: category
Categories (3, int64): [1, 3, 15]
</code></pre></div>
<h4 dir="auto">Output of <code class="notranslate">pd.show_versions()</code></h4>
<details>
<h2 dir="auto">INSTALLED VERSIONS</h2>
<p dir="auto">commit: <a class="commit-link" data-hovercard-type="commit" data-hovercard-url="https://github.com/pandas-dev/pandas/commit/9e3ad63cdb030c6b369d9d822469bb968e2d1804/hovercard" href="https://github.com/pandas-dev/pandas/commit/9e3ad63cdb030c6b369d9d822469bb968e2d1804"><tt>9e3ad63</tt></a><br>
python: 3.5.3.final.0<br>
python-bits: 64<br>
OS: Linux<br>
OS-release: 4.9.0-3-amd64<br>
machine: x86_64<br>
processor:<br>
byteorder: little<br>
LC_ALL: None<br>
LANG: it_IT.UTF-8<br>
LOCALE: it_IT.UTF-8</p>
<p dir="auto">pandas: 0.22.0.dev0+114.g9e3ad63cd<br>
pytest: 3.2.3<br>
pip: 9.0.1<br>
setuptools: 36.7.0<br>
Cython: 0.25.2<br>
numpy: 1.12.1<br>
scipy: 0.19.0<br>
pyarrow: None<br>
xarray: None<br>
IPython: 6.2.1<br>
sphinx: 1.5.6<br>
patsy: 0.4.1<br>
dateutil: 2.6.1<br>
pytz: 2017.2<br>
blosc: None<br>
bottleneck: 1.2.0dev<br>
tables: 3.3.0<br>
numexpr: 2.6.1<br>
feather: 0.3.1<br>
matplotlib: 2.0.0<br>
openpyxl: None<br>
xlrd: 1.0.0<br>
xlwt: 1.1.2<br>
xlsxwriter: 0.9.6<br>
lxml: None<br>
bs4: 4.5.3<br>
html5lib: 0.999999999<br>
sqlalchemy: 1.0.15<br>
pymysql: None<br>
psycopg2: None<br>
jinja2: 2.10<br>
s3fs: None<br>
fastparquet: None<br>
pandas_gbq: None<br>
pandas_datareader: 0.2.1</p>
</details>