Чтение

В этом разделе рассматриваются различные входные данные и параметры, поддерживаемые типом 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=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, недопустимые значения приводят к выдаче ошибки вместо предупреждения.

debug

Аргумент типа Bool, управляющий выводом дополнительной «отладочной» информации во время анализа. Может быть полезен, если анализ не дал ожидаемого результата или есть подозрение на какую-либо ошибку.

Справка по API

# CSV.readFunction

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.FileType

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.ChunksType

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.RowsType

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.detectFunction

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").

Мощность множества

Отношение количества уникальных значений к общему количеству значений в столбце. Столбцы «низкой мощности» имеют малую долю уникальных значений, или, говоря иначе, в столбце немного уникальных значений, которые повторяются многократно. Столбцы «высокой мощности» имеют большую долю уникальных значений относительно общего количества значений. Их можно представить как «столбцы идентификаторов», в которых каждое или почти каждое значение представляет собой уникальный идентификатор и не повторяется (или почти не повторяется).