R for Thais

หัวข้อนี้จะกล่าวถึงการเขียนแฟ้มความช่วยเหลือในรูปแบบ R document (Rd) ซึ่งเป็นรูปแบบที่แนะนำให้ใช้ในการเขียนแฟ้มความช่วยเหลือสำหรับ function ต่างๆ ใน R เนื่องจากในขณะ build นั้นโปรแกรม R CMD check (บน Linux และ Macintosh) หรือ Rcmd check (บน Windows) จะแปลงให้เป็นรูปแบบมาตรฐานที่ใช้ได้สำหรับทุก platform โดยอัตโนมัติ ได้แก่ รูปแบบ text และ รูปแบบ html ที่อ่านได้ด้วยโปรแกรม web browser เช่น Internet Explorer หรือ FireFox และรูปแบบอื่นที่เหมาะสมกับ platform นั้นๆ เช่น chtml บน Windows หรือรูปแบบ dvi บน Linux

เนื้อหาต่อไปนี้สรุปมาจากคู่มือ Writing R Extensions นั่นเอง แต่ได้สรุปให้ง่ายขึ้น และเพิ่มเติมตัวอย่างให้เห็นการทำงานที่ชัดเจนยิ่งขึ้น ผู้สนใจอาจอ่านรายละเอียดเพิ่มเติมได้ใน Writing R Extensions

การเขียนแฟ้ม Rd จะเขียนในรูปแบบคำสั่ง ไม่ใช่เขียนเป็นข้อความโดยตรง แต่คำสั่งมีไม่มากนัก และมีรูปแบบการเขียนที่แน่นอน จึงสามารถทำความเข้าใจและจดจำได้ไม่ยากนัก คำสั่ง markup พื้นฐานมีดังนี้

ซึ่งลำดับดังที่เห็นจะเป็นลำดับที่เห็นได้ในข้อความช่วยเหลือเมื่อเรียกคำสั่ง help ใน R นั่นเอง ดังนั้นการเขียนแฟ้ม Rd จึงต้องเขียนคำสั่งตามลำดับนี้เสมอ

สังเกตว่าคำสั่งในรูปแบบ Rd จะขึ้นต้นด้วยเครื่องหมาย backslash (\) เสมอ และตามด้วยข้อความที่ต้องการให้นำมาแสดงอยู่ภายในเครื่องหมายวงเล็บปีกกา { } ขณะที่ build นั้น R CMD check จะจัดการกับข้อความภายในนั้นอย่างเหมาะสม เช่นข้อความช่วยเหลือชนิด text ของ pack ใน package epican จะเขียนดังนี้

\name{pack}
\alias{pack}
\title{Pack a Dataset}
\description{
Pack a case-by-case data frame into a compact format with frequencies and means.
}
 
\usage{
pack(data, select, FUN)
}
 
\arguments{
    \item{data}{a data frame.}
    \item{select}{a vector of variable in the data frame by which a compact
dataset is formed.}
    \item{FUN}{a scalar function to compute the summary statistics which can be
applied to all data subsets.}
}
 
\details{
The function packs a case-by-case data frame into a compact one. A list of vector
to be the keys for aggregation of the data must be specified in 'select'. If 'FUN'
is not specified, frequency is assumed and a 'freq' column is added as the last
column in the resulting data frame. If 'FUN' is specified, the function is applied
to all non-factor columns and the results will be displayed for each combination
of 'select' categories.
 
At the moment, mean is the only function that can be specified in 'FUN' as the
example below.
}
 
\value{
A compact data frame containing frequencies or functions defined in 'FUN'.
}
 
\seealso{
\code{\link{aggregate}}
}
 
\examples{
data(cca)
cca1 <- pack(cca,c(ovab,alcohol))
cca2 <- pack(cca,c(ovab,alcohol),FUN=mean)
cca1; cca2
}
 
\keyword{datagen}

ข้อความช่วยเหลือชนิด text ของ pack เมื่อเรียกด้วย function help ใน R จะออกมาเป็นดังนี้

pack                 package:epican                 R Documentation

Pack a Dataset
 
Description:
     Pack a case-by-case data frame into a compact format with
     frequencies and means.
 
Usage:
     pack(data, select, FUN)
 
Arguments:
    data: a data frame.
 
  select: a vector of variable in the data frame by which a compact
          dataset is formed.
 
     FUN: a scalar function to compute the summary statistics which can
          be applied to all data subsets.
 
Details:
     The function packs a case-by-case data frame into a compact one. A
     list of vector to be the keys for aggregation of the data must be
     specified in 'select'. If 'FUN' is not specified, frequency is
     assumed and a 'freq' column is added as the last column in the
     resulting data frame. If 'FUN' is specified, the function is
     applied to all non-factor columns and the results will be
     displayed for each combination of 'select' categories.
 
     At the moment, mean is the only function that can be specified in
     'FUN' as the example below.
 
Value:
     A compact data frame containing frequencies or functions defined
     in 'FUN'.
 
