pandasで「Columns must be same length as key」が出た原因と対処法を試した話

Excelの氏名列を、姓と名の2列に分けようとした時のことです。いつものpandas処理のつもりで書いたら、`Columns must be same length as key` という英語エラーで止まりました。最初はkeyという言葉に引っ張られて、列名のスペルばかり見直していました。しかし、本当の原因は代入先の列数と、分割結果の列数が合っていなかったことでした。

この記事では、同じエラーで手が止まった時に、自分が確認した順番をまとめます。直接代入する前にtmpへ受けること、tmp.shapeで列数を見ること、tmp.headで中身を確認すること。この3つを先にやるだけで、どこで列数がずれているのかかなり見つけやすくなりました。非エンジニアの作業メモとして、試して少し楽になった方法を残しておきます。

氏名分割での列数誤解、作業停止

私は仕事で顧客リストを整理していました。氏名が1列にまとまっていたので、後の集計で使いやすいように姓と名へ分けようとした時のことです。いつもの感覚で `str.split` を使い、左側には新しく作る2列を指定した状態です。ところが実行した瞬間に、`Columns must be same length as key` という英語エラーで止まりました。

最初は `key` という言葉に引っ張られて、列名の指定ミスだと思い込んでいました。けれど、何度見ても左側の列名は合っています。そこでやっと「左側では2列を受け取るつもりなのに、右側では別の列数が返っているのかもしれない」と考え直しました。この切り替えができるまでに、かなり時間を使ってしまいました。

氏名列を姓と名に分けるだけのつもりで直接代入したら、英語エラーだけが出て手が止まりました。

`same length`が鍵、pandas代入エラー

pandasの代入では、左側に指定した列数と、右側から返ってくる列数がそろっている必要があります。たとえば左側で `[‘姓’, ‘名’]` の2列を指定しているのに、右側の分割結果が3列になっていると、pandasはどこへ入れればよいか判断できません。

このエラーは、列名そのものが存在しないという話ではありませんでした。左側の「受け皿」の数と、右側の「中身」の数が違うという話でした。私はここを混同していたので、列名チェックばかりを続けてしまいました。エラー文を読む時は、`key` という単語よりも、`same length` のほうを見るべきだったと感じています。

`tmp.shape`で分割エラーを早期特定

直接代入すると、右側で何列できているのかを確認する前に処理が止まってしまいます。そこで、まず分割結果だけを一時変数に受ける形へ変えました。

`tmp.shape` では、行数と列数を数字で見られます。自分では2列のつもりでも、ここで3列や4列なら左側の指定と合いません。次に `tmp.head` を見ます。どの行が余計に分かれているのかを目で追えました。

この確認を入れてから、修正の順番がかなり落ち着きました。いきなり元のDataFrameを書き換えず、まず右側だけを見ます。原因が右側にあると分かってから、分割方法や列数のそろえ方を直すようにしました。

最初は左辺の列名スペルだけを見直していましたが、tmp.shapeで右辺の列数を見るまで原因に気づけませんでした。

tmp.shapeを先に見るようにしてから、原因確認にかかる時間が30分ほど短くなりました。

氏名データ空白の罠

今回のデータでは、氏名の間に入っている空白がそろっていませんでした。多くの行は「姓 名」の形でしたが、一部だけ余計な空白が入っていました。見た目では気づきにくいのですが、`str.split(‘ ‘, expand=True)` は空白の位置に合わせて列を増やします。

そのため、ほとんどの行では2列に見えても、全体としては3列以上の結果になっていました。左側は2列を受け取る指定です。右側は3列以上を返しています。この差が、そのまま `Columns must be same length as key` につながっていました。

ここで大事だったのは、全行が同じ形だと思い込まないことでした。Excelで見た時に問題なさそうでも、前後の空白や連続スペースでpandasの分割結果は変わります。特に人名、住所、部署名のような自由入力に近い列では、最初に形を疑うほうが早いと感じました。

`n=1` で2列固定、最終確認

分割後の列数を2列に固定したい時は、`n=1` を指定する方法が使えました。これは「最初の区切りだけで分ける」という指定です。余計な空白が後ろにあっても、分割回数を増やしすぎないようにできます。

