16  변수 설정 문서

변수 설정 문서는 parameterized report를 저자가 번역한 것으로 R/파이썬 프로그램을 작성할 때 입력값을 달리 받는 함수를 생각하면 이해하기 쉽다. 함수는 입력값에 따라 다른 결과를 출력하는데 변수 설정 문서도 입력값을 달리하면 다른 PDF/HTML/워드 문서가 제작되는 것으로 생각하면 된다.

변수 설정 문서는 데이터 분석과 보고서 작성에서 매우 유용하다. 하나의 보고서 템플릿으로 다양한 데이터셋에 대해 개별 보고서를 생성할 수 있어 중복 작업을 크게 줄일 수 있고, 동일한 코드와 템플릿을 사용하기 때문에 보고서 간 일관성이 유지되고 오류의 가능성도 줄일 수 있다.

특히, 맞춤형 보고가 필요한 경우에 유용하다. 예를 들어, 기업에서 각 지점별 월별 매출 보고서를 생성할 때 지점별 데이터만 바꿔가며 각 지점에 맞는 맞춤형 보고서를 쉽게 제작할 수 있다. 이런 방식은 의료 데이터 분석, 학술 연구, 정부 및 공공기관 데이터 보고, 마케팅 분석 등 다양한 분야에서 활용될 수 있다.

변수 설정 문서는 한번 설정해두면 새로운 데이터가 들어올 때마다, 자동으로 보고서를 업데이트하거나 동일한 보고서를 HTML, PDF, 워드 등 다양한 형식으로 쉽게 변환할 수 있다는 점에서 확장성도 뛰어나다.

16.1 문서 프로그래밍

일반적인 보고서 작성을 위한 작업흐름과 필요한 요소는 다음과 같다. 데이터 기반 보고서를 작성할 때 데이터와 데이터를 처리하는데 필요한 R/파이썬/SAS/SPSS/파이썬 스크립트, 마크다운으로 작성한 문서가 포함된다. 즉, 데이터를 데이터베이스, 웹, 파일형태로 가져오면 R 스크립트를 통해 전처리를 하고 필요한 통계량을 뽑아내고 시각적으로 히스토그램, 막대그래프, 원그래프, 시계열 추세 선 그래프 등이 포함된다. 그리고, 데이터에서 나온 다양한 통계량 및 시각적 산출물에 대한 견해와 함께 최종 보고서 작성자의 의견을 덧붙여 마무리하고 보고서 작성자, 참고문헌, 목차, 각주 등을 붙여 보고서를 완성한다.

GUI가 아닌 CLI 방식으로 데이터를 분석한 후, 분석 결과를 .R, .py 파일로 저장한다. 코드와 문서가 결합된 .qmd 파일로 작성하여 컴퓨터 자동화를 통해 원하는 형태 문서인 .pdf, .html, .docx 파일을 생성한다. 생성된 문서들은 웹용, PC 기반 배포 문서, 추가 저작이 가능한 문서 형태로 배포한다.

그림 16.1: 문학적 프로그래밍(Knuth 1984) 구성요소와 작업흐름

16.2 보고서 자동 생성

하루일과는 아침에 일어나서 밥을 먹고, 학교나 회사에 출근하고, 점심먹고, 오후에 놀거나 추가 작업을 하고, 퇴근을 하고 저녁을 먹고, 쉬고 잠을 자는 과정이 일반적인 일상이다. 이런 과정이 매일 매일 반복된다. 마찬가지로 보고서도 이런 일상적인 과정을 담아내야 한다. 즉, 일별로 생성되는 데이터를 동일한 형태의 보고서로 작성하게 된다. 이를 위해 상기 “일반적인 보고서 작성 흐름”을 복사해서 붙여넣기 신공을 발휘하기 보다는 데이터를 바꿔넣고 해당 데이터를 매개변수(parameter)로 넘겨 일별 보고서 생성을 자동화시킨다.

따라서, 일자 정보를 .qmd 파일에 전달하는 과정을 거치는 것이 필요하고, 통계보고서를 자동생성시키는 과정을 별도 스크립트로 만들어서 실행시킨다.

그림 16.2: 일별 보고서 자동생성

16.3 작업방법

변수 설정 문서는 프로그래밍 함수의 개념을 문서 생성에 확장한 것으로 문서 제작자는 단 하나의 템플릿을 이용해 입력값을 달리하여 맞춤형 문서를 생성할 수 있다. 먼저, ‘보고서.qmd’라는 쿼토 보고서 문서를 하나 생성해야 한다. 이는 마치 R/파이썬에서 스크립트를 작성하는 것과 유사하다. 다음 단계로 R/파이썬 함수를 만드는 과정이 필요한데 YAML 헤더에 인자를 params으로 설정한다. 인자는 하나일 필요는 없고 여러 개일 수도 있다. 템플릿.qmd 파일에 ’params’ 옵션을 사용해 ‘province’ 변수 값을 ’서울특별시’와 같이 지정하면, 해당 지역에 맞는 내용을 담은 문서를 생성할 수 있다. 템플릿과 데이터, 스크립트를 조합하여 최종 PDF, HTML, DOCX 형태 최종 문서를 생성할 수 있다. 이런 식으로 변수 설정 문서는 하나의 템플릿에서 시작해 다수의 맞춤형 문서를 효율적으로 생성할 수 있는 방법을 제공한다.

