Автоматическая документация наборов данных

Question

Сейчас я работаю над проектом, в котором я медленно накапливаю кучу разных переменных из разных источников. Будучи несколько умным человеком, я создал отдельный подкаталог для каждого в главном каталоге "original_data" и включил файл.txt с URL-адресом и другими дескрипторами, из которых я получил данные. Будучи недостаточно умным человеком, эти.txt файлы не имеют структуры.

Теперь передо мной стоит задача составления раздела методов, в котором документируются все различные источники данных. Я готов пройтись и добавить структуру к данным, но тогда мне нужно будет найти или создать инструмент отчетности для сканирования каталогов и извлечения информации.

Это похоже на то, что ProjectTemplate уже бы, но я не могу найти эту функциональность там.

Существует ли такой инструмент?

Если это не так, какие соображения следует учитывать для обеспечения максимальной гибкости? Некоторые предварительные мысли:

1. Следует использовать язык разметки (YAML?)
2. Все подкаталоги должны быть отсканированы
3. Для облегчения (2) следует использовать стандартное расширение для дескриптора набора данных
4. Крайне важно, чтобы сделать это наиболее полезным, должен быть какой-то способ сопоставления дескрипторов переменных с именем, которое они в конечном итоге принимают. Поэтому либо все переименование переменных должно выполняться в исходных файлах, а не на этапе очистки (менее чем идеально), некоторый синтаксический анализ должен выполняться механизмом документации для отслеживания изменений имен переменных (тьфу!), Или некоторые Следует использовать более простой гибрид, такой как разрешение переименования переменных в файле разметки.
5. В идеале отчет также должен быть шаблонным (например, "Мы извлекли переменную [var] из набора данных [dset] в [date].") И, возможно, связан с Sweave.
6. Инструмент должен быть достаточно гибким, чтобы не быть чрезмерно обременительным. Это означает, что минимальная документация будет просто именем набора данных.

Answer 1

Это очень хороший вопрос: люди должны быть очень обеспокоены всеми последовательностями сбора данных, агрегации, преобразования и т. Д., Которые составляют основу для статистических результатов. К сожалению, это широко не практикуется.

Прежде чем ответить на ваши вопросы, я хочу подчеркнуть, что это, похоже, связано с общей целью управления происхождением данных. Я мог бы также дать вам ссылку Google, чтобы узнать больше.:) Есть множество ресурсов, которые вы найдете, такие как опросы, программные инструменты (например, некоторые из них перечислены в записи в Википедии), различные исследовательские проекты (например, Provenance Challenge) и многое другое.

Это концептуальное начало, теперь для решения практических вопросов:

Сейчас я работаю над проектом, в котором я медленно накапливаю кучу разных переменных из разных источников. Будучи несколько умным человеком, я создал отдельный подкаталог для каждого в главном каталоге "original_data" и включил файл.txt с URL-адресом и другими дескрипторами, из которых я получил данные. Будучи недостаточно умным человеком, эти.txt файлы не имеют структуры.

Добро пожаловать в кошмар каждого.:)

Теперь передо мной стоит задача составления раздела методов, в котором документируются все различные источники данных. Я готов пройтись и добавить структуру к данным, но тогда мне нужно будет найти или создать инструмент отчетности для сканирования каталогов и извлечения информации.

Нет проблем. list.files(...,recursive = TRUE) может стать хорошим другом; смотрите также listDirectory() в R.utils,

Стоит отметить, что заполнение раздела методов по источникам данных является узким приложением в области происхождения данных. На самом деле, весьма прискорбно, что представление задач CRAN по воспроизводимым исследованиям фокусируется только на документации. По моему опыту, цели происхождения данных представляют собой подмножество воспроизводимых исследований, а документация по манипулированию данными, а результаты - это часть происхождения данных. Таким образом, этот вид задачи все еще находится в зачаточном состоянии в отношении воспроизводимых исследований. Это может быть полезно для ваших целей, но в конечном итоге вы перерастете это.:)

Существует ли такой инструмент?

Да. Что это за инструменты? Mon Dieu... это очень ориентированный на приложения в целом. В R, я думаю, что этим инструментам не уделяется много внимания (см. Ниже). Это довольно прискорбно - либо я что-то упускаю, либо сообщество R пропускает то, что мы должны использовать.

