pandas 1.4.3 - pandas.read_csv

pandas.read_csv(filepath_or_buffer, sep=NoDefault.no_default, 
				delimiter=None, header='infer', names=NoDefault.no_default, 
                index_col=None, usecols=None, squeeze=None, prefix=NoDefault.no_default,
                mangle_dupe_cols=True, 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=False, skip_blank_lines=True, parse_dates=None,
                infer_datetime_format=False, keep_date_col=False, date_parser=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, error_bad_lines=None,
                warn_bad_lines=None, on_bad_lines=None, delim_whitespace=False,
                low_memory=True, memory_map=False, float_precision=None, storage_options=None)

콤마로 구분된 값 (csv) 파일을 데이터프레임으로 불러옵니다.

이 함수는 또한 파일을 반복하거나 부분 부분으로 나누는 데 사용될 수도 있습니다.

데이터프레임이나 TextParser을 반환합니다.

파라미터

filepath_or_buffer: 문자열, 경로 객체나 파일과 같은 객체

문자열 경로가 들어갈 수 있습니다. 여기에는 http, ftp, s3, gs, file과 같은 URL 구조가 들어갈 수도 있습니다. file URL를 사용하려면 host 역시 설정해 주어야 합니다. 로컬 파일의 예로는 file://localhost/path/to/table.csv와 같이 쓰일 수 있습니다.

경로 객체를 보내려거든 os.PathLike에 해당해야 합니다.

read() 매소드를 사용해 파일같은 객체로 해당 객체를 참조할 수 있습니다. 예를 들어 파이썬 기본 함수인 open 함수 또는 StringIO를 사용해 파일을 다룰 수 있습니다.

 

sep: 문자열, (기본값: \t)

구분에 사용할 문자입니다. sep이 None이라면 C 엔진은 자동으로 구분자를 감지할 수 없습니다. 하지만 파이썬에서는 가능합니다. 파이썬의 파싱 엔진은 파이선에 기본 함수인 csv.Sniffer을 사용해 구분에 사용될 문자를 자동으로 감지할 수 있습니다.

한 글자보다 길면서 \s+가 아닌 구분자는 정규표현식으로 해석되며, 파이선 파싱 엔진의 사용이 강제됩니다. 정규표현식의 구분 문자는 따옴표가 있는 데이터를 무시하기 쉽다는 점에 주의하세요. 정규표현식의 예는 다음과 같습니다. \r\t

 

delimiter: 문자열 (기본값: None)

sep의 다른 이름입니다.

 

header: 정수, 정수의 배열, None (기본값: infer)

열 이름으로 사용하고 데이터가 시작할 위치를 나타내는 행 숫자입니다. 기본 동작 원리는 열 이름을 추측해 열의 이름들이 전달되지 않으면 이는 header=0과 동일하며, 열 이름은 파일의 첫 번째 줄로부터 추측됩니다. 반면, 열의 이름들이 전달되면 이는 header=None과 동일합니다. header=0을 명시해 이미 존재하는 열 이름들을 바꿀 수 있습니다. 헤더는 [0,1,3]과 같은 정수의 배열일 수 있습니다. 이처럼 정수의 배열을 넘김으로서 열에 대한 다중 인덱스를 사용할 수 있습니다. 이 경우 0,1,3번째 행 위치를 특정하며, 2와 같이 특정되지 않은 중간에 있는 행들은 생략됩니다. skip_blank_lines=True가 설정되어 있으면 이 파라미터가 주석 및 비어있는 줄을 무시한다는 점에 유의하십시요. 이 때 header=0은 파일의 첫 줄이 아닌 데이터의 첫 번째 줄을 의미합니다.

 

names: 배열과 같은 (선택)

사용할 열 이름의 배열입니다. 파일에 헤더 행이 이미 있다면, header=0을 명시해 열 이름을 덮어 써야 합니다. 배열에는 중복된 값이 올 수 없습니다.

 

index_col: 정수, 문자열, 연속된 정수나 문자열, False (선택, 기본값: None)