그림 16.3: 매개변수 문서 제작과정

변수설정 보고서 실제 사례로 제19대 대통령선거에서 시도별 특성을 반영한 개별 보고서를 PDF로 작성하는 과정을 살펴보자.

16.3.1 기본 보고서

report.qmd 보고서 파일은 PDF 파일을 제작하기 위해 YAML 헤더 .qmd 파일에 latex-engine: xelatex으로 xelatex을 설정하고 로컬 컴퓨터에 설치된 CJKmainfont: NanumGothic을 통해 NanumGothic 글꼴을 지정했다.

---
title: "대통령 선거 득표 보고서"
subtitle: "경기도 "
author:
    name: 이광춘
    affilates: 한국 R 사용자회
date: "`r Sys.Date()`"
format:
  pdf:
    latex-engine: xelatex   
    keep-tex: false          
CJKmainfont: NanumGothic

report.qmd 파일을 쿼토로 컴파일하게 되면 report.pdf이 생성된다.

그림 16.4: 쿼토 기본 PDF 보고서

16.4 매개변수 보고서

report_template.qmd 파일은 report.qmd 파일을 템플릿으로 사용하여 params 옵션을 사용해 province 변수 값을 서울특별시로 지정해서 매개변수를 보고서에 적용했다. 주목해서 살펴볼 점은 subtitle: 부분에 r params$province으로 변수값 중 province를 지정했다는 점이다. province 변수 값을 서울특별시 대신 다른 시도로 변경하면 변경된 값이 그대로 적용된다.

---
title: "대통령 선거 득표 보고서"
subtitle: "`r params$province`"
author:
    name: 이광춘
    affilates: 한국 R 사용자회
date: "`r Sys.Date()`"
format:
  pdf:
    latex-engine: xelatex   
    keep-tex: false          
CJKmainfont: NanumGothic
params:
  province: "서울특별시"

한걸음 더 나아가 r params$province 변수값을 마크다운 뿐만 아니라 R 코드에도 적용한다는 점이다. params$province를 변수로 필요한 곳(마크다운, R/파이썬 코드)에 적용시킴으로써 유연한 보고서를 복사하여 붙여넣기 대신하여 자유자재로 생성할 수 있다.

---

# 대선 득표 데이터 {#election-dataset}

엑셀로 정리된 제19대 대통령선거 데이터 중 `r params$province` 데이터만 가져와서  시각화와 표제작을 위한 적절한 형태로 정제 작업을 거친다.

16.5 보고서 자동 생성

시도별 PDF 보고서를 달리하여 생성하기 위해서는 데이터와 스크립트가 필요한데 본 보고서의 경우 데이터가 복잡하지 않고 단순히 시도명만 필요하기 때문에 제19대 대통령 선거 결과 데이터에서 시도명을 추출하여 벡터로 만든 후에 이를 quarto 패키지 quarto::quarto_render 함수에 전달한다. for 반복문을 돌리면서 시도명을 쿼토 report_template.qmd 보고서에 전달하여 완성된 .qmd 파일을 생성한 후 PDF 파일을 제작하는 과정을 전체 시도에 대해서 반복한다.

# 0. 환경설정 ---------------------------------------
library(tidyverse)
library(quarto)

# 1. 시도명 ---------------------------------------
provinces <- c("강원도", "경기도", "경상남도", "경상북도", "광주광역시", 
               "대구광역시", "대전광역시", "부산광역시", "서울특별시", 
               "세종특별자치시", "울산광역시", "인천광역시", "전라남도", 
               "전라북도", "제주특별자치도", "충청남도", "충청북도")

# 2. 보고서 만들기 ---------------------------------------
for(province in provinces) {
  quarto_render(input = str_glue("{here::here()}/report_template.qmd"),
                execute_params = list(province = province),
                output_file = str_glue("report_{province}.pdf"))
}

현재기준 quarto quarto_render 함수에 출력 디렉토리를 지정하는 기능은 별도 제공되고 있지 않아 자동으로 생성된 PDF 보고서는 작업 디렉토리 루트에 저장된다. 이것도 자동화하기 위해 move 기능을 추가로 와일드카드가 포함된 정규표현식을 사용하여 코드를 작성하면 된다.

그림 16.5: 시도별 PDF 분석보고서 자동생성결과

연습문제

객관식

  1. 쿼토에서 매개변수를 사용하는 주된 목적은 무엇인가요?
    1. 문서의 속도 향상
    2. 다양한 데이터 소스 관리
    3. 문서 내용의 동적 변경
    4. 보안 강화
  1. 매개변수화 문서에서 사용할 수 있는 입력 유형은 무엇인가요?
    1. 텍스트
    2. 숫자
    3. 날짜
    4. 모두 다
  1. 쿼토에서 매개변수화 기능은 어떤 유형의 파일에 사용할 수 있나요?
    1. 마크다운 파일
    2. HTML 파일
    3. PDF 파일
    4. 위 모두

서술형

  1. 매개변수화 문서 제작 시 고려해야 할 주요 설계 원칙은 무엇인가요?
  1. 쿼토에서 매개변수화 문서를 사용하는 경우의 예시 시나리오는 무엇이 있을까요?