See Also:
     'aggregate'
 
Examples:
     data(cca)
     cca1 <- pack(cca,c(ovab,alcohol))
     cca2 <- pack(cca,c(ovab,alcohol),FUN=mean)
     cca1; cca2

จะเห็นว่าในบางกรณี เช่น \title จะถูกแสดงโดยไม่มีหัวข้อนำหน้า แต่ในกรณีของ \description และ \usage จะถูกแสดงโดยมีหัวข้อ Description: และ Usage: นำ เป็นต้น รายละเอียดในการเขียนแต่ละคำสั่งมีดังต่อไปนี้

ที่น่าสนใจคือเราอาจเขียนแฟ้มความช่วยเหลือเป็นภาษาไทยได้ด้วย ซึ่ง R CMD check จะ build ให้เป็นภาษาไทย แต่อย่างไรก็ตามเนื่องจากในขณะนี้ help window ยังไม่สามารถแสดงเป็นภาษาไทยได้ หากต้องการข้อความช่วยเหลือเป็นภาษาไทย จึงต้องใช้รูปแบบ html หรือ chtml เท่านั้น ตัวอย่างแฟ้มความช่วยเหลือภาษาไทยของ pack เป็นดังนี้

\name{pack}
\alias{pack}
\title{ยุบชุดข้อมูล}
\description{
ยุบชุดข้อมูลแจกแจงรายบุคคลให้เป็นรูปแบบยุบตามความถี่หรือค่าเฉลี่ย
}
 
\usage{
pack(data, select, FUN)
}
 
\arguments{
    \item{data}{กรอบข้อมูล}
    \item{select}{ลิสต์ของเวกเตอร์ที่ต้องการใช้สร้างกรอบข้อมูลที่ยุบแล้ว}
    \item{FUN}{ฟังก์ชันที่จะคำนวณค่าสถิติสรุปของข้อมูลที่ต้องการทำงานกับทุกตัวแปรในกรอบข้อมูล}
}
 
\details{
คำสั่งนี้ยุบกรอบข้อมูลแบบแจกแจงรายบุคคลให้เป็นแบบสรุปย่อ  ระบุลิสต์ของเวกเตอร์ที่จะใช้เป็นตัวแปรหลัก
ในการยุบย่อข้อมูลไว้ใน 'select'  ถ้าไม่ระบุ 'FUN' คำสั่งจะถือว่าต้องการสรุปย่อความถี่ และสดมภ์ชื่อ 
'freq' จะถูกสร้างต่อท้ายกรอบข้อมูลที่สร้างขึ้นใหม่  หากระบุ 'FUN' คำสั่งจะทำฟังก์ชันนี้กับทุกสดมภ์ที่
ไม่ใช่แฟกเตอร์และแสดงค่าสำหรับแต่ละชุดของ 'select' ในกรอบข้อมูลที่สร้างขึ้น
 
ในขณะนี้ mean เป็นฟังก์ชันเดียวที่สามารถใช้ได้กับ 'FUN' ตามตัวอย่างข้างล่าง
}
 
\value{
กรอบข้อมูลในรูปแบบสรุปย่อแสดงความถี่หรือค่าที่ได้จากฟังก์ชันที่ระบุใน 'FUN'
}
 
\seealso{
\code{\link{aggregate}}
}
 
\examples{
data(cca)
cca1 <- pack(cca,c(ovab,alcohol))
cca2 <- pack(cca,c(ovab,alcohol),FUN=mean)
cca1; cca2
}
 
\keyword{datagen}

นั่นคือเป็นการแปลข้อความบางส่วนจากภาษาอังกฤษเป็นภาษาไทยนั่นเอง แต่ด้วยข้อจำกัดของการแสดงภาษาไทยใน help window ของ R หากต้องการเขียนข้อความช่วยเหลือภาษาไทยบน Windows จึงแนะนำวิธีใดวิธีหนึ่งดังนี้ คือ

1. เขียนแฟ้มความช่วยเหลือเป็นภาษาอังกฤษด้วย โดย build แยกกันในแต่ละภาษาแล้ว จึงค่อยนำ help ในรูปแบบ text ที่เป็นภาษาอังกฤษมาแทนที่ภาษาไทย เพื่อให้เวลาเรียก help ตามปกติจะได้ข้อความช่วยเหลือเป็นภาษาอังกฤษ และเมื่อเรียก help ด้วยตัวเลือก html=TRUE จึงแสดงเป็นภาษาไทย
2. แก้ไขแฟ้ม Rprofile ในโฟลเดอร์ R_HOME/etc โดยเอาเครื่องหมาย # หน้า options(htmlhelp=TRUE) หรือ options(chmhelp=TRUE) ออก ซึ่งเป็นการกำหนดตั้งแต่ต้นเริ่มเรียกโปรแกรม R ให้เลือกวิธีแสดงข้อความช่วยเหลือเป็น html หรือ chtml โดยไม่ให้แสดงเป็น text นั่นเอง