데이터프레임의 행 라벨로 사용할 열입니다. 이는 문자열 이름이나 열 인덱스로 지정됩니다. 연속된 숫자나 문자열이 주어지면 다중인덱스가 사용됩니다.

index_col=False는 판다스가 첫 번째 열을 인덱스로 사용하지 않게끔 합니다. 예를 들어 각 줄의 끝에 구획 문자가 있어 형태가 잘못된 파일을 다룰 때 사용될 수 있습니다.

 

usecols: 배열과 같은 혹은 콜러블 (선택)

열의 부분 집합을 반환하도록 합니다. 배열과 같다면 모든 요소들은 반드시 (문서 열의 정수 인덱스처럼) 위치를 잡고 있거나 사용자에 의해 names으로 혹은 문서의 헤더 행으로 부터 추측된 열 이름에 해당하는 문자열이어야만 합니다. names가 주어지면 헤더 행은 고려되지 않습니다. 배열과 같고 올바른 usecols 파라미터의 예시로는 [0, 1, 2] 혹은 ['foo', 'bar', 'baz']가 있습니다.

요소 순서는 무시되기에 usecols=[0, 1]와 [1, 0]는 같습니다. 요소 순서를 가진 data로부터 생성된 데이터프레임이  ['foo', 'bar']의 열 순서를 가지도록 하려면 pd.read_csv(data, usecol=['foo', 'bar'])['foo', 'bar']]을 사용할 수 있습니다. 반대로 ['bar', 'foo]의 열 순서를 가지도록 하려면 pd.read_csv(data, usecol=['foo', 'bar'])['bar', 'foo]]를 사용할 수 있습니다.

콜러블을 사용한다면, 콜러블 함수는 열 이름을 검사해 콜러블 함수가 True로 평가한 이름을 반환합니다. 예시로는 lambda x: x.upper() in ['AAA', 'BBB', 'DDD']를 들어볼 수 있습니다. 이런 파라미터를 사용함으로써 파싱을 더 빠르게, 메모리는 적게 사용할 수 있습니다.

 

squeeze: 불 (기본값: False, 1.4.0 버전부터는 추천되지 않음)

파싱된 데이터가 하나의 열을 가지고 있다면 시리즈 객체를 반환합니다.

 

prefix: 문자열 (선택, 1.4.0 버전부터는 추천되지 않음)

헤더가 없을 때 행 숫자 앞에 붙여지는 접두사입니다. 예를 들어 X라면 X0, X1, ... 이런 식으로 붙게 됩니다.

 

mangle_dupe_cols: 불 (기본값:True)

반복되는 열은 X, X.1, ... X.N으로 명시됩니다. False 시 열에 중복된 이름이 있을 경우 데이터가 겹쳐질 수 있습니다.

 

dtype: 타입 이름 혹은 열의 딕셔너리 -> 타입 (선택)

데이터나 열의 데이터 종류입니다. {'a': np.float64, 'b': np.int32, 'c': 'Int64'}와 같이 사용합니다. 가능한 na_values를 문자열이나 객체를 함께 사용하면 dtype을 해석하지 않고 그대로 보존합니다. 컨버터가 명시되면 dtype을 바꾸는 대신에 컨버터가 적용될 것입니다.

 

engine: {'c', 'python', 'pyarrow'} (선택)

사용할 파서 엔진입니다. C와 pyarrow 엔진은 더 빠르지만 python 엔진은 현재 다양한 매개변수를 지원합니다. 멀티쓰레딩은 현재 pyarrow 엔진에서만 지원됩니다.

1.4.0버전부터 pyarrow 엔진이 실험적으로 추가되었습니다. 몇몇 매개변수는 지원도지 않거나 제대로 동작하지 않을 것입니다.

 

converters: 딕셔너리 (선택)

특정한 열에 있는 값들을 바꾸기 위한 함수들의 딕셔너리입니다. 키 값은 정수형이나 열 이름이 될 수 있습니다.

 

ture_values: 리스트 (선택)

True로 여길 값들입니다

 

false_values: 리스트 (선택)

False로 여길 값들입니다.

 

skipinitialspace: 불 (기본값: False)

구분자 뒤의 공백을 무시합니다.

 

