Чтение
В этом разделе рассматриваются различные входные данные и параметры, поддерживаемые типом CSV.File
и функцией CSV.read
, с примечаниями о совместимости с другими функциями чтения (CSV.Rows
, CSV.Chunks
и т. д.).
input
Обязательный аргумент для операции чтения. Входные данные должны представлять собой текст в кодировке ASCII или UTF-8; если текст имеет другую кодировку, преобразуйте его в UTF-8 с помощью пакета StringEncodings.jl.
Любые входные данные с разделителями в конечном итоге преобразуются в байтовый буфер (Vector{UInt8}
) для анализа или обработки. Учитывая это, давайте рассмотрим различные поддерживаемые типы входных данных.
-
Имя файла в виде
String
илиFilePath
; при анализе выполняется вызовMmap.mmap(string(file))
с целью получить байтовый буфер для данных файла. Если входные данные сжаты посредством gzip, напримерfile.gz
, они сначала распаковываются во временный файл с помощью пакета CodecZlib.jl, а затем сопоставляются с байтовым буфером в памяти. Распаковка также может производиться в памяти. Для этого нужно передать аргументbuffer_in_memory=true
. Имейте в виду, что автоматически распаковываются только данные, сжатые gzip; для распаковки сжатых данных других видов воспользуйтесь соответствующим пакетом и передайте на вход объект IO илиVector{UInt8}
с распакованными данными. -
Vector{UInt8}
илиSubArray{UInt8, 1, Vector{UInt8}}
: если у вас уже есть готовый байтовый буфер, его можно передать напрямую. Строку в формате CSV можно передать какCSV.File(IOBuffer(str))
. -
IO
илиCmd
: объектIO
илиCmd
можно передать напрямую. Он будет помещен во временный файл, а затем сопоставлен с байтовым вектором в памяти. Чтобы не прибегать к временному файлу и вместо этого буферизовать данные в памяти, передайтеbuffer_in_memory=true
. -
Файл из Интернета можно запросить посредством вызова
HTTP.get(url).body
, после чего можно получить доступ к данным в полеbody
как к объектуVector{UInt8}
, который можно передать напрямую для анализа. В версиях Julia 1.6 и выше можно также воспользоваться пакетомDownloads
из библиотеки stdlib, например, вызватьDownloads.download(url)
и передать результат для анализа.
header
Именованный аргумент header
управляет обработкой имен столбцов в файлах. По умолчанию предполагается, что имена столбцов находятся в первой строке входных данных, то есть header=1
. Другие допустимые значения для аргумента header
:
-
Integer
, напримерheader=2
: укажите номер строки, в которой находятся имена столбцов, в виде значения типаInteger
. -
Bool
, напримерheader=false
: в данных нет имен столбцов; они будут сгенерированы автоматически в соответствии с количеством столбцов, напримерColumn1
,Column2
и т. д. -
Vector{String}
илиVector{Symbol}
: укажите имена столбцов вручную в виде строк или символов; количество имен должно совпадать с количеством столбцов в данных. Будет создана копия объектаVector
, которая затем преобразуется вVector{Symbol}
. -
AbstractVector{<:Integer}
: в редких случаях заголовки могут находиться в нескольких строках. Если передать коллекцию номеров строк, проанализирована будет каждая строка и итоговые имена столбцов получаются путем объединения значений из них.
normalizenames
Определяет то, нормализуются ли имена столбцов, то есть преобразуются ли они в допустимые идентификаторы Julia. По умолчанию false
. Если задано значение normalizenames=true
, то к именам столбцов, содержащим пробелы или начинающимся с цифр, в начале добавляется символ подчеркивания. Это позволяет обращаться к столбцам посредством точечной нотации или getproperty
, например file.col1
. После точки (.
) должен стоять допустимый идентификатор, поэтому цифры в начале или пробелы запрещены.
skipto
Вы можете указать значение типа Integer
, соответствующее номеру строки, с которой начинаются данные. По умолчанию предполагается, что данные начинаются сразу после строки заголовков. Если задан аргумент header=false
или имена столбцов указаны вручную в виде Vector{String}
или Vector{Symbol}
, предполагается, что данные начинаются с первой строки, то есть skipto=1
.
footerskip
Аргумент типа Integer
, определяющий количество строк в конце файла, которые следует игнорировать. Анализатор начинает обработку файла с конца и движется в обратном направлении, пока не проанализирует footerskip
строк, после чего анализирует весь файл, пока не будет достигнута новая метка конца файла.
transpose
Если передан аргумент transpose=true
, данные считываются как транспонированные, то есть каждая строка анализируется как столбец, а каждый столбец возвращается как строка. Это полезно, если данные очень широкие (много столбцов), но вы хотите обрабатывать их как длинные (много строк). Обратите внимание, что многопоточный анализ данных в режиме транспонирования не поддерживается.
comment
Если значение этого аргумента (типа String
) встречается в начале строки в ходе анализа, строка пропускается. Следует отметить, что если заданы аргументы header
, skipto
или footerskip
, закомментированные строки игнорируются, однако учитываются при определении строки, к которой нужно перейти. Благодаря этому можно, например, визуально установить, что имена столбцов находятся в строке 6, и передать аргумент header=6
, даже если строка 5 закомментирована и будет пропущена.
ignoreemptyrows
Этот аргумент определяет, следует ли при анализе игнорировать «пустые строки», то есть состоящие из одних символов новой строки. По умолчанию они игнорируются. Если задано значение ignoreemptyrows=false
, то всем ячейкам пустой строки присваивается значение missing
. Так же как и закомментированные строки, пустые строки учитываются при задании аргументов header
, skipto
или footerskip
.
select
/ drop
Эти аргументы определяют то, какие именно столбцы во входных данных будут анализироваться и станут доступны после обработки. select
определяет то, какие столбцы будут доступны после анализа, а drop
— какие столбцы следует пропустить. Значением этих аргументов может быть вектор значений типа Integer
, String
или Symbol
, соответствующих номерам или именам включаемых или исключаемых столбцов. Кроме того, можно задать вектор значений типа Bool
, количество которых должно быть равно количеству столбцов во входных данных. Каждый элемент такого вектора определяет, должен ли включаться или исключаться соответствующий столбец. Наконец, эти аргументы можно задавать в виде логических функций, имеющих форму (i, name) -> Bool
. Номер и имя каждого столбца указываются в виде аргументов, а от результата функции зависит то, будет ли включаться или исключаться столбец.
limit
Аргумент типа Integer
, определяющий количество строк, которые следует считать из данных. Может применяться в сочетании с аргументом skipto
для считывания непрерывных фрагментов файла. Обратите внимание, что в многопоточном режиме (когда размер данных представляется достаточно большим) анализатору может быть сложно точно определить необходимое количество строк, поэтому он может возвращать количество строк, не строго равное limit
. Чтобы при работе с большими файлами количество строк строго ограничивалось, также передайте аргумент ntasks=1
для принудительного анализа в однопоточном режиме.
ntasks
Примечание. Неприменимо к CSV.Rows
.
Если входные данные имеют достаточно большой объем, ntasks
определяет количество задач для одновременного анализа данных в многопоточном режиме. По умолчанию используется Threads.nthreads()
, то есть количество потоков, с которым был запущен процесс julia. Оно определяется командой julia -t N
или переменной среды JULIA_NUM_THREADS
. Чтобы отключить многопоточный анализ даже для больших файлов, передайте ntasks=1
. Этот аргумент применим только к CSV.File
, но не к CSV.Rows
. Для CSV.Chunks
он определяет общее количество фрагментарных итераций, на которые будет разбит большой файл для анализа.
rows_to_check
Примечание. Неприменимо к CSV.Rows
.
Если размер входных данных достаточно велик, анализатор попытается разделить их на части, которые будут анализироваться параллельно в многопоточном режиме. Данные разделяются на фрагменты одинакового размера, после чего начальные анализаторы пытаются правильно определить начало первых строк фрагментов. После обнаружения начала первой строки фрагмента каждый анализатор проверяет rows_to_check
строк, чтобы убедиться в наличии требуемого количества столбцов.
source
Примечание. Применимо только к вектору входных данных, передаваемому в CSV.File
.
Symbol
, String
или пара (Pair
) элементов Symbol
или String
для Vector
. В одиночном элементе Symbol
или String
предоставляется имя столбца, который будет добавлен в число анализируемых. Значения столбца будут «именем» источника входных данных (обычно именем файла), из которого было проанализировано значение. Вторым элементом пары (Pair
) должен быть вектор (Vector
) значений, число которых соответствует количеству наборов входных данных. Каждое значение будет использоваться вместо имени набора входных данных для значений этого набора в автоматически добавляемом столбце.
missingstring
Аргумент, определяющий то, как обрабатываются значения missing
при анализе входных данных. Значение по умолчанию — missingstring=""
. Оно означает, что значение missing
присваивается ячейке при наличии двух разделителей подряд, например ,,
. В противном случае в качестве «метки» можно передать одну строку, например missingstring="NA"
, или вектор строк, каждая из которых будет проверяться при анализе, например missingstring=["NA", "NAN", "NULL"]
. Ячейке будет присвоено значение missing
при обнаружении любой из этих строк. Если передать missingstring=nothing
, значения missing
при анализе не будут проверяться.
delim
Аргумент типа Char
или String
, значение которого анализатор распознает во входных данных как разделитель столбцов в каждой строке. Если этот аргумент не задан, анализатор по умолчанию попытается определить наиболее часто встречающийся разделитель в первых десяти строках входных данных. Если сделать это не удастся, разделителем будет считаться одинарная запятая (,
).
ignorerepeated
Аргумент типа Bool
(значение по умолчанию — false
), при значении true
которого анализатор пропускает любое количество идущих подряд разделителей между столбцами. Он часто может быть полезен для корректного анализа входных данных фиксированной ширины, в которых столбцы разделяются одинаковым количеством разделителей, или в которых строки имеют фиксированную ширину, а между столбцами может быть разное количество разделителей в зависимости от длины значений в ячейках.
quoted
Аргумент Bool
, который определяет, будет ли анализатор проверять наличие символов открывающей и закрывающей кавычек в начале и конце ячеек. Значение по умолчанию — true
. Если известно, что в файле нет ячеек со значениями в кавычках, можно упростить анализ, передав quoted=false
, чтобы анализатор не обрабатывал аргументы quotechar
или openquotechar
и closequotechar
особым образом.
quotechar
, openquotechar
, closequotechar
Аргумент Char
в кодировке ASCII (или аргументы, если заданы и openquotechar
, и closequotechar
), который анализатор использует при обработке ячеек со значениями в кавычках. Если строковое значение ячейки содержит значение аргумента delim или символ новой строки, оно должно начинаться с символа quotechar
и заканчиваться им либо начинаться с openquotechar
и заканчиваться на closequotechar
, чтобы анализатор обрабатывал delim
или символ новой строки как часть значения ячейки, а не особый символ. Если символы quotechar
или closequotechar
также должны использоваться в значении ячейки, они должны надлежащим образом экранироваться посредством аргумента escapechar.
escapechar
Аргумент типа Char
в кодировке ASCII, который используется при анализе, когда в заключенном в кавычки строковом значении ячейки встречается символ quotechar
или closequotechar
. Если в заключенном в кавычки значении ячейки встречается символ escapechar
, он пропускается, а следующий символ интерпретируется как обычный, то есть не влияющий на анализ. Обратите внимание, что escapechar
не включается в значение ячейки, а полностью пропускается.
dateformat
Аргумент типа String
или AbstractDict
, определяющий то, как анализатор обнаруживает значения даты и времени во входных данных. Если передана одна строка String
(или DateFormat
), один и тот же формат применяется ко всем столбцам в файле. Для столбцов, для которых не предоставлены иные сведения о типе, анализатор будет использовать переданную строку формата для проверки возможности анализа ячейки. Если анализ возможен, он попытается проанализировать весь столбец как имеющий тип даты и времени (Time
, Date
или DateTime
). Если аргумент dateformat
не задан явным образом, по умолчанию анализатор попытается определить принадлежность значения к любому из типов Time
, Date
или DateTime
согласно стандартным форматам Dates.ISOTimeFormat
, Dates.ISODateFormat
или Dates.ISODateTimeFormat
соответственно. Если для столбца указан тип даты и времени (см. описание аргумента types), то строка формата dateformat
должна соответствовать формату значений в этом столбце. В противном случае будет выдано предупреждение и значение будет заменено на missing
(это поведение также настраивается с помощью аргументов strict и silencewarnings). Если передается словарь AbstractDict
, для разных столбцов можно задать разные строки dateformat
. В предоставленном словаре строки формата даты могут сопоставляться со столбцами либо посредством значений типа Integer
, соответствующих номерам столбцов, либо с помощью значений типа String
, Symbol
или Regex
, соответствующих именам столбцов. Для столбцов, не сопоставленных в словаре аргумента, будут использоваться указанные выше строки формата по умолчанию.
decimal
Аргумент типа Char
в кодировке ASCII, который используется при анализе значений с плавающей запятой и указывает, где начинается дробная часть такого значения. То есть для усеченного значения числа «пи» 3.14
символ '.'
разделяет значения 3
и 14
, а для значения 3,14
(общепринятая европейская форма записи) символ ','
отделяет дробную часть. По умолчанию decimal='.'
.
groupmark
и разделитель групп разрядов
Маркер группы — это символ, который разделяет группы цифр, чтобы человеку было легче прочитать число. Распространенным примером маркеров групп являются разделители групп разрядов. Если аргумент groupmark
указан, его значением должен быть символ Char
в кодировке ASCII, который будет игнорироваться во время анализа, если он находится между двумя цифрами в левой части десятичного числа. Например, маркером группы в целом числе 1,729
является ','
, а маркером группы для номера социального страхования в США 875-39-3196
является -
. По умолчанию используется значение groupmark=nothing
. Оно указывает, что дополнительных символов, разделяющих группы цифр, нет.
truestrings
и falsestrings
В этих аргументах можно передать Vector{String}
, чтобы указать пользовательские значения, которые должны интерпретироваться как значения true
и false
типа Bool
во всех столбцах входных данных. По умолчанию для обнаружения значений true
используются строковые значения ["true", "True", "TRUE", "T", "1"]
, а для обнаружения значений false
— строковые значения ["false", "False", "FALSE", "F", "0"]
. Обратите внимание, что хотя значения "1"
и "0"
могут сопоставляться со значениями true
и false
при анализе, при автоматическом определении типов столбцов они в первую очередь сопоставляются с Int64
, а не с Bool
. Чтобы интерпретировать их как Bool
в столбце, можно вручную задать для этого столбца тип Bool
(см. описание аргумента type).
types
Аргумент, управляющий типами анализируемых столбцов во входных данных. Значением может быть один тип Type
, вектор AbstractVector
типов, AbstractDict
или функция.
-
Если указан один тип, например
types=Float64
, то все столбцы во входных данных будут анализироваться какFloat64
. Если ячейка в столбце не содержит допустимое значениеFloat64
, выдается предупреждение. Однако если передан аргументsilencewarnings=false
, предупреждение не выводится. Если же передан аргументstrict=true
, вместо этого выдается ошибка независимо от значения аргументаsilencewarnings
. -
Если передан вектор
AbstractVector{Type}
, его длина должна быть равна количеству столбцов во входных данных, а каждый элемент указывает тип соответствующего столбца (по порядку). -
Если передан словарь
AbstractDict
, столбец, тип которого определяется, указывается с помощью ключа словаря:Integer
соответствует номеру столбца, аString
илиSymbol
— имени столбца. Для сопоставления с именами столбцов можно также использоватьRegex
. Значения словаря определяют типы столбцов. Тип отсутствующих в словаре столбцов определяется во время анализа автоматически. -
Если передана функция, она должна иметь вид
(i, name) -> Union{T, Nothing}
. Эта функция применяется к каждому обнаруженному столбцу во время начального анализа. Если функция возвращаетnothing
, тип столбца определяется во время анализа автоматически.
По умолчанию types=nothing
, то есть во время анализа типы всех столбцов определяются автоматически. Обратите внимание, что если во входных данных есть значения missing
, передавать types=Union{Float64, Missing}
не требуется. Анализатор обнаруживает значения missing
при их наличии и автоматически продвигает заданные вручную типы столбцов от одиночного (Float64
) до соответствующего типа, включающего missing (Union{Float64, Missing}
). Если не указано иное, стандартные типы определяются автоматически в следующем порядке: Int64
, Float64
, Date
, DateTime
, Time
, Bool
, String
.
Можно указывать и нестандартные типы, например Dec64
из пакета DecFP.jl, но они должны поддерживать функцию Base.tryparse(T, str)
для анализа строкового значения. Это позволяет, например, легко определять пользовательские типы, такие как struct Float64Array; values::Vector{Float64}; end
, если имеется соответствующее определение Base.tryparse
, такое как Base.tryparse(::Type{Float64Array}, str) = Float64Array(map(x -> parse(Float64, x), split(str, ';')))
, где отдельная ячейка во входных данных имеет вид 1.23;4.56;7.89
.
Имейте в виду, что тип stringtype по умолчанию можно переопределить, указав тип столбца вручную, например CSV.File(source; types=Dict(1 => String), stringtype=PosLenString)
, где первый столбец будет анализироваться как String
, а все остальные строковые столбцы будут иметь тип PosLenString
.
typemap
Аргумент типа AbstractDict{Type, Type}
, который позволяет заменять стандартный тип, отличный от String
, на другой при автоматическом определении типа столбца. Как правило, эта возможность применяется для приведения всех числовых столбцов к типу Float64
. Например, typemap=IdDict(Int64 => Float64)
приводит к тому, что все столбцы, определенные как Int64
, будут анализироваться вместо этого как Float64
. Еще один распространенный вариант использования — приведение всех столбцов определенного типа к строкам при анализе. Например, typemap=IdDict(Date => String)
приводит к тому, что все столбцы, определенные как Date
, будут анализироваться вместо этого как String
.
pool
Этот аргумент определяет, будут ли столбцы возвращаться как массивы PooledArray
. Значением может быть Bool
, Float64
, Tuple{Float64, Int}
, вектор, словарь или функция вида (i, name) -> Union{Bool, Real, Tuple{Float64, Int}, Nothing}
. Значение типа Bool
позволяет однозначно определять, будет ли столбец сжиматься. При передаче в аргументе одинарного значения Bool
, например pool=true
, все строковые столбцы сжимаются независимо от мощности множества. Значение типа Float64
должно быть в диапазоне от 0.0
до 1.0
. Оно определяет порог процентной доли уникальных значений в столбце, ниже которого столбец будет сжиматься. Например, если pool=0.1
, все строковые столбцы с долей уникальных значений менее 10 % будут возвращаться как PooledArray
, а остальные строковые столбцы будут обычными строковыми векторами. Если значением pool
является кортеж, например (0.2, 500)
, первый элемент кортежа соответствует одиночному значению Float64
, которое представляет допустимую процентную долю мощности множества. Второй элемент кортежа — это верхний предел количества уникальных значений, при котором разрешено сжатие столбца. Например, pool=(0.2, 500)
означает, что если в строковом столбце не более 500 уникальных значений и количество уникальных значений составляет менее 20 % от общего числа значений, столбец сжимается. В противном случае этого не происходит. Как уже упоминалось, если в аргументе pool
передается одиночное значение Bool
, Real
или Tuple{Float64, Int}
, сжатие возможно только для строковых столбцов. Если передается вектор или словарь, можно управлять сжатием любых столбцов с помощью значений Bool
, Float64
или Tuple{Float64, Int}
. Как и в случае с аргументом types, в векторе, передаваемом в pool
, должен быть элемент для каждого столбца входных данных, в то время как словарь допускает сопоставление с номерами или именами определенных столбцов с помощью значений типа Bool
, Float64
или Tuple{Float64, Int}
. Не указанные в словаре столбцы не сжимаются.
downcast
Аргумент типа Bool
, который определяет, будут ли столбцы типа Integer
«сжиматься» до наименьшего возможного целочисленного типа. Значение по умолчанию — false
. Применяется только к столбцам, тип которых определяется автоматически, то есть если тип столбца указан вручную как Int64
, столбец не сжимается. Этот аргумент полезен для уменьшения общего объема памяти, занимаемой проанализированными данными. Однако при обработке результатов следует соблюдать осторожность, так как в Julia по умолчанию происходит целочисленное переполнение, которое тем вероятнее, чем меньше целочисленный тип.
stringtype
Аргумент, точно определяющий тип строковых столбцов. Поддерживаемые значения — InlineString
(по умолчанию), PosLenString
и String
. Общие строковые типы, как правило, наиболее понятны большинству пользователей. Однако в некоторых ситуациях может быть выгоднее использовать более конкретные типы. Вот краткий обзор возможных вариантов.
-
InlineString
: набор примитивных типов фиксированной ширины с размещением в стеке. Позволяет снизить нагрузку на память при сборке мусора, поскольку эти типы не ссылочные и не размещаются в куче. В случае с очень большими файлами, содержащими строковые столбцы со сравнительно небольшим расхождением по длине, эти типы позволяют существенно повысить эффективность сборки мусора по сравнению сString
. Если строки значительно различаются по длине, много пространства может расходоваться впустую, так как весь столбец продвигается до наименьшего типа InlineString, в который помещается самое длинное строковое значение. В случае с небольшими строками много пространства может расходоваться впустую, если они продвигаются до большого типа фиксированной ширины. -
PosLenString
: столбцы возвращаются в виде вектораPosLenStringVector
(илиChainedVector{PosLenStringVector}
в многопоточном режиме), который содержит ссылку на исходные входные данные и выступает в качестве одного большого представления исходных данных с указанием места начала и окончания каждой ячейки. Для строковых столбцов может обеспечивать максимальную экономию памяти.PosLenStringVector
, однако, не поддерживает традиционные изменяемые операции, например с обычными объектамиVector
, такими какpush!
,append!
илиdeleteat!
. -
String
: каждая строка должна размещаться в куче, что может приводить к более высокой нагрузке при сборке мусора в случае с большими файлами. Однако столбцы возвращаются как обычные векторыVector{String}
(илиChainedVector{Vector{String}}
), с которыми можно работать обычным образом, в том числе выполнять операции, изменяющие данные.
strict
, silencewarnings
, maxwarnings
Эти аргументы управляют выдачей ошибок при обнаружении недопустимых значений в ходе анализа. Они применимы, только если пользователь задал типы вручную с помощью аргумента types. Если тип столбца указан вручную, но обнаружено недопустимое значение, по умолчанию ячейке присваивается значение missing
и выдается предупреждение (то есть silencewarnings=false
и strict=false
), но выводится всего не более 100 предупреждений (то есть maxwarnings=100
). Если strict=true
, недопустимые значения приводят к выдаче ошибки вместо предупреждения.
Справка по API
#
CSV.read
— Function
CSV.read(source, sink::T; kwargs...) => T
Читает и анализирует файл или файлы с разделителями, материализующиеся напрямую с помощью функции sink
. Позволяет избежать избыточного копирования столбцов для некоторых приемников, например DataFrame
.
Пример
julia> using CSV, DataFrames julia> path = tempname(); julia> write(path, "a,b,c\n1,2,3"); julia> CSV.read(path, DataFrame) 1×3 DataFrame Row │ a b c │ Int64 Int64 Int64 ─────┼───────────────────── 1 │ 1 2 3 julia> CSV.read(path, DataFrame; header=false) 2×3 DataFrame Row │ Column1 Column2 Column3 │ String1 String1 String1 ─────┼─────────────────────────── 1 │ a b c 2 │ 1 2 3
Аргументы
Параметры структуры файла
-
header=1
: указывает способ определения имен столбцов. Если задан какInteger
, указывает строку для анализа имен столбцов. Если задан какAbstractVector{<:Integer}
, указывает набор строк для конкатенации в качестве имен столбцов.Vector{Symbol}
илиVector{String}
явным образом задают имена столбцов (должны соответствовать количеству столбцов в наборе данных). Если в наборе данных нет имен столбцов, либо задайте их в видеVector
, либо задайтеheader=0
илиheader=false
, и имена столбцов будут сгенерированы автоматически (Column1
,Column2
и т. д.). Обратите внимание, что если указан заголовок номера строки иcomment
илиignoreemptyrows
, строка заголовка будет первой незакомментированной/непустой строкой после номера строки, то есть если указанный номер строки является закомментированной строкой, то строка заголовка фактически будет следующей незакомментированной строкой. -
normalizenames::Bool=false
: следует ли «нормализовать» имена столбцов в допустимые символы идентификатора Julia. Полезно при использовании синтаксисаtbl.col1
getproperty
или при итерации строк и обращении к значениям столбцов строки черезgetproperty
(например,row.col1
) -
skipto::Integer
: указывает строку, с которой начинаются данные в CSV-файле. По умолчанию используется следующая строка после строки (строк)header
. Еслиheader=0
, предполагается, что началом данных является первая строка. Указание аргументаskipto
не влияет на аргументheader
. Обратите внимание, что если указаны номера строкskipto
иcomment
илиignoreemptyrows
, строка данных будет первой незакомментированной/непустой строкой после номера строки, то есть если указанный номер строки является закомментированной строкой, то строка данных фактически будет следующей незакомментированной строкой. -
footerskip::Integer
: количество строк в конце файла, которые не нужно анализировать. Обратите внимание, что закомментированные строки (см. именованный аргументcomment
) не учитываются в количестве строк, заданном дляfooterskip
, — они полностью игнорируются анализатором. -
transpose::Bool
: чтение CSV-файла «с транспонированием», т. е. каждый столбец анализируется как строка. -
comment::String
: строка, при анализе которой строки, начинающиеся с нее, будут пропущены. Обратите внимание, что если указан заголовок номера строки илиskipto
иcomment
, строка заголовка или данных будет первой незакомментированной/непустой строкой после номера строки, то есть если указанный номер строки является закомментированной строкой, то строка заголовка или данных фактически будет следующей незакомментированной строкой. -
ignoreemptyrows::Bool=true
: следует ли игнорировать пустые строки в файле (если задано значениеfalse
, каждому столбцу будет присвоено значениеmissing
для этой пустой строки). -
select
:AbstractVector
дляInteger
,Symbol
,String
илиBool
либо выборочная функция вида(i, name) -> keep::Bool
. В результирующем файлеCSV.File
будут проанализированы и доступны только столбцы в коллекции или столбцы, для которых выборочная функция возвращаетtrue
. Недопустимые значения вselect
игнорируются. -
drop
: обратный эквивалентselect
.AbstractVector
дляInteger
,Symbol
,String
илиBool
либо функция отбрасывания вида(i, name) -> drop::Bool
. В результирующем файлеCSV.File
будут игнорироваться столбцы в коллекции или столбцы, для которых функция отбрасывания возвращаетtrue
. Недопустимые значения вdrop
игнорируются. -
limit
:Integer
для указания ограниченного числа строк для анализа в CSV-файле. Используется в сочетании сskipto
для чтения конкретного непрерывного фрагмента в файле. Обратите внимание, что когда в больших файлах для анализа применяется несколько потоков, аргументlimit
может не выводить точное количество анализируемых строк. Если необходимо, для определения точного ограничения используйтеthreaded=false
. -
buffer_in_memory
: логическое значениеBool
, по умолчаниюfalse
, которое определяет, будет лиCmd
,IO
или источник в формате GZIP считываться/распаковываться в памяти, а не во временном файле. -
ntasks::Integer=Threads.nthreads()
[неприменимо кCSV.Rows
]: для файлов с многопоточным анализом управляет количеством задач, порождаемых для чтения файла в параллельных фрагментах. Значением по умолчанию является количество потоков, с которыми была запущена среда Julia (т. е. переменная средыJULIA_NUM_THREADS
илиjulia -t N
). Установкаntasks=1
позволит избежать вызововThreads.@spawn
, и файлы просто будут последовательно считываться в основном потоке. По умолчанию для небольших файлов (< 5_000 ячеек) также будет использоваться один поток. -
rows_to_check::Integer=30
[неприменимо кCSV.Rows
]: файл с многопоточным анализом будет разбит наntasks
равных фрагментов.rows_to_check
управляет количеством проверяемых строк для корректного обнаружения допустимых строк при анализе. Для некоторых файлов с очень большими текстовыми полями, заключенными в кавычки, может потребоваться задать более высокое значениеlines_to_check
(10, 30 и т. д.) для корректного обнаружения этих строк при анализе. -
source
[применимо только для вектора входных данных дляCSV.File
]:Symbol
,String
либоPair
дляSymbol
илиString
дляVector
. В одиночном элементеSymbol
илиString
указывается имя столбца, который будет добавлен в число анализируемых. Значения столбца будут «именем» источника входных данных (обычно именем файла), из которого было проанализировано значение. Вторым элементом пары (Pair
) должен быть вектор (Vector
) значений, число которых соответствует количеству наборов входных данных. Каждое значение будет использоваться вместо имени набора входных данных для значений этого набора в автоматически добавляемом столбце.
Параметры анализа
-
missingstring
: либоnothing
,String
, либоVector{String}
для использования в качестве контрольных значений, которые будут проанализированы какmissing
. Если передаетсяnothing
, контрольные или отсутствующие значения анализироваться не будут. Значением по умолчанию являетсяmissingstring=""
, что означает, что отсутствующим (missing
) считается только пустое поле (два последовательных разделителя). -
delim=','
:Char
илиString
, указывающие на способ разделения столбцов в файле. Если аргумент не задан, анализатор по умолчанию попытается определить наиболее часто встречающийся разделитель в первых десяти строках входных данных. -
ignorerepeated::Bool=false
: следует ли при анализе игнорировать повторяющиеся (последовательные/непоследовательные) разделители. Полезно для файлов фиксированной ширины с заполнением разделителями между ячейками. -
quoted::Bool=true
: будет ли анализатор проверять наличие символовquotechar
в начале и конце ячеек. -
quotechar='"'
,openquotechar
,closequotechar
: символChar
(или другие начальный и конечный символы), указывающий на поле, заключенное в кавычки, которое может содержать текстовые разделители или символы новой строки. -
escapechar='"'
:Char
используется для экранирования символов кавычек в поле, заключенном в кавычки. -
dateformat::Union{String, Dates.DateFormat, Nothing, AbstractDict}
: строка формата даты для указания способа форматирования столбцов Date/DateTime для всего файла. Если задана какAbstractDict
, строки формата даты для указания способа форматирования столбцов Date/DateTime, соответствующих ключам. Dict может сопоставлять индекс столбцаInt
, или имяSymbol
, илиString
со строкой формата для этого столбца. -
decimal='.'
:Char
, указывающий способ разделения десятичных частей в числах с плавающей запятой, т. е.3.14
использует'.'
или3,14
использует запятую','
. -
groupmark=nothing
: дополнительно указывает однобайтовый символ, обозначающий знак группировки чисел, что позволяет анализировать числа, имеющие, например, разделители тысяч (1,000.00
). -
truestrings
,falsestrings
:Vector{String}
, указывающие на способ представления значенийtrue
илиfalse
. По умолчанию"true", "True", "TRUE", "T", "1"
используются для определенияtrue
, а"false", "False", "FALSE", "F", "0"
— для определенияfalse
. Обратите внимание, что столбцы, имеющие только значения1
и0
, по умолчанию будут иметь тип столбцаInt64
, если только явно не будет запрошен типBool
с помощью именованного аргументаtypes
. -
stripwhitespace=false
: если задано значение true, из строковых значений, включая имена столбцов, удаляются начальные и конечные символы пробела.
Параметры типов столбцов
-
types
: один из типовType
,AbstractVector
илиAbstractDict
или функция вида(i, name) -> Union{T, Nothing}
, которая будет использоваться для типов столбцов. Если указан один тип (Type
), все столбцы будут проанализированы с этим единственным типом.AbstractDict
может сопоставлять индекс столбцаInteger
, или имяSymbol
илиString
с типом столбца, т. е.Dict(1=>Float64)
задаст первый столбец какFloat64
,Dict(:column1=>Float64)
задаст столбец с именемcolumn1
какFloat64
иDict("column1"=>Float64)
задастcolumn1
какFloat64
. Если указан вектор (Vector
), он должен соответствовать количеству столбцов, указанных или обнаруженных вheader
. Если указана функция, она принимает в качестве аргументов индекс и имя столбца и должна возвращать желаемый тип столбца, либоnothing
, указывающий на необходимость определения типа столбца при анализе. -
typemap::IdDict{Type, Type}
: сопоставление типа, который должен быть заменен в любом случае другим типом, т. е.Dict(Float64=>String)
изменит каждый обнаруженный столбец типаFloat64
на анализируемый типаString
. С другим типом могут быть сопоставлены только стандартные типы, т. е.Int64
,Float64
,Date
,DateTime
,Time
иBool
. Обнаруженный столбец одного из этих типов будет сопоставлен с указанным типом. -
pool::Union{Bool, Real, AbstractVector, AbstractDict, Function, Tuple{Float64, Int}}=(0.2, 500)
[не поддерживается вCSV.Rows
]: определяет, будут ли столбцы созданы какPooledArray
. Если задано значениеtrue
, все столбцы, обнаруживаемые какString
, будут объединены. Или доля уникальных значений, ниже которой столбцыString
должны быть объединены (то есть если количество уникальных строк в столбце меньше 25 %,pool=0.25
, они будут объединены). Если указан в видеTuple{Float64, Int}
как(0.2, 500)
, он представляет порог кардинальности в процентах в виде первого элемента кортежа (0.2
) и верхний предел для числа уникальных значений (500
), ниже которого столбец будет добавлен в пул. Это значение по умолчанию (pool=(0.2, 500)
). Если заданAbstractVector
, каждый элемент должен иметь типBool
,Real
илиTuple{Float64, Int}
, а количество элементов — соответствовать количеству столбцов в наборе данных. Если заданAbstractDict
, значениеBool
,Real
илиTuple{Float64, Int}
может быть предоставлено для отдельных столбцов, где ключ словаря задан как индекс столбцаInteger
, или имя столбца какSymbol
илиString
. Если указана функция, она должна принимать в качестве двух аргументов индекс и имя столбца и возвращать для каждого столбца значениеBool
,Real
,Tuple{Float64, Int}
илиnothing
. -
downcast::Bool=false
: определяет, будет ли для обнаруженных столбцов типаInt64
выполняться нисходящее преобразование до наименьшего возможного целочисленного типа, напримерInt8
,Int16
,Int32
и т. д. -
stringtype=InlineStrings.InlineString
: определяет способ возврата обнаруженных строковых столбцов. Значение по умолчанию —InlineString
, которое хранит строковые данные в примитивном типе фиксированного размера, что позволяет избежать чрезмерного использования динамической памяти. Если столбец имеет значения длиннее 32 байт, по умолчанию используетсяString
. Если передаетсяString
, все строковые столбцы будут просто обычными значениямиString
. Если передаетсяPosLenString
, строковые столбцы будут возвращены в виде вектораPosLenStringVector
, который представляет собой специальный «отложенный» векторAbstractVector
, выполняющий роль представления для исходных данных файла. Результатом может быть максимально эффективное время анализа, но следует учесть, что представлениеPosLenStringVector
делает его доступным только для чтения, поэтому такие операции, какpush!
,append!
илиsetindex!
, не поддерживаются. Он также содержит ссылку на весь источник входного набора данных, поэтому, например, попытка изменить или удалить базовый файл может завершиться сбоем. -
strict::Bool=false
: должны ли недопустимые значения выдавать ошибку анализа или заменяться наmissing
. -
silencewarnings::Bool=false
: если задано значениеstrict=false
, следует ли подавлять предупреждения о недопустимых значениях. -
maxwarnings::Int=100
: если в процессе анализа будет выведено болееmaxwarnings
предупреждений, дальнейшие предупреждения будут подавляться по умолчанию. При многопоточном анализе каждая задача синтаксического анализа будет выводить не болееmaxwarnings
. -
debug::Bool=false
: передачаtrue
приведет к выводу большого количества информационных сообщений во время анализа набора данных. Может быть полезно для сообщения о проблемах или выяснения того, что происходит внутри набора данных во время его анализа. -
validate::Bool=true
: нужно ли проверять, что столбцы, указанные в ключевых словахtypes
,dateformat
иpool
, действительно найдены в данных. Если задано значениеfalse
, проверка не выполняется, т. е. ошибка не возникнет, еслиtypes
/dateformat
/pool
задают параметры для столбцов, которые в действительности не встречаются в данных.
Параметры итерации
-
reusebuffer=false
[поддерживается только вCSV.Rows
]: следует ли при итерации выделять один буфер для строк и повторно использовать его в каждой итерации. Применяется только в том случае, если каждая строка будет итерироваться один раз и не будет использоваться повторно (например, при выполненииcollect(CSV.Rows(file))
применять этот параметр небезопасно, поскольку допустимой является только текущая итерируемая строка).
#
CSV.File
— Type
CSV.File(input; kwargs...) => CSV.File
Считывает входной CSV-файл в формате UTF-8 и возвращает объект CSV.File
, который представляет собой упрощенную таблицу или фрейм данных, позволяя осуществлять точечный доступ к столбцам и итерацию строк. Удовлетворяет интерфейсу Tables.jl, поэтому может быть передан любому допустимому приемнику, однако, чтобы избежать лишних копий данных, используйте вместо него CSV.read(input, sink; kwargs...)
, если промежуточный объект CSV.File
не нужен.
Аргумент input
может быть одним из указанных ниже:
-
имя файла, заданное в виде строки или типа FilePaths.jl
-
буфер байт
Vector{UInt8}
илиSubArray{UInt8, 1, Vector{UInt8}}
-
объект
CodeUnits
, заключающийString
в оболочку, напримерcodeunits(str)
-
строка в формате CSV также может быть передана как
IOBuffer(str)
-
Cmd
или другойIO
-
файл в формате GZIP (или данные в формате GZIP в любом из вышеперечисленных файлов), который будет автоматически распакован для анализа
-
вектор (
Vector
) любого из вышеперечисленных элементов, который будет анализировать и вертикально конкатенировать каждый источник, возвращая один длинныйCSV.File
Для чтения CSV-файла из URL-адреса используйте пакет Downloads.jl из библиотеки stdlib или HTTP.jl, где результирующий скачанный временный файл или текст HTTP.Response
может быть передан следующим образом:
using Downloads, CSV
f = CSV.File(Downloads.download(url))
# или
using HTTP, CSV
f = CSV.File(HTTP.get(url).body)
Открывает файл или файлы и использует переданные аргументы для определения количества столбцов и типов столбцов, если типы столбцов не заданы вручную с помощью именованного аргумента types
. Обратите внимание, что передача типов столбцов вручную может несколько увеличить производительность для каждого предоставленного типа столбцов (типы столбцов могут быть заданы в виде Vector
для всех столбцов, либо указаны для каждого столбца с помощью имени или индекса в Dict
).
Если указан вектор (Vector
) входных данных, для обеспечения вертикальной конкатенации должны совпадать имена столбцов и типы каждого отдельного файла или входных данных. Для анализа входных данных будут использоваться отдельные потоки, каждый из которых будет анализировать свои входные данные. Затем результаты всех потоков конкатенируются по вертикали с помощью ChainedVector
для отложенной конкатенации столбцов каждого потока.
Для кодировок текста, отличных от UTF-8, загрузите пакет StringEncodings.jl и вызовите, например, CSV.File(open(read, input, enc"ISO-8859-1"))
.
Возвращаемый объект CSV.File
поддерживает интерфейс Tables.jl и может итерировать CSV.Row
. CSV.Row
поддерживает propertynames
и getproperty
для доступа к значениям отдельных строк. CSV.File
также поддерживает доступ к целым столбцам, например DataFrame
, через прямой доступ к свойствам объекта файла, например f = CSV.File(file); f.col1
. Или через доступ getindex с именами столбцов, например f[:col1]
или f["col1"]
. Возвращаемые столбцы являются подтипами AbstractArray
, в том числе: SentinelVector
(для целых чисел), обычные Vector
, PooledVector
для объединенных столбцов, MissingVector
для столбцов всех значений missing
, PosLenStringVector
при передаче stringtype=PosLenString
, и ChainedVector
объединит один из предыдущих типов массивов в цепочку для входных данных, для анализа которых используется несколько потоков (каждый поток анализирует одну цепочку входных данных). Обратите внимание, что повторяющиеся имена столбцов будут обнаружены и скорректированы для обеспечения уникальности (повторяющееся имя столбца a
получит значение a_1
). Например, можно выполнить итерацию CSV-файла с именами столбцов a
, b
и c
, выполнив следующее.
for row in CSV.File(file)
println("a=$(row.a), b=$(row.b), c=$(row.c)")
end
Благодаря поддержке интерфейса Tables.jl CSV.File
также может быть входными данными для любой функции приемника таблиц. Например:
# материализация CSV-файла в виде DataFrame, путем копирования столбцов из CSV.File
df = CSV.File(file) |> DataFrame
# чтобы не делать копию проанализированных столбцов, использование CSV.read
df = CSV.read(file, DataFrame)
# загрузка CSV-файла непосредственно в таблицу базы данных sqlite
db = SQLite.DB()
tbl = CSV.File(file) |> SQLite.load!(db, "sqlite_table")
Аргументы
Параметры структуры файла
-
header=1
: указывает способ определения имен столбцов. Если задан какInteger
, указывает строку для анализа имен столбцов. Если задан какAbstractVector{<:Integer}
, указывает набор строк для конкатенации в качестве имен столбцов.Vector{Symbol}
илиVector{String}
явным образом задают имена столбцов (должны соответствовать количеству столбцов в наборе данных). Если в наборе данных нет имен столбцов, либо задайте их в видеVector
, либо задайтеheader=0
илиheader=false
, и имена столбцов будут сгенерированы автоматически (Column1
,Column2
и т. д.). Обратите внимание, что если указан заголовок номера строки иcomment
илиignoreemptyrows
, строка заголовка будет первой незакомментированной/непустой строкой после номера строки, то есть если указанный номер строки является закомментированной строкой, то строка заголовка фактически будет следующей незакомментированной строкой. -
normalizenames::Bool=false
: следует ли «нормализовать» имена столбцов в допустимые символы идентификатора Julia. Полезно при использовании синтаксисаtbl.col1
getproperty
или при итерации строк и обращении к значениям столбцов строки черезgetproperty
(например,row.col1
) -
skipto::Integer
: указывает строку, с которой начинаются данные в CSV-файле. По умолчанию используется следующая строка после строки (строк)header
. Еслиheader=0
, предполагается, что началом данных является первая строка. Указание аргументаskipto
не влияет на аргументheader
. Обратите внимание, что если указаны номера строкskipto
иcomment
илиignoreemptyrows
, строка данных будет первой незакомментированной/непустой строкой после номера строки, то есть если указанный номер строки является закомментированной строкой, то строка данных фактически будет следующей незакомментированной строкой. -
footerskip::Integer
: количество строк в конце файла, которые не нужно анализировать. Обратите внимание, что закомментированные строки (см. именованный аргументcomment
) не учитываются в количестве строк, заданном дляfooterskip
, — они полностью игнорируются анализатором. -
transpose::Bool
: чтение CSV-файла «с транспонированием», т. е. каждый столбец анализируется как строка. -
comment::String
: строка, при анализе которой строки, начинающиеся с нее, будут пропущены. Обратите внимание, что если указан заголовок номера строки илиskipto
иcomment
, строка заголовка или данных будет первой незакомментированной/непустой строкой после номера строки, то есть если указанный номер строки является закомментированной строкой, то строка заголовка или данных фактически будет следующей незакомментированной строкой. -
ignoreemptyrows::Bool=true
: следует ли игнорировать пустые строки в файле (если задано значениеfalse
, каждому столбцу будет присвоено значениеmissing
для этой пустой строки). -
select
:AbstractVector
дляInteger
,Symbol
,String
илиBool
либо выборочная функция вида(i, name) -> keep::Bool
. В результирующем файлеCSV.File
будут проанализированы и доступны только столбцы в коллекции или столбцы, для которых выборочная функция возвращаетtrue
. Недопустимые значения вselect
игнорируются. -
drop
: обратный эквивалентselect
.AbstractVector
дляInteger
,Symbol
,String
илиBool
либо функция отбрасывания вида(i, name) -> drop::Bool
. В результирующем файлеCSV.File
будут игнорироваться столбцы в коллекции или столбцы, для которых функция отбрасывания возвращаетtrue
. Недопустимые значения вdrop
игнорируются. -
limit
:Integer
для указания ограниченного числа строк для анализа в CSV-файле. Используется в сочетании сskipto
для чтения конкретного непрерывного фрагмента в файле. Обратите внимание, что когда в больших файлах для анализа применяется несколько потоков, аргументlimit
может не выводить точное количество анализируемых строк. Если необходимо, для определения точного ограничения используйтеthreaded=false
. -
buffer_in_memory
: логическое значениеBool
, по умолчаниюfalse
, которое определяет, будет лиCmd
,IO
или источник в формате GZIP считываться/распаковываться в памяти, а не во временном файле. -
ntasks::Integer=Threads.nthreads()
[неприменимо кCSV.Rows
]: для файлов с многопоточным анализом управляет количеством задач, порождаемых для чтения файла в параллельных фрагментах. Значением по умолчанию является количество потоков, с которыми была запущена среда Julia (т. е. переменная средыJULIA_NUM_THREADS
илиjulia -t N
). Установкаntasks=1
позволит избежать вызововThreads.@spawn
, и файлы просто будут последовательно считываться в основном потоке. По умолчанию для небольших файлов (< 5_000 ячеек) также будет использоваться один поток. -
rows_to_check::Integer=30
[неприменимо кCSV.Rows
]: файл с многопоточным анализом будет разбит наntasks
равных фрагментов.rows_to_check
управляет количеством проверяемых строк для корректного обнаружения допустимых строк при анализе. Для некоторых файлов с очень большими текстовыми полями, заключенными в кавычки, может потребоваться задать более высокое значениеlines_to_check
(10, 30 и т. д.) для корректного обнаружения этих строк при анализе. -
source
[применимо только для вектора входных данных дляCSV.File
]:Symbol
,String
либоPair
дляSymbol
илиString
дляVector
. В одиночном элементеSymbol
илиString
указывается имя столбца, который будет добавлен в число анализируемых. Значения столбца будут «именем» источника входных данных (обычно именем файла), из которого было проанализировано значение. Вторым элементом пары (Pair
) должен быть вектор (Vector
) значений, число которых соответствует количеству наборов входных данных. Каждое значение будет использоваться вместо имени набора входных данных для значений этого набора в автоматически добавляемом столбце.
Параметры анализа
-
missingstring
: либоnothing
,String
, либоVector{String}
для использования в качестве контрольных значений, которые будут проанализированы какmissing
. Если передаетсяnothing
, контрольные или отсутствующие значения анализироваться не будут. Значением по умолчанию являетсяmissingstring=""
, что означает, что отсутствующим (missing
) считается только пустое поле (два последовательных разделителя). -
delim=','
:Char
илиString
, указывающие на способ разделения столбцов в файле. Если аргумент не задан, анализатор по умолчанию попытается определить наиболее часто встречающийся разделитель в первых десяти строках входных данных. -
ignorerepeated::Bool=false
: следует ли при анализе игнорировать повторяющиеся (последовательные/непоследовательные) разделители. Полезно для файлов фиксированной ширины с заполнением разделителями между ячейками. -
quoted::Bool=true
: будет ли анализатор проверять наличие символовquotechar
в начале и конце ячеек. -
quotechar='"'
,openquotechar
,closequotechar
: символChar
(или другие начальный и конечный символы), указывающий на поле, заключенное в кавычки, которое может содержать текстовые разделители или символы новой строки. -
escapechar='"'
:Char
используется для экранирования символов кавычек в поле, заключенном в кавычки. -
dateformat::Union{String, Dates.DateFormat, Nothing, AbstractDict}
: строка формата даты для указания способа форматирования столбцов Date/DateTime для всего файла. Если задана какAbstractDict
, строки формата даты для указания способа форматирования столбцов Date/DateTime, соответствующих ключам. Dict может сопоставлять индекс столбцаInt
, или имяSymbol
, илиString
со строкой формата для этого столбца. -
decimal='.'
:Char
, указывающий способ разделения десятичных частей в числах с плавающей запятой, т. е.3.14
использует'.'
или3,14
использует запятую','
. -
groupmark=nothing
: дополнительно указывает однобайтовый символ, обозначающий знак группировки чисел, что позволяет анализировать числа, имеющие, например, разделители тысяч (1,000.00
). -
truestrings
,falsestrings
:Vector{String}
, указывающие на способ представления значенийtrue
илиfalse
. По умолчанию"true", "True", "TRUE", "T", "1"
используются для определенияtrue
, а"false", "False", "FALSE", "F", "0"
— для определенияfalse
. Обратите внимание, что столбцы, имеющие только значения1
и0
, по умолчанию будут иметь тип столбцаInt64
, если только явно не будет запрошен типBool
с помощью именованного аргументаtypes
. -
stripwhitespace=false
: если задано значение true, из строковых значений, включая имена столбцов, удаляются начальные и конечные символы пробела.
Параметры типов столбцов
-
types
: один из типовType
,AbstractVector
илиAbstractDict
или функция вида(i, name) -> Union{T, Nothing}
, которая будет использоваться для типов столбцов. Если указан один тип (Type
), все столбцы будут проанализированы с этим единственным типом.AbstractDict
может сопоставлять индекс столбцаInteger
либо имяSymbol
илиString
с типом столбца, т. е.Dict(1=>Float64)
задаст первый столбец какFloat64
,Dict(:column1=>Float64)
задаст столбец с именемcolumn1
какFloat64
иDict("column1"=>Float64)
задастcolumn1
какFloat64
. Если указан вектор (Vector
), он должен соответствовать количеству столбцов, указанных или обнаруженных вheader
. Если указана функция, она принимает в качестве аргументов индекс и имя столбца и должна возвращать желаемый тип столбца, либоnothing
, указывающий на необходимость определения типа столбца при анализе. -
typemap::IdDict{Type, Type}
: сопоставление типа, который должен быть заменен в любом случае другим типом, т. е.Dict(Float64=>String)
изменит каждый обнаруженный столбец типаFloat64
на анализируемый типаString
. С другим типом могут быть сопоставлены только стандартные типы, т. е.Int64
,Float64
,Date
,DateTime
,Time
иBool
. Обнаруженный столбец одного из этих типов будет сопоставлен с указанным типом. -
pool::Union{Bool, Real, AbstractVector, AbstractDict, Function, Tuple{Float64, Int}}=(0.2, 500)
[не поддерживается вCSV.Rows
]: определяет, будут ли столбцы созданы какPooledArray
. Если задано значениеtrue
, все столбцы, обнаруживаемые какString
, будут объединены. Или доля уникальных значений, ниже которой столбцыString
должны быть объединены (то есть если количество уникальных строк в столбце меньше 25 %,pool=0.25
, они будут объединены). Если указан в видеTuple{Float64, Int}
как(0.2, 500)
, он представляет порог кардинальности в процентах в виде первого элемента кортежа (0.2
) и верхний предел для числа уникальных значений (500
), ниже которого столбец будет добавлен в пул. Это значение по умолчанию (pool=(0.2, 500)
). Если заданAbstractVector
, каждый элемент должен иметь типBool
,Real
илиTuple{Float64, Int}
, а количество элементов — соответствовать количеству столбцов в наборе данных. Если заданAbstractDict
, значениеBool
,Real
илиTuple{Float64, Int}
может быть предоставлено для отдельных столбцов, где ключ словаря задан как индекс столбцаInteger
, или имя столбца какSymbol
илиString
. Если указана функция, она должна принимать в качестве двух аргументов индекс и имя столбца и возвращать для каждого столбца значениеBool
,Real
,Tuple{Float64, Int}
илиnothing
. -
downcast::Bool=false
: определяет, будет ли для обнаруженных столбцов типаInt64
выполняться нисходящее преобразование до наименьшего возможного целочисленного типа, напримерInt8
,Int16
,Int32
и т. д. -
stringtype=InlineStrings.InlineString
: определяет способ возврата обнаруженных строковых столбцов. Значение по умолчанию —InlineString
, которое хранит строковые данные в примитивном типе фиксированного размера, что позволяет избежать чрезмерного использования динамической памяти. Если столбец имеет значения длиннее 32 байт, по умолчанию используетсяString
. Если передаетсяString
, все строковые столбцы будут просто обычными значениямиString
. Если передаетсяPosLenString
, строковые столбцы будут возвращены в виде вектораPosLenStringVector
, который представляет собой специальный «отложенный» векторAbstractVector
, выполняющий роль представления для исходных данных файла. Результатом может быть максимально эффективное время анализа, но следует учесть, что представлениеPosLenStringVector
делает его доступным только для чтения, поэтому такие операции, какpush!
,append!
илиsetindex!
, не поддерживаются. Он также содержит ссылку на весь источник входного набора данных, поэтому, например, попытка изменить или удалить базовый файл может завершиться сбоем. -
strict::Bool=false
: должны ли недопустимые значения выдавать ошибку анализа или заменяться наmissing
. -
silencewarnings::Bool=false
: если задано значениеstrict=false
, следует ли подавлять предупреждения о недопустимых значениях. -
maxwarnings::Int=100
: если в процессе анализа будет выведено болееmaxwarnings
предупреждений, дальнейшие предупреждения будут подавляться по умолчанию. При многопоточном анализе каждая задача синтаксического анализа будет выводить не болееmaxwarnings
. -
debug::Bool=false
: передачаtrue
приведет к выводу большого количества информационных сообщений во время анализа набора данных. Может быть полезно для сообщения о проблемах или выяснения того, что происходит внутри набора данных во время его анализа. -
validate::Bool=true
: нужно ли проверять, что столбцы, указанные в ключевых словахtypes
,dateformat
иpool
, действительно найдены в данных. Если задано значениеfalse
, проверка не выполняется, т. е. ошибка не возникнет, еслиtypes
/dateformat
/pool
задают параметры для столбцов, которые в действительности не встречаются в данных.
Параметры итерации
-
reusebuffer=false
[поддерживается только вCSV.Rows
]: следует ли при итерации выделять один буфер для строк и повторно использовать его в каждой итерации. Применяется только в том случае, если каждая строка будет итерироваться один раз и не будет использоваться повторно (например, при выполненииcollect(CSV.Rows(file))
применять этот параметр небезопасно, поскольку допустимой является только текущая итерируемая строка).
#
CSV.Chunks
— Type
CSV.Chunks(source; ntasks::Integer=Threads.nthreads(), kwargs...) => CSV.Chunks
Возвращает итератор фрагмента файла. Принимает все те же входные данные и именованные аргументы, что и CSV.File
. Объяснение каждого именованного аргумента см. в соответствующей документации.
Именованный аргумент ntasks
указывает, на сколько фрагментов должен быть разбит файл. По умолчанию это количество потоков, доступных Julia (т. е. переменной среды JULIA_NUM_THREADS
), или восемь, если Julia работает в однопоточном режиме.
В ходе каждой итерации CSV.Chunks
создается следующий фрагмент файла в виде CSV.File
. Хотя начальное определение метаданных файла выполняется только один раз (для определения количества столбцов, имен столбцов и т. д.), в каждой итерации осуществляется вывод независимых типов для столбцов. Это важно, так как при появлении в файле новых значений разные фрагменты могут иметь тип столбца, отличный от типов предыдущих фрагментов. Обратите внимание, что, как и в случае с CSV.File
, типы можно передавать вручную с помощью именованных аргументов type
или types
.
Эта функциональность является новой и поэтому считается экспериментальной. При возникновении проблем или ошибок создайте проблему на сайте GitHub.
Аргументы
Параметры структуры файла
-
header=1
: указывает способ определения имен столбцов. Если задан какInteger
, указывает строку для анализа имен столбцов. Если задан какAbstractVector{<:Integer}
, указывает набор строк для конкатенации в качестве имен столбцов.Vector{Symbol}
илиVector{String}
явным образом задают имена столбцов (должны соответствовать количеству столбцов в наборе данных). Если в наборе данных нет имен столбцов, либо задайте их в видеVector
, либо задайтеheader=0
илиheader=false
, и имена столбцов будут сгенерированы автоматически (Column1
,Column2
и т. д.). Обратите внимание, что если указан заголовок номера строки иcomment
илиignoreemptyrows
, строка заголовка будет первой незакомментированной/непустой строкой после номера строки, то есть если указанный номер строки является закомментированной строкой, то строка заголовка фактически будет следующей незакомментированной строкой. -
normalizenames::Bool=false
: следует ли «нормализовать» имена столбцов в допустимые символы идентификатора Julia. Полезно при использовании синтаксисаtbl.col1
getproperty
или при итерации строк и обращении к значениям столбцов строки черезgetproperty
(например,row.col1
) -
skipto::Integer
: указывает строку, с которой начинаются данные в CSV-файле. По умолчанию используется следующая строка после строки (строк)header
. Еслиheader=0
, предполагается, что началом данных является первая строка. Указание аргументаskipto
не влияет на аргументheader
. Обратите внимание, что если указаны номера строкskipto
иcomment
илиignoreemptyrows
, строка данных будет первой незакомментированной/непустой строкой после номера строки, то есть если указанный номер строки является закомментированной строкой, то строка данных фактически будет следующей незакомментированной строкой. -
footerskip::Integer
: количество строк в конце файла, которые не нужно анализировать. Обратите внимание, что закомментированные строки (см. именованный аргументcomment
) не учитываются в количестве строк, заданном дляfooterskip
, — они полностью игнорируются анализатором. -
transpose::Bool
: чтение CSV-файла «с транспонированием», т. е. каждый столбец анализируется как строка. -
comment::String
: строка, при анализе которой строки, начинающиеся с нее, будут пропущены. Обратите внимание, что если указан заголовок номера строки илиskipto
иcomment
, строка заголовка или данных будет первой незакомментированной/непустой строкой после номера строки, то есть если указанный номер строки является закомментированной строкой, то строка заголовка или данных фактически будет следующей незакомментированной строкой. -
ignoreemptyrows::Bool=true
: следует ли игнорировать пустые строки в файле (если задано значениеfalse
, каждому столбцу будет присвоено значениеmissing
для этой пустой строки). -
select
:AbstractVector
дляInteger
,Symbol
,String
илиBool
либо выборочная функция вида(i, name) -> keep::Bool
. В результирующем файлеCSV.File
будут проанализированы и доступны только столбцы в коллекции или столбцы, для которых выборочная функция возвращаетtrue
. Недопустимые значения вselect
игнорируются. -
drop
: обратный эквивалентselect
.AbstractVector
дляInteger
,Symbol
,String
илиBool
либо функция отбрасывания вида(i, name) -> drop::Bool
. В результирующем файлеCSV.File
будут игнорироваться столбцы в коллекции или столбцы, для которых функция отбрасывания возвращаетtrue
. Недопустимые значения вdrop
игнорируются. -
limit
:Integer
для указания ограниченного числа строк для анализа в CSV-файле. Используется в сочетании сskipto
для чтения конкретного непрерывного фрагмента в файле. Обратите внимание, что когда в больших файлах для анализа применяется несколько потоков, аргументlimit
может не выводить точное количество анализируемых строк. Если необходимо, для определения точного ограничения используйтеthreaded=false
. -
buffer_in_memory
: логическое значениеBool
, по умолчаниюfalse
, которое определяет, будет лиCmd
,IO
или источник в формате GZIP считываться/распаковываться в памяти, а не во временном файле. -
ntasks::Integer=Threads.nthreads()
[неприменимо кCSV.Rows
]: для файлов с многопоточным анализом управляет количеством задач, порождаемых для чтения файла в параллельных фрагментах. Значением по умолчанию является количество потоков, с которыми была запущена среда Julia (т. е. переменная средыJULIA_NUM_THREADS
илиjulia -t N
). Установкаntasks=1
позволит избежать вызововThreads.@spawn
, и файлы просто будут последовательно считываться в основном потоке. По умолчанию для небольших файлов (< 5_000 ячеек) также будет использоваться один поток. -
rows_to_check::Integer=30
[неприменимо кCSV.Rows
]: файл с многопоточным анализом будет разбит наntasks
равных фрагментов.rows_to_check
управляет количеством проверяемых строк для корректного обнаружения допустимых строк при анализе. Для некоторых файлов с очень большими текстовыми полями, заключенными в кавычки, может потребоваться задать более высокое значениеlines_to_check
(10, 30 и т. д.) для корректного обнаружения этих строк при анализе. -
source
[применимо только для вектора входных данных дляCSV.File
]:Symbol
,String
либоPair
дляSymbol
илиString
дляVector
. В одиночном элементеSymbol
илиString
указывается имя столбца, который будет добавлен в число анализируемых. Значения столбца будут «именем» источника входных данных (обычно именем файла), из которого было проанализировано значение. Вторым элементом пары (Pair
) должен быть вектор (Vector
) значений, число которых соответствует количеству наборов входных данных. Каждое значение будет использоваться вместо имени набора входных данных для значений этого набора в автоматически добавляемом столбце.
Параметры анализа
-
missingstring
: либоnothing
,String
, либоVector{String}
для использования в качестве контрольных значений, которые будут проанализированы какmissing
. Если передаетсяnothing
, контрольные или отсутствующие значения анализироваться не будут. Значением по умолчанию являетсяmissingstring=""
, что означает, что отсутствующим (missing
) считается только пустое поле (два последовательных разделителя). -
delim=','
:Char
илиString
, указывающие на способ разделения столбцов в файле. Если аргумент не задан, анализатор по умолчанию попытается определить наиболее часто встречающийся разделитель в первых десяти строках входных данных. -
ignorerepeated::Bool=false
: следует ли при анализе игнорировать повторяющиеся (последовательные/непоследовательные) разделители. Полезно для файлов фиксированной ширины с заполнением разделителями между ячейками. -
quoted::Bool=true
: будет ли анализатор проверять наличие символовquotechar
в начале и конце ячеек. -
quotechar='"'
,openquotechar
,closequotechar
: символChar
(или другие начальный и конечный символы), указывающий на поле, заключенное в кавычки, которое может содержать текстовые разделители или символы новой строки. -
escapechar='"'
:Char
используется для экранирования символов кавычек в поле, заключенном в кавычки. -
dateformat::Union{String, Dates.DateFormat, Nothing, AbstractDict}
: строка формата даты для указания способа форматирования столбцов Date/DateTime для всего файла. Если задана какAbstractDict
, строки формата даты для указания способа форматирования столбцов Date/DateTime, соответствующих ключам. Dict может сопоставлять индекс столбцаInt
, или имяSymbol
, илиString
со строкой формата для этого столбца. -
decimal='.'
:Char
, указывающий способ разделения десятичных частей в числах с плавающей запятой, т. е.3.14
использует'.'
или3,14
использует запятую','
. -
groupmark=nothing
: дополнительно указывает однобайтовый символ, обозначающий знак группировки чисел, что позволяет анализировать числа, имеющие, например, разделители тысяч (1,000.00
). -
truestrings
,falsestrings
:Vector{String}
, указывающие на способ представления значенийtrue
илиfalse
. По умолчанию"true", "True", "TRUE", "T", "1"
используются для определенияtrue
, а"false", "False", "FALSE", "F", "0"
— для определенияfalse
. Обратите внимание, что столбцы, имеющие только значения1
и0
, по умолчанию будут иметь тип столбцаInt64
, если только явно не будет запрошен типBool
с помощью именованного аргументаtypes
. -
stripwhitespace=false
: если задано значение true, из строковых значений, включая имена столбцов, удаляются начальные и конечные символы пробела.
Параметры типов столбцов
-
types
: один из типовType
,AbstractVector
илиAbstractDict
или функция вида(i, name) -> Union{T, Nothing}
, которая будет использоваться для типов столбцов. Если указан один тип (Type
), все столбцы будут проанализированы с этим единственным типом.AbstractDict
может сопоставлять индекс столбцаInteger
либо имяSymbol
илиString
с типом столбца, т. е.Dict(1=>Float64)
задаст первый столбец какFloat64
,Dict(:column1=>Float64)
задаст столбец с именемcolumn1
какFloat64
иDict("column1"=>Float64)
задастcolumn1
какFloat64
. Если указан вектор (Vector
), он должен соответствовать количеству столбцов, указанных или обнаруженных вheader
. Если указана функция, она принимает в качестве аргументов индекс и имя столбца и должна возвращать желаемый тип столбца, либоnothing
, указывающий на необходимость определения типа столбца при анализе. -
typemap::IdDict{Type, Type}
: сопоставление типа, который должен быть заменен в любом случае другим типом, т. е.Dict(Float64=>String)
изменит каждый обнаруженный столбец типаFloat64
на анализируемый типаString
. С другим типом могут быть сопоставлены только стандартные типы, т. е.Int64
,Float64
,Date
,DateTime
,Time
иBool
. Обнаруженный столбец одного из этих типов будет сопоставлен с указанным типом. -
pool::Union{Bool, Real, AbstractVector, AbstractDict, Function, Tuple{Float64, Int}}=(0.2, 500)
[не поддерживается вCSV.Rows
]: определяет, будут ли столбцы созданы какPooledArray
. Если задано значениеtrue
, все столбцы, обнаруживаемые какString
, будут объединены. Или доля уникальных значений, ниже которой столбцыString
должны быть объединены (то есть если количество уникальных строк в столбце меньше 25 %,pool=0.25
, они будут объединены). Если указан в видеTuple{Float64, Int}
как(0.2, 500)
, он представляет порог кардинальности в процентах в виде первого элемента кортежа (0.2
) и верхний предел для числа уникальных значений (500
), ниже которого столбец будет добавлен в пул. Это значение по умолчанию (pool=(0.2, 500)
). Если заданAbstractVector
, каждый элемент должен иметь типBool
,Real
илиTuple{Float64, Int}
, а количество элементов — соответствовать количеству столбцов в наборе данных. Если заданAbstractDict
, значениеBool
,Real
илиTuple{Float64, Int}
может быть предоставлено для отдельных столбцов, где ключ словаря задан как индекс столбцаInteger
, или имя столбца какSymbol
илиString
. Если указана функция, она должна принимать в качестве двух аргументов индекс и имя столбца и возвращать для каждого столбца значениеBool
,Real
,Tuple{Float64, Int}
илиnothing
. -
downcast::Bool=false
: определяет, будет ли для обнаруженных столбцов типаInt64
выполняться нисходящее преобразование до наименьшего возможного целочисленного типа, напримерInt8
,Int16
,Int32
и т. д. -
stringtype=InlineStrings.InlineString
: определяет способ возврата обнаруженных строковых столбцов. Значение по умолчанию —InlineString
, которое хранит строковые данные в примитивном типе фиксированного размера, что позволяет избежать чрезмерного использования динамической памяти. Если столбец имеет значения длиннее 32 байт, по умолчанию используетсяString
. Если передаетсяString
, все строковые столбцы будут просто обычными значениямиString
. Если передаетсяPosLenString
, строковые столбцы будут возвращены в виде вектораPosLenStringVector
, который представляет собой специальный «отложенный» векторAbstractVector
, выполняющий роль представления для исходных данных файла. Результатом может быть максимально эффективное время анализа, но следует учесть, что представлениеPosLenStringVector
делает его доступным только для чтения, поэтому такие операции, какpush!
,append!
илиsetindex!
, не поддерживаются. Он также содержит ссылку на весь источник входного набора данных, поэтому, например, попытка изменить или удалить базовый файл может завершиться сбоем. -
strict::Bool=false
: должны ли недопустимые значения выдавать ошибку анализа или заменяться наmissing
. -
silencewarnings::Bool=false
: если задано значениеstrict=false
, следует ли подавлять предупреждения о недопустимых значениях. -
maxwarnings::Int=100
: если в процессе анализа будет выведено болееmaxwarnings
предупреждений, дальнейшие предупреждения будут подавляться по умолчанию. При многопоточном анализе каждая задача синтаксического анализа будет выводить не болееmaxwarnings
. -
debug::Bool=false
: передачаtrue
приведет к выводу большого количества информационных сообщений во время анализа набора данных. Может быть полезно для сообщения о проблемах или выяснения того, что происходит внутри набора данных во время его анализа. -
validate::Bool=true
: нужно ли проверять, что столбцы, указанные в ключевых словахtypes
,dateformat
иpool
, действительно найдены в данных. Если задано значениеfalse
, проверка не выполняется, т. е. ошибка не возникнет, еслиtypes
/dateformat
/pool
задают параметры для столбцов, которые в действительности не встречаются в данных.
Параметры итерации
-
reusebuffer=false
[поддерживается только вCSV.Rows
]: следует ли при итерации выделять один буфер для строк и повторно использовать его в каждой итерации. Применяется только в том случае, если каждая строка будет итерироваться один раз и не будет использоваться повторно (например, при выполненииcollect(CSV.Rows(file))
применять этот параметр небезопасно, поскольку допустимой является только текущая итерируемая строка).
#
CSV.Rows
— Type
CSV.Rows(source; kwargs...) => CSV.Rows
Считывает входной CSV-файл, возвращая объект CSV.Rows
.
Аргумент input
может быть одним из указанных ниже:
-
имя файла, заданное в виде строки или типа FilePaths.jl
-
буфер байт
Vector{UInt8}
илиSubArray{UInt8, 1, Vector{UInt8}}
-
объект
CodeUnits
, заключающийString
в оболочку, напримерcodeunits(str)
-
строка в формате CSV также может быть передана как
IOBuffer(str)
-
Cmd
или другойIO
-
файл в формате GZIP (или данные в формате GZIP в любом из вышеперечисленных файлов), который будет автоматически распакован для анализа
Для чтения CSV-файла из URL-адреса используйте пакет HTTP.jl, где текст HTTP.Response
может быть передан следующим образом.
f = CSV.Rows(HTTP.get(url).body)
Другие входные данные IO
или Cmd
можно передать следующим образом: f = CSV.Rows(read(obj))
.
Несмотря на сходство с CSV.File
, CSV.Rows
предоставляет несколько иной интерфейс, но при этом имеет ряд преимуществ, включая следующие.
-
Незначительный объем занимаемой памяти. Во время итерации буферизируются только значения текущей строки.
-
Доступ к строкам обеспечивается только через итерацию. Для доступа к столбцам можно передать строки в табличный тип.
-
Вывод типов не производится. Каждый столбец или ячейка рассматриваются как
Union{String, Missing}
. При необходимости пользователь может воспользоваться функциейParsers.parse(T, str)
для преобразования значений в более конкретный тип или передать типы при построении, используя именованные аргументыtype
илиtypes
.
Открывает файл и с помощью переданных аргументов определяет количество столбцов, но не типы столбцов (столбцы по умолчанию имеют тип String
, если вручную не указано иное). Возвращаемый объект CSV.Rows
поддерживает интерфейс Tables.jl и может итерировать строки. Каждый объект строки поддерживает propertynames
, getproperty
и getindex
для доступа к значениям отдельных строк. Обратите внимание, что повторяющиеся имена столбцов будут обнаружены и скорректированы для обеспечения уникальности (повторяющееся имя столбца a
получит значение a_1
). Например, можно выполнить итерацию CSV-файла с именами столбцов a
, b
и c
, выполнив следующее.
for row in CSV.Rows(file)
println("a=$(row.a), b=$(row.b), c=$(row.c)")
end
Аргументы
Параметры структуры файла
-
header=1
: указывает способ определения имен столбцов. Если задан какInteger
, указывает строку для анализа имен столбцов. Если задан какAbstractVector{<:Integer}
, указывает набор строк для конкатенации в качестве имен столбцов.Vector{Symbol}
илиVector{String}
явным образом задают имена столбцов (должны соответствовать количеству столбцов в наборе данных). Если в наборе данных нет имен столбцов, либо задайте их в видеVector
, либо задайтеheader=0
илиheader=false
, и имена столбцов будут сгенерированы автоматически (Column1
,Column2
и т. д.). Обратите внимание, что если указан заголовок номера строки иcomment
илиignoreemptyrows
, строка заголовка будет первой незакомментированной/непустой строкой после номера строки, то есть если указанный номер строки является закомментированной строкой, то строка заголовка фактически будет следующей незакомментированной строкой. -
normalizenames::Bool=false
: следует ли «нормализовать» имена столбцов в допустимые символы идентификатора Julia. Полезно при использовании синтаксисаtbl.col1
getproperty
или при итерации строк и обращении к значениям столбцов строки черезgetproperty
(например,row.col1
) -
skipto::Integer
: указывает строку, с которой начинаются данные в CSV-файле. По умолчанию используется следующая строка после строки (строк)header
. Еслиheader=0
, предполагается, что началом данных является первая строка. Указание аргументаskipto
не влияет на аргументheader
. Обратите внимание, что если указаны номера строкskipto
иcomment
илиignoreemptyrows
, строка данных будет первой незакомментированной/непустой строкой после номера строки, то есть если указанный номер строки является закомментированной строкой, то строка данных фактически будет следующей незакомментированной строкой. -
footerskip::Integer
: количество строк в конце файла, которые не нужно анализировать. Обратите внимание, что закомментированные строки (см. именованный аргументcomment
) не учитываются в количестве строк, заданном дляfooterskip
, — они полностью игнорируются анализатором. -
transpose::Bool
: чтение CSV-файла «с транспонированием», т. е. каждый столбец анализируется как строка. -
comment::String
: строка, при анализе которой строки, начинающиеся с нее, будут пропущены. Обратите внимание, что если указан заголовок номера строки илиskipto
иcomment
, строка заголовка или данных будет первой незакомментированной/непустой строкой после номера строки, то есть если указанный номер строки является закомментированной строкой, то строка заголовка или данных фактически будет следующей незакомментированной строкой. -
ignoreemptyrows::Bool=true
: следует ли игнорировать пустые строки в файле (если задано значениеfalse
, каждому столбцу будет присвоено значениеmissing
для этой пустой строки). -
select
:AbstractVector
дляInteger
,Symbol
,String
илиBool
либо выборочная функция вида(i, name) -> keep::Bool
. В результирующем файлеCSV.File
будут проанализированы и доступны только столбцы в коллекции или столбцы, для которых выборочная функция возвращаетtrue
. Недопустимые значения вselect
игнорируются. -
drop
: обратный эквивалентselect
.AbstractVector
дляInteger
,Symbol
,String
илиBool
либо функция отбрасывания вида(i, name) -> drop::Bool
. В результирующем файлеCSV.File
будут игнорироваться столбцы в коллекции или столбцы, для которых функция отбрасывания возвращаетtrue
. Недопустимые значения вdrop
игнорируются. -
limit
:Integer
для указания ограниченного числа строк для анализа в CSV-файле. Используется в сочетании сskipto
для чтения конкретного непрерывного фрагмента в файле. Обратите внимание, что когда в больших файлах для анализа применяется несколько потоков, аргументlimit
может не выводить точное количество анализируемых строк. Если необходимо, для определения точного ограничения используйтеthreaded=false
. -
buffer_in_memory
: логическое значениеBool
, по умолчаниюfalse
, которое определяет, будет лиCmd
,IO
или источник в формате GZIP считываться/распаковываться в памяти, а не во временном файле. -
ntasks::Integer=Threads.nthreads()
[неприменимо кCSV.Rows
]: для файлов с многопоточным анализом управляет количеством задач, порождаемых для чтения файла в параллельных фрагментах. Значением по умолчанию является количество потоков, с которыми была запущена среда Julia (т. е. переменная средыJULIA_NUM_THREADS
илиjulia -t N
). Установкаntasks=1
позволит избежать вызововThreads.@spawn
, и файлы просто будут последовательно считываться в основном потоке. По умолчанию для небольших файлов (< 5_000 ячеек) также будет использоваться один поток. -
rows_to_check::Integer=30
[неприменимо кCSV.Rows
]: файл с многопоточным анализом будет разбит наntasks
равных фрагментов.rows_to_check
управляет количеством проверяемых строк для корректного обнаружения допустимых строк при анализе. Для некоторых файлов с очень большими текстовыми полями, заключенными в кавычки, может потребоваться задать более высокое значениеlines_to_check
(10, 30 и т. д.) для корректного обнаружения этих строк при анализе. -
source
[применимо только для вектора входных данных дляCSV.File
]:Symbol
,String
либоPair
дляSymbol
илиString
дляVector
. В одиночном элементеSymbol
илиString
указывается имя столбца, который будет добавлен в число анализируемых. Значения столбца будут «именем» источника входных данных (обычно именем файла), из которого было проанализировано значение. Вторым элементом пары (Pair
) должен быть вектор (Vector
) значений, число которых соответствует количеству наборов входных данных. Каждое значение будет использоваться вместо имени набора входных данных для значений этого набора в автоматически добавляемом столбце.
Параметры анализа
-
missingstring
: либоnothing
,String
, либоVector{String}
для использования в качестве контрольных значений, которые будут проанализированы какmissing
. Если передаетсяnothing
, контрольные или отсутствующие значения анализироваться не будут. Значением по умолчанию являетсяmissingstring=""
, что означает, что отсутствующим (missing
) считается только пустое поле (два последовательных разделителя). -
delim=','
:Char
илиString
, указывающие на способ разделения столбцов в файле. Если аргумент не задан, анализатор по умолчанию попытается определить наиболее часто встречающийся разделитель в первых десяти строках входных данных. -
ignorerepeated::Bool=false
: следует ли при анализе игнорировать повторяющиеся (последовательные/непоследовательные) разделители. Полезно для файлов фиксированной ширины с заполнением разделителями между ячейками. -
quoted::Bool=true
: будет ли анализатор проверять наличие символовquotechar
в начале и конце ячеек. -
quotechar='"'
,openquotechar
,closequotechar
: символChar
(или другие начальный и конечный символы), указывающий на поле, заключенное в кавычки, которое может содержать текстовые разделители или символы новой строки. -
escapechar='"'
:Char
используется для экранирования символов кавычек в поле, заключенном в кавычки. -
dateformat::Union{String, Dates.DateFormat, Nothing, AbstractDict}
: строка формата даты для указания способа форматирования столбцов Date/DateTime для всего файла. Если задана какAbstractDict
, строки формата даты для указания способа форматирования столбцов Date/DateTime, соответствующих ключам. Dict может сопоставлять индекс столбцаInt
, или имяSymbol
, илиString
со строкой формата для этого столбца. -
decimal='.'
:Char
, указывающий способ разделения десятичных частей в числах с плавающей запятой, т. е.3.14
использует'.'
или3,14
использует запятую','
. -
groupmark=nothing
: дополнительно указывает однобайтовый символ, обозначающий знак группировки чисел, что позволяет анализировать числа, имеющие, например, разделители тысяч (1,000.00
). -
truestrings
,falsestrings
:Vector{String}
, указывающие на способ представления значенийtrue
илиfalse
. По умолчанию"true", "True", "TRUE", "T", "1"
используются для определенияtrue
, а"false", "False", "FALSE", "F", "0"
— для определенияfalse
. Обратите внимание, что столбцы, имеющие только значения1
и0
, по умолчанию будут иметь тип столбцаInt64
, если только явно не будет запрошен типBool
с помощью именованного аргументаtypes
. -
stripwhitespace=false
: если задано значение true, из строковых значений, включая имена столбцов, удаляются начальные и конечные символы пробела.
Параметры типов столбцов
-
types
: один из типовType
,AbstractVector
илиAbstractDict
или функция вида(i, name) -> Union{T, Nothing}
, которая будет использоваться для типов столбцов. Если указан один тип (Type
), все столбцы будут проанализированы с этим единственным типом.AbstractDict
может сопоставлять индекс столбцаInteger
либо имяSymbol
илиString
с типом столбца, т. е.Dict(1=>Float64)
задаст первый столбец какFloat64
,Dict(:column1=>Float64)
задаст столбец с именемcolumn1
какFloat64
иDict("column1"=>Float64)
задастcolumn1
какFloat64
; он должен соответствовать количеству столбцов. Если указан вектор (Vector
), он должен соответствовать количеству столбцов, указанных или обнаруженных вheader
. Если указана функция, она принимает в качестве аргументов индекс и имя столбца и должна возвращать желаемый тип столбца, либоnothing
, указывающий на необходимость определения типа столбца при анализе. -
typemap::IdDict{Type, Type}
: сопоставление типа, который должен быть заменен в любом случае другим типом, т. е.Dict(Float64=>String)
изменит каждый обнаруженный столбец типаFloat64
на анализируемый типаString
. С другим типом могут быть сопоставлены только стандартные типы, т. е.Int64
,Float64
,Date
,DateTime
,Time
иBool
. Обнаруженный столбец одного из этих типов будет сопоставлен с указанным типом. -
pool::Union{Bool, Real, AbstractVector, AbstractDict, Function, Tuple{Float64, Int}}=(0.2, 500)
[не поддерживается вCSV.Rows
]: определяет, будут ли столбцы созданы какPooledArray
. Если задано значениеtrue
, все столбцы, обнаруживаемые какString
, будут объединены. Или доля уникальных значений, ниже которой столбцыString
должны быть объединены (то есть если количество уникальных строк в столбце меньше 25 %,pool=0.25
, они будут объединены). Если указан в видеTuple{Float64, Int}
как(0.2, 500)
, он представляет порог кардинальности в процентах в виде первого элемента кортежа (0.2
) и верхний предел для числа уникальных значений (500
), ниже которого столбец будет добавлен в пул. Это значение по умолчанию (pool=(0.2, 500)
). Если заданAbstractVector
, каждый элемент должен иметь типBool
,Real
илиTuple{Float64, Int}
, а количество элементов — соответствовать количеству столбцов в наборе данных. Если заданAbstractDict
, значениеBool
,Real
илиTuple{Float64, Int}
может быть предоставлено для отдельных столбцов, где ключ словаря задан как индекс столбцаInteger
или имя столбца какSymbol
илиString
. Если указана функция, она должна принимать в качестве двух аргументов индекс и имя столбца и возвращать для каждого столбца значениеBool
,Real
,Tuple{Float64, Int}
илиnothing
. -
downcast::Bool=false
: определяет, будет ли для обнаруженных столбцов типаInt64
выполняться нисходящее преобразование до наименьшего возможного целочисленного типа, напримерInt8
,Int16
,Int32
и т. д. -
stringtype=InlineStrings.InlineString
: определяет способ возврата обнаруженных строковых столбцов. Значение по умолчанию —InlineString
, которое хранит строковые данные в примитивном типе фиксированного размера, что позволяет избежать чрезмерного использования динамической памяти. Если столбец имеет значения длиннее 32 байт, по умолчанию используетсяString
. Если передаетсяString
, все строковые столбцы будут просто обычными значениямиString
. Если передаетсяPosLenString
, строковые столбцы будут возвращены в виде вектораPosLenStringVector
, который представляет собой специальный «отложенный» векторAbstractVector
, выполняющий роль представления для исходных данных файла. Результатом может быть максимально эффективное время анализа, но следует учесть, что представлениеPosLenStringVector
делает его доступным только для чтения, поэтому такие операции, какpush!
,append!
илиsetindex!
, не поддерживаются. Он также содержит ссылку на весь источник входного набора данных, поэтому, например, попытка изменить или удалить базовый файл может завершиться сбоем. -
strict::Bool=false
: должны ли недопустимые значения выдавать ошибку анализа или заменяться наmissing
. -
silencewarnings::Bool=false
: если задано значениеstrict=false
, следует ли подавлять предупреждения о недопустимых значениях. -
maxwarnings::Int=100
: если в процессе анализа будет выведено болееmaxwarnings
предупреждений, дальнейшие предупреждения будут подавляться по умолчанию. При многопоточном анализе каждая задача синтаксического анализа будет выводить не болееmaxwarnings
. -
debug::Bool=false
: передачаtrue
приведет к выводу большого количества информационных сообщений во время анализа набора данных. Может быть полезно для сообщения о проблемах или выяснения того, что происходит внутри набора данных во время его анализа. -
validate::Bool=true
: нужно ли проверять, что столбцы, указанные в ключевых словахtypes
,dateformat
иpool
, действительно найдены в данных. Если задано значениеfalse
, проверка не выполняется, т. е. ошибка не возникнет, еслиtypes
/dateformat
/pool
задают параметры для столбцов, которые в действительности не встречаются в данных.
Параметры итерации
-
reusebuffer=false
[поддерживается только вCSV.Rows
]: следует ли при итерации выделять один буфер для строк и повторно использовать его в каждой итерации. Применяется только в том случае, если каждая строка будет итерироваться один раз и не будет использоваться повторно (например, при выполненииcollect(CSV.Rows(file))
применять этот параметр небезопасно, поскольку допустимой является только текущая итерируемая строка).
Вспомогательные функции
#
CSV.detect
— Function
CSV.detect(str::String)
Для анализа значения из простой строки используется та же логика, что и в CSV.File
для определения типов столбцов. Это может быть полезно в сочетании с типом CSV.Rows
, который возвращает каждую ячейку файла в виде строки. Последовательность попыток такова: Int
, Float64
, Date
, DateTime
, Bool
, и если все попытки оказываются неудачными, возвращается входная строка. Ошибки не возникают. Для расширенного использования можно передать собственный тип Parsers.Options
в качестве именованного аргумента option=ops
для определения контрольного значения.
Общие термины
Стандартные типы
Типы, которые определяются по умолчанию, если пользователь не задал типы столбцов. К ним относятся следующие: Int64
, Float64
, Date
, DateTime
, Time
, Bool
и String
.
Символы новой строки
При любых операциях анализа символы новой строки определяются автоматически независимо от того, представлены ли они в данных в виде одиночного символа новой строки ('\n'
), одиночного символа возврата ('\r'
) или полной последовательности CRLF ("\r\n"
).
Мощность множества
Отношение количества уникальных значений к общему количеству значений в столбце. Столбцы «низкой мощности» имеют малую долю уникальных значений, или, говоря иначе, в столбце немного уникальных значений, которые повторяются многократно. Столбцы «высокой мощности» имеют большую долю уникальных значений относительно общего количества значений. Их можно представить как «столбцы идентификаторов», в которых каждое или почти каждое значение представляет собой уникальный идентификатор и не повторяется (или почти не повторяется).