Для базового процесса, который вы описали, я обычно использую JSON (см. Этот ответ и этот ответ для комментариев о том, чем я занимаюсь). Для большей части моей работы я представляю это как "модель потока данных" (кстати, этот термин может быть неоднозначным, особенно в контексте вычислений, но я имею в виду это с точки зрения статистического анализа). Во многих случаях этот поток описывается с помощью JSON, поэтому нетрудно извлечь последовательность из JSON, чтобы выяснить, как возникли конкретные результаты.

Для более сложных или регулируемых проектов недостаточно JSON, и я использую базы данных, чтобы определить, как данные собирались, преобразовывались и т. Д. Для регулируемых проектов в базе данных может быть много аутентификации, журналирования и многого другого, чтобы гарантировать, что данные Происхождение хорошо документировано. Я подозреваю, что такого рода БД не в ваших интересах, так что давайте двигаться дальше...

1. Следует использовать язык разметки (YAML?)

Честно говоря, все, что вам нужно для описания вашего потока данных, будет адекватным. Большую часть времени я считаю достаточным иметь хороший JSON, хорошие макеты каталогов данных и хорошую последовательность сценариев.

2. Все подкаталоги должны быть отсканированы

Готово: listDirectory()

3. Для облегчения (2) следует использовать стандартное расширение для дескриптора набора данных

Тривиально: ".json".;-) Или ".SecretSauce" тоже работает.

4. Крайне важно, чтобы сделать это наиболее полезным, должен быть какой-то способ сопоставления дескрипторов переменных с именем, которое они в конечном итоге принимают. Поэтому либо все переименование переменных должно выполняться в исходных файлах, а не на этапе очистки (менее чем идеально), некоторый синтаксический анализ должен выполняться механизмом документации для отслеживания изменений имен переменных (тьфу!), Или некоторые Следует использовать более простой гибрид, такой как разрешение переименования переменных в файле разметки.

Как уже говорилось, это не совсем имеет смысла. Предположим, что я беру var1 а также var2и создать var3 а также var4, возможно var4 это просто отображение var2 к его квантилям и var3 наблюдательный максимум var1 а также var2; или я мог бы создать var4 от var2 обрезая крайние значения. Если я сделаю это, оставлю ли я имя var2? С другой стороны, если вы имеете в виду просто сопоставление "длинных имен" с "простыми именами" (т. Е. Текстовые дескрипторы с переменными R), то это то, что вы можете сделать только вы. Если у вас очень структурированные данные, нетрудно создать список текстовых имен, соответствующих именам переменных; В качестве альтернативы вы можете создать токены, для которых можно выполнить подстановку строк. Я не думаю, что сложно создать CSV (или, что еще лучше, JSON;-)), который сопоставляет имя переменной с дескриптором. Просто продолжайте проверять, что все переменные имеют соответствующие строки дескриптора, и остановитесь, как только это будет сделано.

5. В идеале отчет также должен быть шаблонным (например, "Мы извлекли переменную [var] из набора данных [dset] в [date].") И, возможно, связан с Sweave.

Вот где другие предложения roxygen а также roxygen2 можно применять.

6. Инструмент должен быть достаточно гибким, чтобы не быть чрезмерно обременительным. Это означает, что минимальная документация будет просто именем набора данных.

Хм, я в тупике:)

(*) Кстати, если вам нужен один проект FOSS, связанный с этим, посмотрите таверну. Он был интегрирован с R, как описано в нескольких местах. Это может быть излишним для ваших нужд в настоящее время, но это стоит изучить в качестве примера прилично зрелой системы рабочего процесса.

---

Примечание 1: потому что я часто использую bigmemory для больших наборов данных я должен назвать столбцы каждой матрицы. Они хранятся в файле дескриптора для каждого двоичного файла. Этот процесс поощряет создание дескрипторов, сопоставляющих имена переменных (и матрицы) с дескрипторами. Если вы храните ваши данные в базе данных или в других внешних файлах, поддерживающих произвольный доступ и множественный доступ для чтения / записи (например, файлы с отображением в памяти, файлы HDF5, что угодно, кроме файлов.rdat), вы, вероятно, обнаружите, что добавление дескрипторов становится второй натурой.