R for Thais

Library กับ package ใน R มีความหมายเช่นเดียวกันนั่นเอง เป็นการนำ function และ/หรือ data มารวมกันเป็นชุด ข้อแนะนำต่อไปนี้เป็นสิ่งที่จำเป็นอย่างน้อยที่สุดในการสร้าง package ให้ทำงานได้ หากต้องการให้ package ทำงานหรือมีคุณสมบัติอย่างอื่นๆ เพิ่มเติมมากกว่านี้ ควรอ่านรายละเอียดในคู่มือ Writing R Extensions

ในบทนี้จะกล่าวถึงเฉพาะการสร้างแฟ้มและโฟลเดอร์ต่างๆ เท่านั้น ส่วนการ build package นั้นจะได้กล่าวในบทต่างหากต่อไป เนื่องจากมีขั้นตอนซับซ้อนพอสมควร และยังจะต้องติดตั้งโปรแกรมที่เกี่ยวข้องอีกมากมาย

ในการสร้าง package หนึ่งๆ นั้น เริ่มจากการสร้างโฟลเดอร์ในชื่อของ package ที่ต้องการ แล้วสร้างโฟลเดอร์ย่อยต่อไปนี้ (เป็นอย่างน้อย) แฟ้มและโฟลเดอร์เหล่านี้ใช้ได้เหมือนกันในการ build package ในทุก platform ไม่ว่าจะเป็น Windows, Unix, หรือ Macintosh ก็ตาม โฟลเดอร์และแฟ้มเหล่านี้ได้แก่

1. R บรรจุแฟ้มของ function ต่างๆ
2. data บรรจุแฟ้มข้อมูลที่เรียกใช้ในตัวอย่าง ไม่จำเป็นต้องมีโฟลเดอร์นี้ก็ได้
3. man บรรจุแฟ้มช่วยเหลือและตัวอย่างการใช้งานสำหรับ function ต่างๆ ใน package

แม้ว่าโฟลเดอร์ย่อย man นี้จะไม่จำเป็น แต่ควรมีไว้ เพื่ออธิบายวิธีการใช้งาน function ต่างๆ เช่น argument ที่สามารถใช้ได้ ลำดับของ argument ข้อจำกัดของ function และอื่นๆ แม้ว่าสิ่งเหล่านี้อาจเขียนเป็นเอกสารคู่มือได้ แต่ผู้ใช้จะสะดวกมากกว่าหากเรียกดูข้อความช่วยเหลือได้ทันทีหากลืมวิธีใช้หรือต้องการดูตัวอย่างวิธีใช้งานจาก R console หรือในสภาพแวดล้อมของการทำงานในขณะนั้น

นอกจากโฟลเดอร์ย่อยทั้งสามแล้ว สิ่งที่จำเป็นมากอีกอย่างหนึ่งคือแฟ้มที่ชื่อ DESCRIPTION แฟ้มนี้ต้องเขียนด้วยอักษรตัวใหญ่ และไม่มีนามสกุลใดๆ ในบางครั้งโปรแกรม editor บางตัวที่ใช้อาจใส่นามสกุลให้โดยอัตโนมัติ ถ้าพบว่ามีการเติมนามสกุลให้เอง ต้องลบออกเสีย

ตัวอย่างเช่น การสร้าง package ชื่อ mypack ให้สร้างโฟลเดอร์ชื่อ mypack ที่บรรจุโฟลเดอร์ย่อยและแฟ้มดังนี้

โฟลเดอร์หลัก	แฟ้มในโฟลเดอร์หลัก	โฟลเดอร์ย่อย	แฟ้มในโฟลเดอร์ย่อย
mypack	DESCRIPTION
		R	mypack.R
		data	FILELIST
			examdata.R
			…
		man	myfun.Rd
			…

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

1. แฟ้ม DESCRIPTION เป็นแฟ้มที่บรรจุคำอธิบาย package นั้น ประกอบด้วยหัวข้อย่อยๆ ดังตัวอย่างแฟ้ม DESCRIPTION ของ package epican ดังนี้

Package: epican
Version: 1.3.3
Date: 2005-05-08
Title: Functions for Epidemiology
Depends: R (>= 2.0.0)
Maintainer: Epidemiology Unit, Prince of Songkla University
Author: Epidemiology Unit Faculty of Medicine and Department of Statistics, Faculty of Science
Description: Common Statistical Functions for Epidemiology
License: GPL version 2 or newer

