# Install and load the latest version of the package from Github
::p_load_current_gh("reconverse/reportfactory")
pacman#remotes::install_github("reconverse/reportfactory") # alternative
41 Tổ chức báo cáo định kỳ
Chương này bao gồm reportfactory package, là một package hỗ trợ việc báo cáo sử dụng R Markdown.
Trong các tình huống mà bạn chạy báo cáo thường xuyên (hàng ngày, hàng tuần, v.v.), nó giúp giảm bớt việc soạn nhiều tệp R Markdown và tổ chức các kết quả đầu ra của chúng. Về bản chất, nó cung cấp một “nhà máy” mà từ đó bạn có thể chạy các báo cáo R Markdown, nhận các thư mục được đánh dấu ngày tháng và thời gian tự động cho kết quả đầu ra và có quyền kiểm soát phiên bản “nhẹ”.
reportfactory là một trong những packages được phát triển bởi RECON (R Epidemics Consortium). Đây là website và Github của họ.
41.1 Chuẩn bị
Tải packages
Từ trong RStudio, hãy cài đặt phiên bản mới nhất của reportfactory package từ Github.
Bạn có thể thực hiện việc này thông qua pacman package với p_load_current_gh()
, lệnh này sẽ buộc nhập phiên bản mới nhất từ Github. Cung cấp chuỗi ký tự “reconverse/reportfactory”, trong đó chỉ định tổ chức Github (reconverse) và kho lưu trữ (reportfactory). Bạn cũng có thể sử dụng install_github()
từ remotes package để thay thế.
41.2 Nhà máy mới
Để tạo một nhà máy mới, chạy hàm new_factory()
. Thao tác này sẽ tạo một thư mục dự án R độc lập mới. Mặc định là:
- Nhà máy sẽ được thêm vào thư mục làm việc của bạn
- Tên của nhà máy dự án R sẽ được gọi là “new_factory.Rproj”
- Phiên RStudio của bạn sẽ “chuyển sang” dự án R này
# This will create the factory in the working directory
new_factory()
Nhìn vào bên trong nhà máy, bạn có thể thấy rằng các thư mục con và một số tệp đã được tạo tự động.
- Thư mục report_sources sẽ chứa các scripts R Markdown của bạn, các scripts này sẽ tạo ra các báo cáo của bạn
- Thư mục outputs sẽ chứa các kết quả đầu ra của báo cáo (ví dụ: HTML, Word, PDF, v.v.)
- Thư mục scripts có thể được sử dụng để lưu trữ các scripts R khác (ví dụ: được lấy từ các scripts Rmd của bạn)
- Thư mục data có thể được sử dụng để chứa dữ liệu của bạn (bao gồm các thư mục con “thô” và “sạch”)
- Tệp .here, vì vậy bạn có thể sử dụng here package để gọi các tệp trong thư mục con theo mối quan hệ của chúng với thư mục gốc này (xem chương R projects để biết thêm chi tiết)
- Tệp gitignore được tạo trong trường hợp bạn liên kết dự án R này với kho lưu trữ Github (xem Version control and collaboration with Github)
- Tệp README trống, nếu bạn sử dụng kho lưu trữ Github
THẬN TRỌNG: tùy thuộc vào cài đặt máy tính của bạn, các tệp như “.here” có thể tồn tại nhưng ẩn.
Trong số các cài đặt mặc định, dưới đây là một số cài đặt mà bạn có thể điều chỉnh trong lệnh new_factory()
:
factory =
- Đặt tên cho thư mục gốc (mặc định là “new_factory”)
path =
- Chỉ định đường dẫn tệp cho nhà máy mới (mặc định là thư mục làm việc)
report_sources =
Đặt tên thay thế cho thư mục con chứa các R Markdown scripts (mặc định là “report_sources”)
outputs =
Đặt tên thay thế cho thư mục chứa kết quả đầu ra báo cáo (mặc định là “outputs”)
Xem ?new_factory
để biết danh sách đầy đủ các đối số.
Khi bạn tạo nhà máy mới, phiên R của bạn được chuyển sang dự án R mới, vì vậy bạn nên tải lại package reportfactory.
::p_load(reportfactory) pacman
Bây giờ bạn có thể chạy lệnh factory_overview()
để xem cấu trúc bên trong (tất cả các thư mục và tệp) trong nhà máy.
factory_overview() # print overview of the factory to console
“Cây” các thư mục và tệp của nhà sản xuất được in ra R console. Lưu ý rằng trong thư mục “data” có các thư mục con cho dữ liệu “raw” (thô) và “clean” (sạch) cũng như dữ liệu CSV mẫu. Ngoài ra còn có “example_report.Rmd” trong thư mục “report_sources”.
41.3 Tạo báo cáo
Từ bên trong dự án R của nhà máy, hãy tạo báo cáo R Markdown giống như bạn thường làm và lưu nó vào thư mục “report_sources”. Xem chương R Markdown để biết hướng dẫn. Để ví dụ, chúng tôi đã thêm những thứ sau vào nhà máy:
- R markdown script mới có tên “daily_sitrep.Rmd”, được lưu trong thư mục “report_sources”
- Dữ liệu cho báo cáo (“linelist_cleaned.rds”), được lưu vào thư mục con “clean” trong thư mục “data”
Chúng ta có thể thấy bằng cách sử dụng factory_overview()
R Markdown trong thư mục “report_sources” và tệp dữ liệu trong thư mục dữ liệu “clean” (được đánh dấu):
Dưới đây là ảnh chụp phần đầu của R Markdown “daily_sitrep.Rmd”. Bạn có thể thấy rằng định dạng đầu ra được đặt là HTML, thông qua tiêu đề YAML output: html_document
.
Trong script đơn giản này, có các lệnh để:
- Tải các packages cần thiết
- Nhập dữ liệu danh sách dòng bằng đường dẫn tệp từ package here (đọc thêm trong chương Import and export)
<- import(here("data", "clean", "linelist_cleaned.rds")) linelist
- In bảng tóm tắt các trường hợp và xuất nó với
export()
dưới dạng tệp .csv
- In một đường cong dịch tễ và xuất nó bằng
ggsave ()
dưới dạng tệp .png
Bạn chỉ có thể xem lại danh sách các báo cáo R Markdown trong thư mục “report_sources” bằng lệnh này:
list_reports()
41.4 Biên soạn
Trong nhà máy báo cáo, để “biên soạn” báo cáo R Markdown có nghĩa là .Rmd script sẽ được chạy và đầu ra sẽ được tạo (như được chỉ định trong script YAML, ví dụ như HTML, Word, PDF, v.v.).
Nhà máy sẽ tự động tạo một thư mục được đánh dấu ngày tháng và thời gian cho các kết quả đầu ra trong thư mục “outputs”.
Bản thân báo cáo và mọi tệp đã xuất do script tạo ra (ví dụ: csv, png, xlsx) sẽ được lưu vào thư mục này. Ngoài ra, bản thân script Rmd sẽ được lưu trong thư mục này, vì vậy bạn có bản ghi của phiên bản script đó.
Điều này trái ngược với hoạt động bình thường của R Markdown “knitted” (kết hợp), lưu kết quả đầu ra vào vị trí của script Rmd. Hành vi mặc định này có thể dẫn đến các thư mục đông đúc, lộn xộn. Nhà máy nhằm mục đích cải thiện tổ chức khi một người cần chạy báo cáo thường xuyên.
Biên soạn theo tên
Bạn có thể biên dịch một báo cáo cụ thể bằng cách chạy compile_reports()
và đặt tên Rmd script (không có phần mở rộng .Rmd) cho reports =
. Để đơn giản hơn, bạn có thể bỏ qua reports =
và chỉ cần viết tên R Markdown trong dấu ngoặc kép, như bên dưới.
Lệnh này sẽ chỉ biên dịch báo cáo “daily_sitrep.Rmd”, lưu báo cáo HTML, xuất bảng .csv và đường cong dịch bệnh .png vào một thư mục con được đóng dấu ngày và giờ cụ thể cho báo cáo, trong thư mục “outputs” .
Lưu ý rằng nếu bạn chọn cung cấp phần mở rộng .Rmd, bạn phải nhập chính xác phần mở rộng vì nó được lưu trong tên tệp (.rmd so với .Rmd).
Cũng lưu ý rằng khi biên soạn, bạn có thể thấy một số tệp tạm thời xuất hiện trong thư mục “report_sources” - nhưng chúng sẽ sớm biến mất khi chúng được chuyển đến đúng thư mục “output”.
Biên soạn theo số
Bạn cũng có thể chỉ định Rmd script để biên dịch bằng cách cung cấp một số hoặc vectơ số cho reports =
. Các con số phải phù hợp với thứ tự các báo cáo xuất hiện khi bạn chạy list_reports()
.
# Compile the second and fourth Rmds in the "report_sources" folder
compile_reports(reports = c(2, 4))
Biên soạn tất cả
Bạn có thể biên soạn tất cả báo cáo R Markdown trong thư mục “report_sources” bằng cách đặt đối số report =
thành TRUE.
Biên soạn từ thư mục con
Bạn có thể thêm các thư mục con vào thư mục “report_sources”. Để chạy báo cáo R Markdown từ một thư mục con, chỉ cần cung cấp tên của thư mục cho subfolder =
. Dưới đây là ví dụ về code để biên soạn báo cáo Rmd nằm trong thư mục con của “report_sources”.
compile_reports(
reports = "summary_for_partners.Rmd",
subfolder = "for_partners")
Bạn có thể biên soạn tất cả các báo cáo Rmd trong một thư mục con bằng cách cung cấp tên thư mục con cho reports =
, với một dấu gạch chéo ở cuối, như bên dưới.
compile_reports(reports = "for_partners/")
Tham số hóa
Như đã lưu ý trong chương về Reports with R Markdown, bạn có thể chạy báo cáo với các thông số được chỉ định. Bạn có thể chuyển các tham số này dưới dạng danh sách tới compile_reports ()
thông qua đối số params =
. Ví dụ, trong báo cáo hư cấu này, có ba tham số được cung cấp cho báo cáo R Markdown.
compile_reports(
reports = "daily_sitrep.Rmd",
params = list(most_recent_data = TRUE,
region = "NORTHERN",
rates_denominator = 10000),
subfolder = "regional"
)
Dùng “run-file”
Nếu bạn có nhiều báo cáo cần chạy, hãy cân nhắc tạo R script chứa tất cả các lệnh compile_reports()
. Người dùng có thể chỉ cần chạy tất cả các lệnh trong R script này và tất cả các báo cáo sẽ được biên soạn. Bạn có thể lưu “run-file” này vào thư mục “scripts”.
41.5 Kết quả đầu ra
Sau khi chúng ta đã biên soạn các báo cáo một vài lần, thư mục “outputs” có thể trông giống như sau (các điểm nổi bật được thêm vào để rõ ràng):
- Trong “outputs”, các thư mục con đã được tạo cho mỗi báo cáo Rmd
- Trong đó, các thư mục con khác đã được tạo cho mỗi lần biên soạn duy nhất
- Đây là những ngày tháng và thời gian được đóng dấu (“2021-04-23_T11-07-36” có nghĩa là ngày 23 tháng 4 năm 2021 lúc 11:07:36)
- Bạn có thể chỉnh sửa định dạng dấu ngày/giờ. Xem
?compile_reports
- Trong mỗi thư mục ngày/giờ được biên soạn, kết quả báo cáo được lưu trữ (ví dụ: HTML, PDF, Word) cùng với tập lệnh Rmd (kiểm soát phiên bản!) Và bất kỳ tệp nào được xuất khác (ví dụ: table.csv, translate_curve.png)
Đây là chế độ xem bên trong một trong các thư mục được đánh dấu ngày/giờ cho báo cáo “daily_sitrep”. Đường dẫn tệp được đánh dấu bằng màu vàng để nhấn mạnh.
Cuối cùng, bên dưới là ảnh chụp màn hình của kết quả báo cáo HTML.
Bạn có thể sử dụng list_outputs()
để xem lại danh sách các kết quả đầu ra.
41.6 Mục khác
Knit
Bạn vẫn có thể “knit” một trong các báo cáo R Markdown của mình bằng cách nhấn nút “Knit” nếu muốn. Nếu bạn làm điều này, theo mặc định, kết quả đầu ra sẽ xuất hiện trong thư mục lưu Rmd - thư mục “report_sources”. Trong các phiên bản trước của reportfactory, việc có bất kỳ tệp nào không phải Rmd trong “report_sources” sẽ ngăn việc biên dịch, nhưng trường hợp này không còn nữa. Bạn có thể chạy compile_reports()
và không có lỗi nào xảy ra.
Scripts
Chúng tôi khuyến khích bạn sử dụng thư mục “scripts” để lưu trữ “runfiles” hoặc các .R scripts được lấy từ các .R scripts của bạn. Xem trang trên R Markdown để biết các mẹo về cách cấu trúc code của bạn trên một số tệp.
Thêm
Với reportfactory, bạn có thể sử dụng hàm
list_deps()
để liệt kê tất cả các packages được yêu cầu trên tất cả các báo cáo trong toàn bộ nhà máy.Có một package đi kèm trong quá trình phát triển được gọi là rfextras cung cấp nhiều chức năng trợ giúp hơn để hỗ trợ bạn trong việc xây dựng báo cáo, chẳng hạn như:
load_scripts()
- dẫn nguồn/tải tất cả các .R scripts trong một thư mục nhất định (thư mục “scripts” theo mặc định)find_latest()
- tìm phiên bản mới nhất của tệp (ví dụ: tập dữ liệu mới nhất)
41.7 Tài nguyên
Xem Github page của reportfactory package
Xem Github page của rfextras package