skiprows: 리스트같은, 정수나 콜러블 (선택)

인덱스가 0으로 지정된 경우 무시할 줄의 숫자가 되고, 인덱스가 정수형이면 파일의 시작 지점으로부터 무시할 줄의 숫자가 됩니다.

콜러블이면, 콜러블 함수는 행 인덱스를 검사하여 행이 무시된다면 True를, 아닌 경우 False를 반환합니다. 예시로는 lambda x: x in [0, 2]를 들어볼 수 있습니다.

 

skipfooter: 정수 (기본값: 0)

파일의 가장 마지막으로부터 무시할 줄의 개수입니다.

engine='c'에서는 지원하지 않습니다.

 

nrows: 정수 (선택)

파일에서 읽을 행들의 숫자입니다. 큰 파일의 부분 부분을 읽을 때 유용하게 사용할 수 있습니다.

 

na_values: 스칼라, 문자열, 리스트 같은, 혹은 딕셔너리 (선택)

NA 혹은 NaN으로 여겨지게 될 문자열입니다. 딕셔너리가 전달되면 특정한 각 열의 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’, ‘n/a’, ‘nan’, ‘null’.

 

keep_default_na: 불 (기본값: True)

파싱할 때 NaN값의 존재와 상관 없이, 그리고 na_values가 전달되었는지에 따라 다음과 같이 작동합니다.

• keep_default_na가 True이고 na_values가 명시되었으면, na_values에는 NaN 값이 추가되어 파싱에 사용됩니다.
• keep_default_na가 True이고 na_values가 명시되지 않았으면, NaN 값이 파싱에 사용됩니다.
• keep_default_na가 False이고 na_values가 명시되었다면, NaN 값으로 명시된 na_values가 파싱에 사용됩니다.
• keep_default_na가 False이고 na_values가 명시되지 않았다면, 문자열은 NaN으로 파싱되지 않습니다.

na_filter: 불 (기본값: True)

비어있는 값 마커(비어있는 문자열이나 na_values의 값)를 찾아냅니다. NA가 하나도 없는 데이터라면, na_filter=False로 설정하면 큰 파일을 읽어올 때 성능을 개선시킬 수 있습니다.

 

verbose: 불 (기본값: False)

숫자가 아닌 열에서 NA값의 갯수를 나타냅니다.

 

skip_blank_lines: 불 (기본값: True)

True로 설정되었으면 비어있는 줄을 NaN으로 해석하는 대신 그냥 무시해버립니다.

 

parse_dates: 불, 이름 및 정수의 리스트, 리스트의 리스트, 딕셔너리 (기본값: False)

• True라면 인덱스를 파싱합니다.
• 이름 및 정수의 리스트라면 열을 구분된 날짜 열로 파싱을 시도합니다.
• 리스트의 리스트라면 열들을 합치고 하나의 날짜 열로 파싱합니다.
• 딕셔너리라면 값의 숫자를 날짜로 파싱하고 키를 불러옵니다.

열이나 인덱스가 datetimes의 배열이 될 수 없다면 열이나 인덱스는 바뀌지 않은 채 객체 데이터 타입으로 반환됩니다. 비표준 datetime을 파싱하려면 pd.to_datetime을 pd.read_csv다음에 사용하세요. 시간대가 섞여 있는 인덱스나 열을 파싱하려면 date_parser을 명시해 pandas.to_datetime(utc=True)가 부분적으로 적용되게끔 하세요.

 

infer_datetime_format: 불 (기본값: False)

True이고 parse_dates가 사용되고 있다면 판다스는 열에서 datetime 문자열의 구조를 추측하려 할 것입니다. 또한 반드시 성공하는 경우에는 파싱하는 더 빠른 방법을 사용하세요. 몇몇 경우에 이렇게 하면 파싱 속도를 5~10배 빠르게 할 수 있습니다.

 

keep_date_col: 불 (기본값: False)

True이고 parse_dates가 여러 열을 합쳐 명시하고 있다면 본래 열을 그대로 둡니다.

 

date_parser: 함수 (선택)