Package	ชื่อของ package
Version	รุ่นของ package
Date	วันที่พัฒนา package รุ่นนั้น (หากเปิดดูแฟ้มจาก package ที่พร้อมใช้งานใน ../R/library แล้ว จะพบว่าบรรทัดสุดท้ายจะมีวันเวลาอีกครั้งหนึ่ง ส่วนนั้นไม่ต้องเขียน แต่ R จะสร้างให้เองในเวลาที่ build package นั้นให้เองโดยอัตโนมัติ ขั้นตอนนี้จะได้กล่าวต่อไป)
Title	หัวข้อที่จะแสดงเมื่อเรียกใช้งาน เช่นเมื่อเรียกดูข้อความช่วยเหลือ
Depends	รุ่นของ R ที่ package นั้นสามารถใช้งานได้ (เมื่อเปลี่ยนรุ่นของ R อาจมีบาง function ทำงานเปลี่ยนไปจากเดิม หรือยกเลิกไป หรือเพิ่มขึ้นมาใหม่ ทำให้ function ที่เรียกใช้ function เหล่านั้นอีกต่อหนึ่งทำงานไม่ถูกต้องหรือทำงานไม่ได้ไปเลยก็มี)
Maintainer	ผู้ดูแลรับผิดชอบ package
Author	ผู้เขียน package
Description	คำอธิบาย package อย่างสั้นๆ
License	ลักษณะของลิขสิทธิ์ของ package นั้น โดยปกติก็จะเป็น GPL ดังในตัวอย่าง

ไม่จำเป็นต้องระบุุทุกหัวข้อก็ได้

2. โฟลเดอร์ย่อย R เป็นโฟลเดอร์ที่บรรจุแฟ้ม function ต่างๆ ที่ต้องการรวมให้เป็น package เดียวกัน มักเป็นโฟลเดอร์ที่สำคัญที่สุดที่ต้องมีอยู่ใน package โดยทั่วไปหากมี function ไม่มากนัก ก็รวมอยู่ในแฟ้มเดียวกันได้ และมักนิยมตั้งชื่อให้ตรงกับชื่อ package นั้น และมีนามสกุลเป็น .R แต่หากมี function จำนวนมากก็อาจแบ่งเป็นหลายแฟ้มก็ได้ ในขณะ build นั้น R จะรวม function ในแฟ้มต่างๆ เข้าเป็น package เดียวกันให้เอง

ภายในแฟ้มนอกจากจะบรรจุ function แล้ว ยังอาจกำหนดค่าให้ตัวแปร global หรือตัวแปรเฉพาะของ package ด้วยก็ได้ สามารถใส่ comment ต่างๆ ได้เช่นเดียวกับการเขียนชุดคำสั่ง R โดยทั่วไปนั่นเอง

ตัวอย่างเช่น ใน package epican รุ่นก่อนหน้า 1.3.3 มีแฟ้มเพียงแฟ้มเดียวคือ epican.R แต่ในรุ่น 1.3.3 ประกอบด้วยแฟ้มชื่อ data.man.R, data.summ.R, file.man.R, general.R, miscellaneous.R, stat.model.R, และ stat.test.R เป็นการแตกแฟ้มเดิมที่มีขนาดใหญ่ให้เป็นแฟ้มย่อยๆ เป็นกลุ่มๆ ของ function นั่นเอง เนื่องจากในแฟ้มขนาดใหญ่นั้น หากพบข้อผิดพลาดขณะ build package จะหาตำแหน่งที่ผิดพลาดได้ยาก เพราะเป็นไปได้มากว่าตำแหน่งบรรทัดที่ R แจ้งว่ามีข้อผิดพลาดจะไม่ใช่ตำแหน่งที่ผิดพลาดจริง คือเกิดความผิดพลาดมาก่อนหน้านั้นหลายบรรทัดแล้ว แต่ยังตรวจสอบไม่พบ เช่นการปิดวงเล็บปีกกา การตรวจสอบจะบอกไม่ได้ว่าควรปิดที่ตรงไหน แต่จะตรวจพบได้เมื่อพยายามหาวงเล็บปิดแล้วไม่พบ เป็นต้น

