CSVファイルはデータ分析で最も広く使われるファイル形式のひとつです。PandasではCSVファイルを簡単にデータフレームとして読み込むことができます。
この記事では、pd.read_csv()の基本的な使い方から、よく使う引数の詳細まで網羅的に解説します。
Pandasバージョン
本記事は、Pandas 2.2.3の情報を基に執筆しています。
import pandas as pd
print(pd.__version__)
>>
2.2.3pd.read_csv()
CSVファイルの読み込みにはpd.read_csv()を使用します。必須の引数として、読み込むファイルのパス（またはバッファ）を拡張子付きで指定します。相対パス・絶対パスのいずれも使用できます。
pandas.read_csv(filepath_or_buffer, *, sep=<no_default>, delimiter=None, header='infer', names=<no_default>, index_col=None, usecols=None, dtype=None, engine=None, converters=None, true_values=None, false_values=None, skipinitialspace=False, skiprows=None, skipfooter=0, nrows=None, na_values=None, keep_default_na=True, na_filter=True, verbose=<no_default>, skip_blank_lines=True, parse_dates=None, infer_datetime_format=<no_default>, keep_date_col=<no_default>, date_parser=<no_default>, date_format=None, dayfirst=False, cache_dates=True, iterator=False, chunksize=None, compression='infer', thousands=None, decimal='.', lineterminator=None, quotechar='"', quoting=0, doublequote=True, escapechar=None, comment=None, encoding=None, encoding_errors='strict', dialect=None, on_bad_lines='error', delim_whitespace=<no_default>, low_memory=True, memory_map=False, float_precision=None, storage_options=None, dtype_backend=<no_default>)基本的な使い方は以下の通りです。
import pandas as pd
df = pd.read_csv("input/apple_stock.csv")
引数一覧
| 引数 | 必須 | 説明 |
|---|---|---|
| filepath_or_buffer | ○ | 読み込むファイルのパスまたはバッファ |
| sep | 区切り文字。デフォルトは','（カンマ） | |
| delimiter | sepのエイリアス | |
| header | カラムとして利用する行番号。デフォルトは0 | |
| names | カラム名を配列で指定する | |
| index_col | インデックスとして使用する列を指定する | |
| usecols | 読み込むカラムを指定する | |
| dtype | データの型を指定する | |
| engine | 'c', 'python', 'pyarrow'のいずれかを指定 | |
| converters | 特定の列に関数処理を実行する | |
| true_values | Trueとして扱う値を指定 | |
| false_values | Falseとして扱う値を指定 | |
| skipinitialspace | 区切り文字後のスペースをスキップするか | |
| skiprows | スキップする行を指定する | |
| skipfooter | 末尾からスキップする行数 | |
| nrows | 読み込む行数を指定する | |
| na_values | 欠損値として扱う値を指定する | |
| keep_default_na | デフォルトの欠損値リストを使用するか | |
| na_filter | 欠損値検出を行うか | |
| verbose | 欠損値の数を表示する | |
| skip_blank_lines | 空白行をスキップするか | |
| parse_dates | 日付型に変換する列を指定する | |
| date_format | 日付の変換フォーマットを指定する | |
| dayfirst | DD/MM/YYYY形式で日付を読み込むか | |
| cache_dates | 日付変換結果をキャッシュするか | |
| iterator | 分割読み込みを行うか | |
| chunksize | 一度に読み込む行数を指定する | |
| compression | 圧縮フォーマットを指定する | |
| thousands | 数値の区切り文字を指定する | |
| decimal | 小数点の文字を指定する | |
| lineterminator | 改行コードを指定する | |
| quotechar | 引用符の文字を指定する | |
| quoting | 引用符の取扱いを指定する | |
| doublequote | 連続する引用符を1つとみなすか | |
| escapechar | エスケープ文字を指定する | |
| comment | コメント文字を指定する | |
| encoding | 文字コードを指定する | |
| encoding_errors | エンコードエラー時の処理を指定する | |
| dialect | 表記ルールを指定する | |
| on_bad_lines | 不正行の処理を指定する | |
| low_memory | メモリ消費を抑えるか | |
| memory_map | メモリマッピングを使用するか | |
| float_precision | 浮動小数点のコンバータを指定する | |
| storage_options | リモートファイルアクセス情報を指定する | |
| dtype_backend | バックエンドのデータタイプを指定する |
以降では、よく使う引数を中心に具体例とともに解説します。
基本引数
sep
区切り文字を指定します。デフォルトは','（カンマ）です。
CSVは「Comma Separated Values」の略ですが、sepを変更すればTSV（タブ区切り）など他の形式のファイルも読み込めます。
以下はタブ区切りファイル（TSV）を読み込む例です。
df = pd.read_csv("input/apple_stock.tsv", sep="\t")header
ヘッダー行を指定します。整数で行番号を指定すると、その行をヘッダーとして読み込みます。デフォルトはheader=0と同様の動作です。
df = pd.read_csv("input/apple_stock.csv", sep=",", header=0)複数行をヘッダーとして読み込む場合は、リスト形式で行番号を指定します。
df = pd.read_csv("input/apple_stock.csv", sep=",", header=[0, 1])
ヘッダーがない場合はNoneを指定します。
df = pd.read_csv("input/apple_stock.csv", sep=",", header=None)names
データフレームの列名をリスト形式で指定します。
cols = ["Date_renemed", "Open_renemed", "High_renemed", "Low_renemed", "Close_renemed", "Volume_renemed", "Adj_Close_renemed"]
df = pd.read_csv("input/apple_stock.csv", sep=",", names=cols)index_col
インデックスに割り当てる列を指定します。列番号（左端が0）または列名で指定できます。
df = pd.read_csv("input/apple_stock.csv", index_col=3)
df = pd.read_csv("input/apple_stock.csv", index_col="Open")usecols
読み込み対象の列を指定します。指定しない場合はすべての列が読み込まれます。列番号の配列または列名の配列で指定します。
注意: 列番号と列名の混合指定はエラーになります。
df = pd.read_csv("input/apple_stock.csv", usecols=[0, 1, 4])
df = pd.read_csv("input/apple_stock.csv", usecols=["Date", "High", "Close"])
dtype
読み込む列の型を指定します。データフレーム全体への一括指定か、辞書形式で列ごとに指定します。
注意: 数値型に一括変換する場合、文字列が混在しているとエラーになります。
# データフレーム全体を一括で型指定
df = pd.read_csv("input/apple_stock.csv", dtype=object)
df.dtypes
>>
Date object
High object
Low object
Open object
Close object
Volume object
Adj Close object
dtype: object列ごとに型を指定する場合は辞書形式を使用します。指定しなかった列はデフォルトの型推論が適用されます。
# 列ごとに型指定
df = pd.read_csv("input/apple_stock.csv", dtype={"Date": str, "Open": float, "High": object, "Low": float, "Close": float})
df.dtypes
>>
Date object
High object
Low float64
Open float64
Close float64
Volume float64
Adj Close float64
dtype: objectskiprows
読み込みをスキップする行を行番号のリストで指定します。callable関数を渡すことも可能で、関数はインデックス番号に対して適用されます。
df = pd.read_csv("input/apple_stock.csv", skiprows=[0,2])
# callable関数：偶数行をスキップ
df = pd.read_csv("input/apple_stock.csv", skiprows=lambda x: x % 2 == 0)skipfooter
読み込みをスキップする末尾の行数を整数で指定します。
注意:
engine='c'を指定している場合、この引数は無効となります。
df = pd.read_csv("input/apple_stock.csv", skipfooter=5)nrows
読み込む行数を整数で指定します。大容量ファイルの先頭部分のみを確認したい場合に便利です。
df = pd.read_csv("input/apple_stock.csv", nrows=5)欠損値（NA/NaN）の取扱い
na_values
欠損値（NA/NaN）として扱う値を追加指定します。デフォルトで以下の値が欠損値として認識されます。
デフォルトで欠損値として扱われる値
" ", "#N/A", "#N/A N/A", "#NA", "-1.#IND", "-1.#QNAN", "-NaN", "-nan", "1.#IND", "1.#QNAN", "<NA>", "N/A", "NA", "NULL", "NaN", "None", "n/a", "nan", "null "以下のCSVでは、1行目に#N/Aと-nanが含まれており、読み込み時に自動的に欠損値として扱われます。
デフォルトのリストに含まれない値を欠損値として扱いたい場合は、na_valuesで指定します。
df = pd.read_csv("input/apple_stock.csv", na_values="欠損値")na_filter
欠損値検出の有効/無効を切り替えます。Falseにすると、NaNやNULLもすべて文字列として読み込まれます。
df = pd.read_csv("input/apple_stock.csv", na_filter=False)日付・時刻の取扱い
デフォルトでは、日付・時刻データは文字列型として読み込まれます。日付型に変換するには、以下の引数を使用します。
検証用のCSVファイルを使用します。
df = pd.read_csv("input/date.csv")型を確認すると、日付列も文字列型（object）または数値型として読み込まれています。
df.dtypes
>>
Date object
DayFirst object
iso8601 object
Year int64
Month int64
Day int64
Time object
JapanFormat object
dtype: objectparse_dates
日付型に変換するカラムを指定します。指定したカラムはdatetime64[ns]に変換されます。日付型に変換できないカラムを指定した場合は、変換されずスキップされます。
df = pd.read_csv("input/date.csv", parse_dates=["Date"])
df.dtypes
>>
Date datetime64[ns]
DayFirst object
iso8601 object
Year int64
Month int64
Day int64
Time object
JapanFormat object
dtype: object複数カラムの指定も可能です。
df = pd.read_csv("input/date.csv", parse_dates=["Date", "iso8601"])
df.dtypes
>>
Date datetime64[ns]
DayFirst object
iso8601 datetime64[ns]
Year int64
Month int64
Day int64
Time object
JapanFormat object
dtype: object2重リストで複数カラムを指定すると、それらを結合して1つの日付カラムとして変換されます。
df = pd.read_csv("input/date.csv", parse_dates=[["Year", "Month", "Day"]])
keep_date_col
parse_datesで日付型に変換する際、変換元のカラムを残すかを指定します。デフォルトはFalse（元カラムを残さない）です。
df = pd.read_csv("input/date.csv", parse_dates=[["Year", "Month", "Day"]], keep_date_col=True)
date_format
日付変換時のフォーマットを指定します。"ISO8601"や"mixed"といった特殊指定も使用可能です。
以下は、日本語フォーマットの日付を変換する例です。
df = pd.read_csv("input/date.csv", parse_dates=["JapanFormat"], date_format="%Y年%m月%d日")
dayfirst
DD/MM/YYYY形式（イギリス式）の日付データを正しく読み込むための引数です。デフォルトではMM/DD/YYYYとして解釈されます。
デフォルトの状態でDayFirst列を読み込むと、月と日が入れ替わってしまいます。
df = pd.read_csv("input/date.csv", parse_dates=["DayFirst"])
dayfirst=Trueを指定することで、DD/MM/YYYYとして正しく変換されます。
df = pd.read_csv("input/date.csv", parse_dates=["DayFirst"], dayfirst=True)
イテレーション
iterator / chunksize
大容量のCSVファイルを分割して読み込むための引数です。iterator=Trueを指定すると、データフレームではなくTextFileReader（イテレータ）が返されます。
TFReader = pd.read_csv("input/apple_stock.csv", iterator=True)
type(TFReader)
>>
pandas.io.parsers.readers.TextFileReaderchunksizeで1回あたりの読み込み行数を指定し、ループ処理でデータを順次取得します。
TFReader = pd.read_csv("input/apple_stock.csv", iterator=True, chunksize=2, usecols=[0, 1, 2])
for chunk in TFReader:
print(chunk)
print("=====")
>>
Date High Low
0 2015-11-23 2095.610107 NaN
1 2015-11-24 2094.120117 2070.290039
=====
Date High Low
2 2015-11-25 2093.0 2086.300049
3 2015-11-26 2093.0 2086.300049
=====
Date High Low
4 2015-11-27 2093.290039 2084.129883
5 2015-11-28 2093.290039 2084.129883
=====
Date High Low
6 2015-11-29 2093.290039 2084.129883
7 2015-11-30 2093.810059 2080.409912
=====活用場面: メモリに収まりきらない大容量ファイルの処理や、DB操作でいうページング処理に相当する用途で活用できます。
数値の取扱い
数値データに関する引数を紹介します。
df = pd.read_csv("input/numbers.csv")thousands
数値に含まれる桁区切り文字を指定します。区切り文字を除去して数値として読み込みたい場合に使用します。
df = pd.read_csv("input/numbers.csv", thousands=",")decimal
小数点を表す文字を指定します。デフォルトはピリオド（.）です。
フランスやドイツなどでは小数点にカンマが使われることがあり、そのようなデータに対応する場合に使用します。
df = pd.read_csv("input/numbers.csv", decimal=",")ファイルの体裁に関する取扱い
lineterminator
改行コードを任意の1文字で指定します。engine='c'でのみ有効です。
df = pd.read_csv("input/apple_stock.csv", lineterminator='\r')quotechar
引用符として使用する文字を指定します。デフォルトはダブルクォート（"）です。
ダブルクォートで囲まれたデータはデフォルトで正しく処理されます。
df = pd.read_csv("input/apple_stock.csv")シングルクォートで囲まれたCSVの場合、デフォルトではシングルクォートも値の一部として読み込まれます。
quotecharにシングルクォートを指定すれば正しく読み込めます。
df = pd.read_csv("input/apple_stock.csv", quotechar="'")quoting
引用符の取扱いを指定します。以下の4つの値が指定可能です。
デフォルトはcsv.QUOTE_MINIMALです。csv.QUOTE_NONEを指定すると、ダブルクォートも引用符として認識しなくなります。
# csv.QUOTE_NONE
df = pd.read_csv("input/apple_stock.csv", quoting=3)doublequote
連続する引用符を1つの引用符とみなすかを指定します。デフォルトはTrueです。
以下のCSVでは、ヘッダを除いた1行目に連続したダブルクォートで囲った値が含まれています。
doublequote=True（デフォルト）の場合、連続するダブルクォートは1つとして認識されます。
df = pd.read_csv("input/apple_stock.csv")doublequote=Falseの場合、連続するダブルクォートがそのまま残り、意図しない挙動になる場合があります。
df = pd.read_csv("input/apple_stock.csv", doublequote=False)encoding
CSVファイルの文字コードを指定します。指定できる文字コードはPython標準に準拠します。
WindowsではShift_JISを拡張したcp932がよく使用されます。
df = pd.read_csv("input/apple_stock.csv", encoding="utf-8")
df = pd.read_csv("input/apple_stock.csv", encoding="cp932")エラーハンドリング
encoding_errors
文字コード変換時にエラーが発生した場合のハンドリングを指定します。デフォルトは'strict'です。
| 値 | 意味 |
|---|---|
'strict' | 変換できない文字があるとUnicodeErrorを送出する |
'ignore' | 変換できない値は無視される |
'replace' | 変換できない文字は�（U+FFFD）に変換される |
'backslashreplace' | 変換できない文字はバックスラッシュのエスケープシーケンスに変換される |
'surrogateescape' | 変換できない文字はサロゲートコードポイントに変換される |
df = pd.read_csv("input/apple_stock.csv", encoding_errors="replace")
df = pd.read_csv("input/apple_stock.csv", encoding_errors="ignore")on_bad_lines
不正なレコード（フィールド数が不一致な行など）が含まれていた場合のハンドリングを指定します。デフォルトは'error'です。
| 値 | 意味 |
|---|---|
'error' | Exceptionを送出し処理を停止する |
'warn' | Warningを送出し当該行をスキップして処理を継続する |
'skip' | 当該行をスキップして処理を継続する |
注意:
'skip'を使用するとスキップされたことを検知できないため、基本的には'error'または'warn'の使用を推奨します。
df = pd.read_csv("input/apple_stock.csv", on_bad_lines="warn")まとめ
今回は、pd.read_csv()を使ったCSVファイルの読み込み方法を紹介しました。
- 基本的な読み込み:
pd.read_csv("ファイルパス")で簡単に読み込める - 区切り文字（sep）: カンマ以外の区切り文字（タブなど）にも対応可能
- 欠損値処理:
na_valuesで独自の欠損値を指定、na_filter=Falseで欠損値検出を無効化 - 日付変換:
parse_datesとdate_formatの組み合わせで柔軟に対応 - 大容量ファイル:
iteratorとchunksizeで分割読み込みが可能
引数の数は多いですが、すべてを覚える必要はありません。必要な場面で適切な引数を参照し、活用してください。