연속된 문자열 열을 datetime 인스턴스의 배열로 변환하는데 사용할 함수입니다. 기본적으로 dateutil.parser.parser을 사용해 변환합니다. 만일 다음으로 넘어갈 때 예외가 발생한다면 판다스는 date.parser을 세 가지 다른 방법으로 불러오려 시도합니다.

1. (parse_date으로 정의된) 한개 이상의 배열을 매개변수로 넘깁니다.
2. parse_dates에서 정의된 열에서 나온 문자열 값들을 (행별로) 연결시켜 하나의 배열을 만들어 넘깁니다.
3. (parse_dates에서 정의된 열에 해당하는) 한 개 이상의 문자열을 사용하여 매개변수로 각 행마다 date_parser을 한 번씩 호출합니다.

dayfirst: 불 (기본값: False)

국제/유럽 형식인 DD/MM 형식으로 데이터를 가공합니다.

 

cache_dates: 불 (기본값: True)

True라면 datetime 변환에 적용하기 위해 고유하고 변환된 날짜 캐시를 사용합니다.

 

iterator: 불 (기본값: False)

반복 및 get_chunk()로 청크를 얻기 위한 TextFileReader 객체를 반환합니다.

 

chunksize: 정수 (선택)

반복을 위한 TextFileReader 객체를 반환합니다. 

 

compression: 문자열 혹은 딕셔너리 (기본값: infer)

디스트에 있는 데이터를 on-the-fly 방식(프로그램을 재시작할 필요가 없는) 압축 해제에 사용됩니다. infer 그리고 %s가 경로와 같다면 .gz, .bz2, .zip, .xz, .zst, (혹은 압축 없음) 확장자의 압축 형식을 감지합니다. .zip을 사용 중이라면 파일에는 읽어질 데이터 파일이 적어도 한 개 존재해야 합니다.

압축 해제를 할 필요가 없다면 None을 입력하세요.

해당 값은 또한 딕셔너리일 수도 있습니다. 이 딕셔너리의 키 값 method는 zip, gzip, bz2, zstd이어야만 합니다. 이들은 각자 zipfile.ZipFiile, gzip.GzipFile, bz2.BZ2File 혹은 zstandard.ZstdDecompressor로 전달됩니다. 예를 들어, compression={'method':'zstd', 'dict_data':my_comression_dict)은 직접 만든 압축의 딕셔너리를 사용한 Zstandard 압축 해제될 수 있습니다.

 

thousadns: 문자열 (선택)

천 단위를 구분합니다.

 

decimal: 문자열 (기본값: .)

소숫점 자리를 구분하기 위한 문자입니다.

 

lineterminator: 문자열(길이 1) (선택)

파일을 줄들로 쪼갤 문자입니다. C parser에서만 작동합니다.

 

quotechar: 문자열(길이 1) (선택)

따옴표가 있는 항목의 시작고 끝을 표기할 문자입니다. 따옴표가 있는 항목은 구획 문자를 포함할 수 있으나 이는 무시됩니다.

 

quoting: 정수 혹은 csv.QUOTE_* 객체 (기본값: 0)

csv.QUOTE_* 상수에 따른 필드 따옴표를 제어합니다. 다음 중 하나를 사용하세요: QUOTE_MINIMAL (0), QUOTE_ALL (1), QUOTE_NONNUMERIC (2) or QUOTE_NONE (3)

 

doublequote: 불 (기본값: True)

quotechar이 지정되고 quoting이 QUOTE_NONE이 아닐 때, 필드 안의 두 개 연속된 quochar 요소를 단일한 quochar 요소로 해석할 것인지를 나타냅니다.

 

escapechar: 문자열(길이 1) (선택)

다른 문자를 이스케이프할 한 글자 문자입니다.

 

comment: 문자열 (옵션)

파싱되어서는 안 될 줄의 나머지 부분이 보여줍니다. 줄 시작점에서 발견된다면 그 줄은 함께 무시될 것입니다. 이 파라미터는 반드시 한 글자 문자여야 합니다. (skip_blank_lines=True인 이상) 비어있는 줄과 마찬가지로 주석으로만 이루어진 줄들은 skiprows가 아닌 header 파라미터로 무시됩니다. 예를 들어 comment='#'이고 header=0으로  #empty\na,b,c\n1,2,3을 파싱한다면 a, b, c가 헤더로 여겨질 것입니다.

 