ขอให้สังเกตว่าในการตั้งชื่อแฟ้มนั้น เราอาจใส่จุดคั่นชื่อหลายๆ จุดก็ได้ หรืออาจใช้เครื่องหมาย – หรือ _ เพื่อคั่นคำที่มาประกอบกันเป็นชื่อก็ได้

3. โฟลเดอร์ย่อย data เป็นโฟลเดอร์ที่บรรจุแฟ้มข้อมูลที่ใช้ในการแสดงตัวอย่างในแฟ้มช่วยเหลือหรือแฟ้มสาธิต (demo) แฟ้มข้อมูลนี้อาจสร้างได้สองวิธีคือ การสร้างโดยคำสั่ง structure แล้วกำหนด class ให้เป็น “data.frame” ดังตัวอย่างการสร้าง dataset ที่ชื่อ evans ดังนี้

"evans" <- structure(list(
chd = structure(factor(c(rep(1,538),rep(2,71)),
levels=1:2),
.Label=c("no ","yes")),

chl = structure(factor(c(rep(1,447),rep(2,91),rep(1,57),rep(2,14)),
levels=1:2),
.Label=c("low ","high"))),

row.names = paste(1:609),
class = "data.frame")

โดยบรรจุชุดคำสั่งทั้งหมดนี้ในแฟ้มชื่อ evans.R

หรืออาจใช้คำสั่ง read อ่านข้อมูลเข้ามาก็ได้ ดังตัวอย่างคำสั่งในแฟ้มที่ชื่อ ancdata.R มีคำสั่งบรรทัดเดียวคือ

ancdata <- read.delim("ancdata.txt")

กรณีนี้ก็จะต้องมีแฟ้มข้อมูลชื่อ ancdata.txt อยู่ในโฟลเดอร์ data นี้ด้วย

และสุดท้ายควรสร้างแฟ้มที่ชื่อ FILELIST เขียนด้วยอักษรตัวใหญ่ทั้งหมดและไม่มีนามสกุล เพื่อบอกว่าแฟ้มข้อมูลทั้งหมดมีแฟ้มอะไรอยู่บ้าง เช่นใน package epican นั้น ข้อความในแฟ้ม FILELIST มีดังนี้

cca.R
cca9.R
mccdata.R
irdata.R
ahcc.R
ccan.R
ancdata.R
evans.R
vct.R

4. โฟลเดอร์ย่อย man เป็นโฟลเดอร์ที่บรรจุแฟ้มความช่วยเหลือ ที่เขียนในรูปแบบ R document (Rd) ดูรายละเอียดการเขียนแฟ้มชนิดนี้ใน Writing R Extensions และจะนำมากล่าวเป็นหัวข้อต่างหากในบทอื่นต่อไป

จากแฟ้มรูปแบบ Rd นี้ ในขณะ build package แฟ้มช่วยเหลือชนิดอื่นๆ จะถูกสร้างขึ้นมา เช่น ชนิด html, chtml, dvi, และ text ทั้งนี้ขึ้นกับ platform ของคอมพิวเตอร์ที่ใช้ build นั้นเอง ส่วนแฟ้มชนิด pdf ที่อ่านได้ด้วยโปรแกรม Acrobat reader สามารถสร้างได้จากแฟ้ม dvi อีกต่อหนึ่ง

เราสามารถสร้างแฟ้มความช่วยเหลือเป็นภาษาใดก็ได้ (ไทย อังกฤษ หรือภาษาอื่น) แต่หัวข้อจะถูกสร้างเป็นภาษาอังกฤษโดยอัตโนมัติด้วยเงื่อนไขคำสั่งในรูปแบบ Rd นั้นเอง แต่การจัดการกับแฟ้มช่วยเหลือในภาษาอื่นมีรายละเอียดมากพอสมควร จะได้นำมากล่าวเป็นบทต่างหากต่อไป

ดูตัวอย่างแฟ้มความช่วยเหลือสำหรับคำสั่ง clean ดังข้างล่างนี้

\name{clean}
\alias{clean}
\title{Clean R Memory}
\description{
Clean R memory.
}

\usage{
clean()
}

\details{
Remove all objects from R memory.
}

\seealso{
\code{\link{rm}}
}

\examples{
\dontrun{clean()}
}

\keyword{environment}

สนับสนุนโดย สำนักงานกองทุนสนับสนุนการวิจัย (สกว)