ในกรณีของคอมพิวเตอร์ระบบ Macintosh นั้นไม่ต้องเปลี่ยนแปลงอย่างใดทั้งสิ้น เนื่องจากโปรแกรมจะใช้รูปแบบ html เป็นปกติโดยไม่ใช้รูปแบบ text อยู่แล้ว ส่วนบนระบบ Linux นั้น ใช้วิธีการเรียกข้อความช่วยเหลือโดยระบุตัวเลือก html=TRUE (หรือเขียนย่อว่า h=T ก็ได้) เช่น help(pack, h=T)

ต่อไปนี้เป็นรายละเอียดของแต่ละคำสั่ง

\name{name}

name โดยปกติแล้วก็จะเป็นชื่อของแฟ้ม Rd นั้นเอง และเป็นชื่อของวัตถุ ซึ่งในที่นี้คือ function ใน package นั่นเอง วัตถุใน package นั้นจะต้องไม่มีชื่อซ้ำกัน นั่นคือจะต้องไม่ตั้งชื่อวัตถุอื่นใดซ้ำกับชื่อ function ใน package เดียวกัน ดูตัวอย่างในกรณีของคำสั่ง pack ใน package:epican ที่แสดงข้างต้น

\alias{topic}

\alias ระบุทุกๆ หัวข้อที่แฟ้มนั้นให้คำอธิบายอยู่ ข้อมูลนี้จะรวมกันอยู่ในฐานข้อมูล index ในการค้นหาด้วยระบบความช่วยเหลือทั้งในรูปแบบ text และ html

โดยปกติแล้ว \alias มักเป็นชื่อของ function นั้นเองที่ระบุอยู่ใน \name แต่ก็อาจมี \alias หลายๆ อันภายใต้ \name อันเดียวได้ มีบ่อยครั้งที่เราต้องการเขียนคำอธิบายหลายๆ วัตถุใน R ด้วยแฟ้มเดียว ตัวอย่างเช่น แฟ้ม Normal.Rd ใน package:stats ที่อธิบายเกี่ยวกับ density distribution function, quantile function และการสร้างตัวเลขสุ่มตามการกระจายแบบปกติ เริ่มต้นแฟ้มด้วยชุดคำสั่งต่อไปนี้

            \name{Normal}
            \alias{dnorm}
            \alias{pnorm}
            \alias{rnorm}          

นอกจากนี้เราอาจตั้งชื่อ function หนึ่งด้วยหลายชื่อก็ได้ เช่นใน package:epican นั้น to.numeric กับ to.vector ทำงานเช่นเดียวกัน แต่ตั้งชื่อต่างกันเพียงเพื่อสื่อความหมายถึงการเปลี่ยนแปลงที่ต่างกันเล็กน้อย โดยที่ to.numeric สื่อถึงการเปลี่ยนจากตัวอักษรเป็นตัวเลข ขณะที่ to.vector สื่อถึงการเปลี่ยนแฟกเตอร์เป็นเวกเตอร์ ซึ่งทั้งสองกรณีก็ทำงานเช่นเดียวกัน ดังในกรณีนี้ใช้แฟ้มอธิบายร่วมกันเพียงแฟ้มเดียวคือ to.numeric.Rd ซึ่งขึ้นต้นด้วย

            \name{to.numeric}
            \alias{to.numeric}
            \alias{to.vector}
            \alias{to.num}
            \alias{to.vec}

    pack(data, select, FUN)

           pack <- function (data, select, FUN)
           {
            …
           }

           cc <- function (data, case, control, expose, table, 
             a, b, c, d, outcome=get.ec.option("outcome"),
             frame=get.ec.option("frame"))

           cc(table, outcome=get.ec.option("outcome"),
             frame=get.ec.option("frame"))
           cc(data, case, expose, outcome=get.ec.option("outcome"),
             frame=get.ec.option("frame"))
           cc(a, b, c, d, outcome=get.ec.option("outcome"), frame=
             get.ec.option("frame"))

           \synopsis{
           cc <- function (data, case, control, expose, table, 
             a, b, c, d, outcome=get.ec.option("outcome"),
             frame=get.ec.option("frame"))
           }
 
           \usage{
           cc(table, outcome=get.ec.option("outcome"),
             frame=get.ec.option("frame"))
           cc(data, case, expose, outcome=get.ec.option("outcome"),
             frame=get.ec.option("frame"))
           cc(a, b, c, d, outcome=get.ec.option("outcome"), frame=
             get.ec.option("frame"))
           }

           \item{arg_i}{Description of arg_i}

            \note{
              Pie charts are a very bad way of displaying information.
              The eye is good at judging linear measures and bad at
              judging relative areas.
              ...
            }

    x <- runif(10)       # Shown and run.
    \dontrun{plot(x)}    # Only shown.
    \dontshow{log(x)}    # Only run.

Posted by: hutcha sriplung / 23:58