48  Получение помощи

На этой странице мы рассматриваем то, как получить помощь, разместив пост о проблеме Github или разместив воспроизводимый пример (“reprex”) в онлайн форуме.

48.1 Проблемы с Github

Код многих пакетов R и проектов размещен на сайте Github.com. Вы можете связаться напрямую с авторами через веб-сайт, разместив “Проблему”.

Более подробно читайте о том, как хранить свою работу в Github на странице Совместная работа с Github.

В Github каждый проект содержится внутри репозитория. В каждом репозитории содержится код, данные, выходные результаты, документация справки и т.п. Также существует способ коммуникации с авторами, который называется “Issues” (проблемы).

См. ниже страницу Github по пакету incidence2 (используется для создания эпидемических кривых). Вы можете увидеть, что вкладка “Issues” выделена желтым. Вы видите, что есть 5 открытых проблем.

Перейдя на вкладку Issues, вы увидите открытые проблемы. Просмотрите их, чтобы убедиться, что ваша проблема уже не рассматривается. Вы можете открыть новую проблему, нажав зеленую кнопку справа. Для этого вам потребуется учетная запись Github.

В своей проблеме следуйте приведенным ниже инструкциям и приведите минимальный, воспроизводимый пример. И, пожалуйста, будьте вежливы! Большинство людей, разрабатывающих пакеты и проекты на языке R, делают это в свободное время (как, например, это руководство!).

Чтобы ознакомиться с более подробными материалами по работе с проблемами в собственном репозитории Github, ознакомьтесь с Github документацией по проблемам.

48.2 Воспроизводимый пример

Предоставление воспроизводимого примера (“reprex”) - ключевой момент в получении помощи при написании сообщения на форуме или в проблеме на Github. Люди хотят помочь вам, но вы должны дать им пример, с которым они могут работать на своем компьютере. Пример должен:

  • демонстрировать проблему, с которой вы столкнулись
  • быть минимальным в том плане, чтобы он включал только данные и код, требуемые для воспроизведения вашей проблемы
  • быть воспроизводимым, чтобы все объекты (например, данные), вызов пакетов (например, library() или p_load()) были включены

Также будьте уверены, что вы не размещаете чувствительные данные в reprex! Вы можете создать примеры датафреймов, либо использовать один из датафреймов, встроенных в R (введите data(), чтобы открыть список этих наборов данных).

Пакет reprex

Пакет reprex может помочь вам в создании воспроизводимого примера:

  1. reprex устанавливается вместе с tidyverse, поэтому загрузить любой из двух пакетов
# установите/загрузите tidyverse (который включает reprex)
pacman::p_load(tidyverse)
  1. Начните скрипт R, который создает вашу проблему пошагово, начиная с загрузки пакетов и данных.
# загрузите пакеты
pacman::p_load(
     tidyverse,  # управление данными и визуализация
     outbreaks)  # наборы данных с примерами вспышек

# построчный список для эпидемии гриппа
outbreak_raw <- outbreaks::fluH7N9_china_2013  # извлекаем набор данных из пакета outbreaks

# вычищаем набор данных
outbreak <- outbreak_raw %>% 
     mutate(across(contains("date"), as.Date))

# Строим график эпидемии

ggplot(data = outbreak)+
     geom_histogram(
          mapping = aes(x = date_of_onset),
          binwidth = 7
     )+
  scale_x_date(
    date_format = "%d %m"
  )

Копируем весь код в буфер обмена, затем выполняем следующую команду:

reprex::reprex()

В панели RStudio Viewer появится HTML-вывод. Он будет содержать весь ваш код, а также предупреждения, ошибки и графики. Этот вывод также копируется в буфер обмена, поэтому его можно сразу поместить в проблему на Github или в сообщение на форуме.

  • Если вы задали session_info = TRUE будет включен выходной результат sessioninfo::session_info() с версиями вашего R и пакета R
  • Вы можете задать рабочую директорию в wd =
  • Вы можете более подробно прочитать об этих аргументах и возможных вариациях в документации или введя ?reprex

В примере выше команда ggplot() не была выполнена, поскольку date_format = неверный - он должен быть date_labels =.

Минимальные данные

Помощники должны иметь возможность использовать ваши данные - в идеале они должны быть способны их создать с помощью кода.

Чтобы создать минимальный набор данных, попробуйте анонимизировать и использовать только подмножество наблюдений.

В РАЗРАБОТКЕ - вы можете также использовать функцию dput(), чтобы создать минимальный набор данных.

48.3 Пост на форуме

Прочитайте большое количество постов на форуме. Попробуйте понять, какие посты написаны хорошо, а какие - нет.

  1. Во-первых, решите, задавать ли вообще вопрос. Вы тщательно изучили форумы, попробовали разные слова для поиска, может быть ваш вопрос уже был задан?

  2. Дайте своему вопросу информативный заголовок (а не “Помогите! Не работает”).

  3. Напишите свой вопрос:

  • Представьте свою ситуацию и проблему
  • Дайте ссылки на посты с похожими проблемами и объясните, почему они не отвечают на ваш вопрос
  • Включите необходимую информацию, чтобы помочь кому-то, кто не знаком с контекстом вашей работы
  • Дайте минимальный воспроизводимый пример с информацией о вашей сессии R
  • Используйте правильную орфографию, грамматику, пунктуацию, разбейте свой вопрос на абзацы, чтобы его было легче читать

  1. Следите за размещенным вопросом и отвечайте на любые просьбы о разъяснении. Будьте вежливы и любезны - часто люди, отвечающие на вопросы, добровольно тратят свое время, чтобы помочь вам. Если у вас есть дополнительный вопрос, подумайте, стоит ли его опубликовать отдельно.

  2. Отметьте вопрос отвеченным, если вы получите ответ, который удовлетворяет изначальному запросу. Это помогает другим быстрее узнать решение.

Прочитайте эти посты о том, как задавать хороший вопрос в Кодексе поведения Stack overflow.

48.4 Ресурсы

Страница Tidyverse о том, как получить помощь!

Советы по созданию минимального набора данных

Документация по функции dput