encoding: 문자열 (선택)

읽고 쓸때 사용될 인코딩입니다. 파이썬 기본 인코딩을 참고하세요

 

encoding_errors: 문자열 (선택, 기본값: 'strict')

인코딩 에러가 어떻게 처리될 것인가 결정합니다. 가능한 값 문서를 참고하세요.

 

dialect: 문자열 혹은 csv.Dialect (선택)

명시되면 이 파라미터는 delimiter, doublequote, escapechar, skipinitialspace, quotechar, quoting 값들을 덮어씌웁니다. 갚을 덮어씌어야 한다면 ParserWarning이 발생합니다. csv.Dialect 문서를 참고하세요.

 

error_bad_lines: 불 (선택, 기본값: None, 1.3.0 부터 추천되지 않음)

(너무 많은 ,을 가진 csv 줄처럼) 너무 많은 필드를 가지고 있는 줄은 기본적으로 예외를 발생시키고 데이터프레임은 반환되지 않습니다. False라면 이러한 잘못된 줄이 떨어져 나간 데이터프레임이 반환될 것입니다.

 

warn_bad_lines: 불(선택, 기본값: None, 1.3.0 부터 추천되지 않음)

error_bad_line이 False이고 warn_bad_lines가 True이면 각 잘못된 줄에 대한 경고가 출력됩니다.

 

on_bad_lines: {'error', 'warn', 'skip'} 혹은 콜러블 (기본값: 'error)

(필드가 너무 많은) 잘못된 줄에 대해 어떻게 대처할 지 결정합니다.

• error은 예외를 발생시킵니다.
• warn은 경고를 발생시키고 그 줄을 무시합니다.
• skip은 예외나 경고를 발생시키지 않고 그 줄을 무시합니다.

delim_whitespace: 불 (기본값: False)

공백이 구분자로 사용될 지 결정합니다. 이는 sep='\s+ 세팅과 동일합니다. 이 옵션이 True라면 delimiter 파라미터에는 아무것도 넘져지지 않는 것이 좋습니다

 

low_memory: 불 (기본값: True)

내부적으로 파일을 뭉텅이로 작업해 파싱 할 때 메모리 사용량을 낮추지만 혼합된 타입 추론이 사용될 것입니다. 혼합된 타입을 방지하기 위해서는 False로 설정하거나 dtype 파라미터로 타입을 지정하세요. 전체 파일이 하나의 데이터프레임으로 읽혀지더라도 chunksize나 iterator 파라미터를 사용해 데이터를 뭉텅이로 반환하는데 사용할 수 있습니다. (이는 C parser 에서만 작동합니다.)

 

memory_map: 불 (기본값: False)

파일경로가 filepath_or_buffer에 제공된다면 파일 객체를 바로 메모리에 매핑하고 그곳으로 데이터를 직접 접근합니다. 이 옵션을 사용하는 것은 성능을 개선할 수 있습니다. 이는 I/O 오버헤드가 더 이상 없기 때문입니다.

 

float_precision: 문자열 (선택)

C 엔진이 어떤 컨버터를 사용해 실수값을 처리할 것인지 명시합니다. 옵션으로는 일반적인 컨버터로 None 혹은 high가 있고, 일반적으로 낮은 정밀도의 판다스 컨버터로 legacy가 있고 라운드-트립 컨버터로 round_trip이 있습니다.

 

storage_options: 딕셔너리 (선택)

추가 옵션을 주어서 특별한 객체, 예를 들어 host, port, username, password를 다룰 수 있습니다.

HTTP(S) 주소의 키-값 쌍은 헤더 옵션으로 urllib로 전송됩니다. s3://, gcs://같은 주소들의 키-값 쌍은 fsspec로 전송됩니다. 이와 관련된 더 자세한 내용은 fsspec, urllib 문서에 있습니다.