もちろん、どんなデータにもこれで対応できるわけではありません。姓と名の間以外にも意味のある区切りがある場合は、別のルールを考える必要があります。それでも、今回のように「最初の空白だけを区切りにしたい」ケースでは、列数を安定させる効果がありました。

私は修正後も、すぐに本番の列へ代入しませんでした。もう一度だけ一時変数で形を見て、2列になっていることを確認してから代入しました。この一手間を入れると、同じエラーを繰り返しにくくなります。

n=1で分割回数を固定しただけで、手元の300行ほどの氏名データは2列にそろって処理できました。

短い確認メモでエラー解決

このエラーは、直した直後は分かった気になります。でも、数日後に別のCSVで同じことをしました。その時には、また少し迷った記憶があります。そこで、短い確認メモを残すようにしました。

まず、左側に何列を指定したかを書きました。次に、右側の結果が何列かを残します。さらに、区切り文字も一緒にメモしました。空白なのか、カンマなのかを分けました。このメモだけでも、次の調査が楽になります。

私の場合は、メモを3行にしました。「左側は2列」と残しました。「右側は3列」と続けます。「余分な空白あり」で締めます。これで原因の説明がかなり楽になりました。

職場で相談する時にも助かりました。エラー文だけを見せるより伝わります。どこまで確認したかを共有できます。相手にも状況を説明しやすくなりました。自分用のメモですが、かなり効果がありました。あとで見返すと、同じミスを避けやすくなります。焦っている時ほど、短い記録が役に立ちました。完璧なメモでなくても大丈夫でした。次回の自分にも役立ちます。

applyでのリスト長不一致による代入エラー

もう一つの落とし穴として、applyを使った処理があります。これも同様のエラーを引き起こす原因になりました。行ごとにリストの長さが変わるような処理を書いた時のことです。一見すると全ての行で同じ処理が走っているように見えます。しかし、データによっては空のリストが返ることもありました。この状態で直接データフレームに代入しようとすると失敗します。リストの長さが揃っていないため、列数が合わなくなるのです。この時も、まずは結果をtmpに入れて確認しました。各行のリストの長さを調べてみると、やはりばらつきがあります。処理結果を揃えるための工夫が必要だと分かりました。

applyの処理内で、必ず同じ長さのリストを返すように修正します。足りない要素にはNoneを入れるようにしました。これでようやく、エラーなしで代入できるようになったのです。

applyで返すリストの長さが行によって違い、見た目では同じ処理に見えるのに代入時だけ失敗しました。

再インデックスで列数を揃える安全策

エラーを解消するために、データフレームの列数を確認しました。手元のCSVファイルを開いて列の数を数えてみます。追加しようとしていたリストの要素数とぴったり一致していません。足りない列を無理やり代入しようとしたことが原因だと気づきました。いきなり元のデータフレームに手を加えるのはやめます。まずは新しいデータフレームを作成しました。そこに必要な列をすべて揃える方法を試してみたのです。具体的には、再インデックス機能を使いました。列の並び順と個数を強制的に合わせる処理を入れます。この手順を踏むことで、エラーが出ずに無事にデータを追加できました。

最初から完成形を求めるのは危険かもしれません。一度安全な場所で列を補うというひと手間を加えます。それだけで、作業の安心感が大きく変わることを学びました。今はこの安全策を入れてから、本番のDataFrameに戻すようにしています。

pandas代入エラー、左右の形確認

今回のエラーで学んだのは、pandasの代入エラーを見た時に、左側だけを直しても解決しないことがあるという点でした。左側の列名が正しくても、右側の結果が違う形なら同じように止まります。

今は、複数列へ代入する前に、右側の結果を別の変数で確認するようにしています。列数が多い時は分割回数を固定しました。列が足りない時は、必要な列を補ってから代入します。applyを使う時も、返すリストの長さをそろえる形に直しました。

難しい理屈を全部覚えたわけではありません。それでも、「左と右の列数が同じか」を先に見るだけで、かなり落ち着いて対応できるようになりました。同じエラーで止まった人は、まず代入の右側だけを取り出して、形を確認してみてください。

関連リンクとチェックリスト

学習サービスとアンケート