R for Thais

ในการทำแฟ้มความช่วยเหลือนั้น ดังที่ได้กล่าวไว้ในเรื่องการ build package แล้วว่าจะต้องเขียนในรูปแบบ R document (Rd) การที่จะทำแฟ้มความช่วยเหลือเป็นภาษาไทยก็เช่นเดียวกัน ต้องเริ่มต้นด้วยการสร้างแฟ้มความช่วยเหลือในรูปแบบ Rd นั่นเอง ซึ่งมี tag คำสั่งต่างๆ ดังได้อธิบายไว้ในเรื่อง “การเขียนแฟ้มความช่วยเหลือในรูปแบบ R document” แล้ว

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

tag คำสั่ง \name และ \alias นั้นให้เขียนเป็นภาษาอังกฤษเสมอ เนื่องจากจะเป็นส่วนของชื่อคำสั่งนั้นๆ ที่ R ใช้อ้างอิงและค้นหาคำสั่งในระบบ tag คำสั่ง \title และ \description สามารถเขียนเป็นภาษาไทยได้ ในส่วนของ \usage นั้นจะต้องเขียนเป็นภาษาอังกฤษ เพราะเป็นส่วนที่แสดงวิธีการเรียกใช้ฟังก์ชัน ในส่วนของ \arguments นั้น ในส่วนของชื่อ argument จะต้องเป็นภาษาอังกฤษตามที่ระบุไว้ใน \usage นั่นเอง แต่ในส่วนของคำอธิบายสามารถเขียนเป็นภาษาไทยได้

ส่วน tag คำสั่ง \details, \value, \references, \note, และ \author สามารถเขียนเป็นภาษาไทยได้ตามความเหมาะสม ส่วน tag คำสั่ง \seealso, \examples, และ \keyword จะต้องเขียนเป็นภาษาอังกฤษ ยกเว้นในส่วนของ comment ใน \examples อาจเขียนเป็นภาษาไทยได้

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

ดังได้กล่าวในบท “การสร้าง package ใน R” แล้วนั้น โฟลเดอร์ที่บรรจุแฟ้มความช่วยเหลือในรูปแบบ Rd คือโฟลเดอร์ man นั่นเอง หากจะมีบางกรณีที่ต้องการเรียกความช่วยเหลือในรูปแบบ text ด้วย ให้เขียนแฟ้มความช่วยเหลือเป็นสองโฟลเดอร์ โดยโฟลเดอร์หนึ่งเขียนเป็นภาษาอังกฤษ และอีกโฟลเดอร์หนึ่งเขียนเป็นภาษาไทย ตามคำแนะนำข้างต้น อย่างไรก็ตามเพื่อความสะดวกอาจเขียนเป็นภาษาไทยอย่างเดียวก็ได้ แล้วกำหนดค่าปกติของการเรียกความช่วยเหลือให้เรียกรูปแบบ html หรือ chtml (เฉพาะบน Windows) ซึ่งบนระบบปฏิบัติการ Macintosh นั้นจะไม่มีปัญหาแต่อย่างใด เนื่องจาก R บน Macintosh จะเรียกความช่วยเหลือในรูปแบบ html เสมออยู่แล้ว ส่วนบน Linux นั้นอาจเรียกคำสั่ง help ด้วย option html=TRUE เสมอ และบน Windows นั้น สามารถแก้ไขแฟ้ม Rprofile ในโฟลเดอร์ ../R/rw20xx/etc โดยเอาเครื่องหมาย # หน้าบรรทัด options(chmhelp=TRUE) หรือ options(htmlhelp=TRUE) ออกเสีย ส่วนจะเลือกเอาเครื่องหมายหน้าบรรทัดไหนออกนั้น ก็ขึ้นอยู่กับว่าต้องการให้แสดงความช่วยเหลือเป็นแบบ html หรือ chtml นั่นเอง

ในขั้นตอนของการ build package นั้น ขอแยกกล่าวเป็นสองกรณี คือการ build บน Macintosh บน Linux และการ build บน Windows

บน Macintosh นั้น ถ้าต้องการความช่วยเหลือภาษาไทย ก็สร้างแฟ้มความช่วยเหลือในรูปแบบ Rd เป็นภาษาไทยอย่างเดียวได้เลย แล้ว build package ตามที่อธิบายไว้ในบท “การ build package ใน R” ได้เลย

บน Linux นั้น เนื่องจากการ build เป็นภาระของผู้ใช้เอง ดังนั้นอาจต้องเตรียมแฟ้ม .tar.gz ไว้ทั้งที่มีแฟ้มความช่วยเหลือภาษาไทยและอังกฤษ ให้ผู้ใช้เลือกที่จะ build แบบใดแบบหนึ่งต่อไปนี้ด้วยตัวเอง

หากไม่ต้องการใช้ความช่วยเหลือแบบ text ก็สามารถสร้างแฟ้มความช่วยเหลือรูปแบบ Rd เป็นภาษาไทยอย่างเดียวได้เลย แต่หากเรียกคำสั่ง help โดยไม่ระบุตัวเลือก html=TRUE แล้ว จะได้ข้อความช่วยเหลือเป็น text ที่อ่านไม่รู้เรื่อง เนื่องจากความช่วยเหลือแบบ text นั้นจะแสดงบน terminal console ซึ่งแสดงภาษาไทยไม่ได้

ดังนั้นถ้าต้องการให้ข้อความช่วยเหลือรูปแบบ text ที่อ่านออกเป็นภาษาอังกฤษด้วย ก็จะต้อง build package สองครั้ง โดยครั้งแรกแนะนำให้ build โดยใช้แฟ้ม .tar.gz ที่มีแฟ้มความช่วยเหลือเป็นภาษาไทยก่อน โดยเมื่อขยายแฟ้มออกมาแล้ว ให้ build ด้วยคำสั่ง

R CMD INSTALL package_name

จากนั้นจึงขยายแฟ้ม .tar.gz ที่มีแฟ้มความช่วยเหลือภาษาอังกฤษออกมา แล้ว build ด้วยคำสั่ง

R CMD check package_name

อีกครั้ง คราวนี้จะได้โฟลเดอร์ package_name.Rcheck ขึ้นที่ root (ในการ build package จะต้อง login เป็น root เสมอ) จากนั้นเข้าไปในโฟลเดอร์ package_name.Rcheck/package_name จะเห็นโฟลเดอร์ชื่อ help อยู่ ให้คัดลอกโฟลเดอร์นี้ไปไว้ในโฟลเดอร์ R_HOME/library/package_name ทับโฟลเดอร์ help ที่มีอยู่เดิม โฟลเดอร์ R_HOME อาจแตกต่างกันตามแต่ระบบ Linux ที่ใช้ ทางที่ดีให้ใช้วิธีค้นหาชื่อของ package ในโฟลเดอร์ / (ไม่ใช่ /root) จะเห็นว่าการทำค่อนข้างยุ่งยากพอสมควร

ส่วนบนระบบ Windows นั้น ผู้พัฒนา package จะต้องแจกจ่ายแฟ้ม package ในรูปแบบ zip จึงต้อง build package เสียก่อน นั่นคือผู้พัฒนาสามารถทำแฟ้ม package_name.zip ที่มีโฟลเดอร์ความช่วยเหลือ html และ chtml เป็นภาษาไทย ขณะที่แฟ้มในโฟลเดอร์ help เป็นภาษาอังกฤษได้เลย

ขั้นตอนการ build ให้ build package ด้วยแฟ้มความช่วยเหลือภาษาอังกฤษ โดยใช้คำสั่ง

Rcmd check package_name

ดังที่ได้กล่าวแล้วในบท “การ build package ใน R” ซึ่งจะต้องออกคำสั่งนี้สองครั้งดังได้กล่าวในบทความ เมื่อเสร็จแล้วจะได้โฟลเดอร์ package_name.Rcheck ซึ่งภายในมีโฟลเดอร์ package_name อยู่ ให้ zip โฟลเดอร์นี้เป็น package_name.zip ที่มีแฟ้มความช่วยเหลือเป็นภาษาอังกฤษล้วน พร้อมแจกจ่ายให้กับชาวต่างประเทศได้ จากนั้นเปลี่ยนชื่อโฟลเดอร์ package_name.Rcheck นี้ให้เป็น package_name.Rcheck.en เพื่อให้รู้ว่าเป็นโฟลเดอร์ที่มีแฟ้มความช่วยเหลือเป็นภาษาอังกฤษ

จากนั้น build package ที่มีแฟ้มความช่วยเหลือเป็นภาษาไทย ในการออกคำสั่ง

Rcmd check package_name

ในรอบแรกนั้น ก่อนเรียกใช้โปรแกรม HTML Help Workshop จะต้องแก้ไขข้อความในแฟ้มทุกแฟ้มในโฟลเดอร์ chm ที่คำสั่งได้สร้างขึ้นใหม่เสียก่อน

เมื่อเปิดโฟลเดอร์ chm จะเห็นแฟ้มต่างๆ ที่มีนามสกุลเป็น .html โดยจะต้องมีแฟ้มแรกเป็น 00Index.html เสมอ ส่วนแฟ้มอื่นๆ จะมีชื่อตามแฟ้ม Rd ที่สร้างไว้เดิมนั่นเอง ตามด้วยนามสกุล .html ให้เปิดแฟ้ม 00Index.html ด้วยโปรแกรม text editor ที่มีอยู่ เช่น Notepad หรือ Notepad++ หรือ Crimson Editor หรือโปรแกรมอื่นก็ได้ ไม่ควรเปิดด้วย Word เพราะอาจเผลอบันทึกแฟ้มเป็น .doc ซึ่งจะทำให้การทำงานต่อไปไม่ถูกต้องได้

ในแฟ้ม 00Index.html นั้น สามบรรทัดแรกจะเป็นดังนี้

หมายเหตุ ในข้อความในแฟ้ม html ต่อไปนี้ จะใช้เครื่องหมาย ( ) แทนเครื่องหมาย <> ทั้งนี้เพราะเป็นเครื่องหมายที่จะมีผลต่อการแสดงผลทางเว็บ และไม่สามารถแสดงบนหน้าจอนี้ได้ เมื่อจะนำไปใช้จริงให้เปลี่ยนกลับเป็นเครื่องหมาย <>

ข้อความใน tag (title)…(/title) จะเปลี่ยนไปตามที่ระบุคำอธิบาย package นั้นๆ

ให้แทรกบรรทัดต่อไปนี้เป็นบรรทัดที่สองหรือสามก็ได้

จะได้ดังนี้

ทั้งนี้เพื่อระบุให้การ compile แฟ้มความช่วยเหลือที่เป็น chtml นั้นให้ใช้ภาษาไทยชุดอักษร tis-620 แก้เช่นนี้กับทุกแฟ้มในโฟลเดอร์ chm นี้

จากนั้นเรียกโปรแกรม HTML Help Workshop เพื่อ compile สร้างแฟ้มความช่วยเหลือ chtml แล้ว build package ใหม่อีกครั้ง คราวนี้จะได้โฟลเดอร์ package_name.Rcheck ที่มีแฟ้มความช่วยเหลือเป็นภาษาไทย แต่สามบรรทัดแรกในแฟ้มความช่วยเหลือรูปแบบ html จะกลับไปเป็นเหมือนเดิมอีก และแฟ้มความช่วยเหลือในรูปแบบ text ที่ยังเป็นตัวอักษรไทยที่อ่านใน R console ไม่ได้อยู่

ขั้นตอนต่อไปเป็นการแก้ไขให้แฟ้ม html บังคับให้โปรแกรม browser ใช้ชุดตัวอักษรภาษาไทย tis-620 ทำได้โดยเข้าไปในโฟลเดอร์ html ในโฟลเดอร์ package_name.Rcheck แล้วเปิดทุกแฟ้มมาแก้ส่วน head เช่นเดียวกับที่กล่าวข้างต้นอีกครั้งหนึ่ง เช่นในแฟ้ม 00Index.html จะมีสามบรรทัดแรกเป็น

ก็แทรกบรรทัดเช่นเดิม จะได้ใหม่เป็นดังนี้

หมายเหตุ ขอให้สังเกตว่าบรรทัดที่ 2 นั้นไม่เหมือนเดิมทีเดียว คือจะเรียกแฟ้ม cascade style sheet ที่ต่างกัน

เนื่องจาก R รุ่น 2.0.0 ไม่สามารถแสดงภาษาไทยบน console และความช่วยเหลือที่เป็น text ได้ เมื่อแก้เสร็จแล้ว ให้กลับไปที่โฟลเดอร์ package_name.Rcheck.en ที่ได้สร้างไว้ก่อนแล้ว คัดลอกโฟลเดอร์ help ที่เป็นความช่วยเหลือภาษาอังกฤษนี้มาทับโฟลเดอร์ help ในโฟลเดอร์ package_name ที่อยู่ภายในโฟลเดอร์ package_name.Rcheck ที่เป็นภาษาไทยเสีย เพื่อให้แฟ้มความช่วยเหลือในรูปแบบ text อ่านได้เป็นภาษาอังกฤษ (อาจลบโฟลเดอร์นี้ไปเลยก็ได้ แต่ต้องแจ้งให้ผู้ใช้ทราบว่าในการเรียกความช่วยเหลือสำหรับ package นี้ ต้องเรียกเป็น chtml หรือ html เท่านั้น) แต่สำหรับ R รุ่น 2.1.0 ขึ้นไป สามารถแสดงอักษรภาษาไทยได้อย่างถูกต้อง จึงไม่ต้องเปลี่ยนความช่วยเหลือแบบ text เป็นภาษาอังกฤษ

จากนั้น zip โฟลเดอร์ package_name นั้นดังที่ได้อธิบายไว้ข้างต้น จะได้แฟ้ม package_name.zip ที่มีแฟ้มความช่วยเหลือเป็นภาษาไทยพร้อมแจกจ่ายแก่ผู้ใช้ได้

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

Posted by: hutcha sriplung / 14:23 0 comments

โดยปกติการใช้งาน package ใน R สำหรับคอมพิวเตอร์ Linux และ Macintosh นั้น ผู้ใช้สามารถ install package จาก source file ที่บีบอัดข้อมูลในรูปแบบ tar.gz ได้โดยตรง นั่นคือผู้สร้าง package ไม่ต้อง build ให้ แต่ผู้ใช้เป็นคน build package จาก source file เองได้ แต่การทำงานบน Windows นั้นจะต่างออกไป คือผู้สร้างจะต้อง build ให้ แล้ว zip package นั้นเพื่อให้ผู้ใช้ unzip เอาไปใช้อีกต่อหนึ่ง ทั้งนี้เพราะกระบวนการ build บน Windows นั้นค่อนข้างยุ่งยาก เนื่องจากจะต้องทำงานเลียนแบบการทำงานบน Unix platform (Linux และ Macintosh เป็น Unix อยู่แล้ว จึงทำได้ทันที) ซึ่งจะกล่าวต่อไปในบทนี้

1. เครื่องมือที่ต้องใช้

มี web site ที่สนับสนุนการทำงานนี้โดยเฉพาะ คือ http://www.murdoch-sutherland.com/Rtools/ ซึ่งมีแฟ้มเครื่องมือสำหรับการ build บริการให้ ผู้สนใจอาจเข้าไปศึกษารายละเอียดเพิ่มเติมของการ build package บน Windows ที่ไม่ได้อธิบายไว้ในบทนี้ได้ที่ web site นี้ แต่ในขั้นต้นขอให้ download โปรแกรมเครื่องมือมาก่อนจาก http://www.murdoch-sutherland.com/Rtools/tools.zip จากนั้น unzip แฟ้มนี้ไปใส่ในโฟลเดอร์ ../R/rw20xx/bin

นอกจากแฟ้มเครื่องเหล่านี้แล้ว ยังต้อง download โปรแกรม ActivePerl จาก http://www.activestate.com/Products/ActivePerl/Download.html ซึ่งเป็นโปรแกรมที่มีอยู่เป็นปกติบนเครื่อง Linux และ Macintosh อยู่แล้ว แต่ไม่มีอยู่บน Windows ActivePerl เป็นโปรแกรมที่ใช้ในการแปลคำสั่งแฟ้ม Rd เพื่อสร้างแฟ้มข้อความช่วยเหลือนั่นเอง เมื่อได้มาแล้ว ให้ติดตั้งตามขั้นตอนซึ่งจะใช้เวลาในการติดตั้งนานสักเล็กน้อย จากนั้น restart เครื่องคอมพิวเตอร์ โปรแกรม ActivePerl จะถูกเรียกทำงานอยู่เบื้องหลังทุกครั้งเมื่อเปิดเครื่องคอมพิวเตอร์

จากนั้นต้องตั้งค่าตัวแปร environment ที่ชื่อ TMPDIR ให้เป็นโฟลเดอร์ที่มีอยู่จริง เช่น C:\TEMP หรือ C:\WINDOWS\TEMP (หากยังไม่มีก็สร้างขึ้นใหม่) ทั้งนี้จะเป็นโฟลเดอร์ที่ ActivePerl จะใช้สำหรับใส่แฟ้มชั่วคราวที่สร้างขึ้นระหว่างการทำงานต่างๆ เพื่อจะได้ไม่ไปปะปนอยู่กับ โฟลเดอร์ทำงานตามปกติ สามารถทำได้โดยไปที่ Control Panel แล้วเลือก System กดปุ่ม Advanced ที่ด้านบน แล้วกดปุ่ม Environment Variables (ที่ด้านล่างเหนือปุ่ม OK) เมื่อปรากฏหน้าต่างขึ้น ให้ดูในช่อง System variables ด้านล่าง แล้วเลื่อนลงไปจนพบชื่อ TMPDIR หากพบก็ไม่ต้องทำอะไร แต่หากไม่พบให้กดปุ่ม New จะเกิดหน้าต่างเล็กๆ ขึ้น ช่อง Variable name ให้ใส่ TMPDIR และช่องด้านล่างให้ใส่ C:\TEMP หรือ C:\WINDOWS\TEMP ตามที่สร้างไว้หรือมีอยู่แล้วดังกล่าวข้างต้น

นอกจากนี้ยังมีอีกโปรแกรมหนึ่งที่ต้อง download มาคือ htmlhelp.exe ทั้งนี้เพื่อใช้สร้างแฟ้มช่วยเหลือชนิด chtml นั้นเอง โดย download จาก link ที่ให้ไว้ที่ http://www.murdoch-sutherland.com/Rtools/ หรือ download ได้โดยตรงที่ http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwmicrosofthtmlhelpdownloads.asp หรือที่ http://office.microsoft.com/en-gb/assistance/HA011362801033.aspx ก็ได้ (link เหล่านี้อาจเปลี่ยนแปลงได้ ถ้าไม่สามารถเข้าได้ ให้ตรวจสอบ link ใหม่ที่ web site ของ Murdoch หรือใช้ search engine เช่น google ค้นหา link ใหม่โดยใช้คำหลักว่า htmlhelp.exe) ติดตั้งโปรแกรมตามขั้นตอน

2. วิธี build R package

สร้างโฟลเดอร์ package ตามที่ได้อธิบายไว้แล้วในเรื่อง “การสร้าง package ใน R” หรือตามรายละเอียดที่บรรยายใน “Writing R Extensions” คัดลอกโฟลเดอร์นี้ทั้งหมดไปใส่ในโฟลเดอร์ ../R/rw20xx/bin ซึ่งจะเป็นโฟลเดอร์ทำงานในการ build บนเครื่อง Windows

ในที่นี้ขอแทรกเรื่องการ build package บน Linux และ Macintosh สักเล็กน้อย บน Linux นั้น หากจำ build หรือ install package ใดๆ ต้อง login เป็น root แล้วคัดลอกโฟลเดอร์ที่ต้องการทำงานไปไว้ที่ root home จากนั้นเรียก terminal ขึ้นมา หากต้องการ install คือติดตั้ง package เข้าไปใน R ทำโดยพิมพ์คำสั่งที่ prompt ดังนี้

R CMD INSTALL package_name

การทำงานนี้ใช้เมื่อแน่ใจว่าทุกอย่างที่สร้างขึ้นถูกต้องหมดแล้วทั้งสิ้น แต่ในการพัฒนา package จริงๆ นั้น จะต้องตรวจสอบก่อนว่าทุกอย่างที่เขียนใน package และแฟ้มความช่วยเหลือนั้นสามารถทำงานได้ถูกต้องหรือไม่ ซึ่ง R ได้มีคำสั่งที่ใช้ทดสอบการทำงานไว้ให้แล้ว โดยการใช้คำสั่ง

R CMD check package_name

เมื่อออกคำสั่งนี้ จะเกิดโฟลเดอร์ชื่อ package_name.Rcheck ขึ้น ภายในนั้นจะมีโฟลเดอร์ที่มีชื่อเดียวกับ package นั้นอยู่ หากไม่เกิดปัญหาใดๆ ในการ build เมื่อเข้าไปดูจะเห็นแฟ้มและโฟลเดอร์ย่อยต่างๆ คล้าย package ที่เป็นต้นกำเนิด แต่หากดูให้ลึกถึงข้อความในแฟ้มจะเป็นเปลี่ยนไป และมีแฟ้มเพิ่มขึ้น โดยจะมีแฟ้มชื่อ DESCRIPTION ซึ่งจะมีข้อความต่างไปจากต้นฉบับเดิมเล็กน้อย, CONTENTS, INDEX, และ NAMESPACE ถ้าในโฟลเดอร์เดิมมี NAMESPACE อยู่ด้วย และมีโฟลเดอร์ต่อไปนี้ data, help, html, latex, man, Meta, R, และ R-ex ในที่นี้จะไม่กล่าวถึงสิ่งที่บรรจุในโฟลเดอร์เหล่านี้ แต่โดยสรุปคือเป็นโครงสร้างและข้อมูลที่ใช้ทำงานจริงใน library folder ของ R นั่นเอง (ซึ่งแม้ว่าคำสั่ง R CMD INSTALL จะไม่แสดงแฟ้มและโฟลเดอร์เหล่านี้ให้เห็นที่โฟลเดอร์ root แต่คำสั่งจะติดตั้งแฟ้มและโฟลเดอร์เหล่านี้ลงใน library folder ทำงานของ R ทันที เพราะระบบปฏิบัติการ Linux ไม่ต้องการให้ผู้ใช้เข้าไปจัดการในส่วนนี้ แต่ระบบจะจัดการให้เอง)

บนระบบปฏิบัติการ Macintosh ก็เช่นเดียวกัน ให้คัดลอกโฟลเดอร์ package ไปไว้ที่ root (ชื่อ user ของผู้ใช้ ไม่ใช่ที่ไดเรกตอรีหลักของ hard disk เช่นผู้ใช้ชื่อ user ก็คัดลอกไปที่โฟลเดอร์ชื่อ user ไม่ใช่ที่ hard disk) จากนั้นเรียกโปรแกรม terminal จากโฟลเดอร์ Utilities ในโฟลเดอร์ Application นั่นคือขณะนี้ได้เข้า terminal mode เช่นเดียวกับ Linux แล้ว เมื่อพิมพ์ ls ที่ prompt ใน terminal จะเห็นโฟลเดอร์ package จากนั้นใช้คำสั่งเช่นเดียวกับที่กล่าวมาแล้วข้างต้นบน Linux นั่นเอง

ในการพิมพ์คำสั่งบน Linux หรือ Macintosh ขอให้พิมพ์ตัวพิมพ์เล็กหรือใหญ่ตามที่เขียนไว้ข้างต้นนี้ เพราะบนระบบปฏิบัติการตระกูล Unix นั้น อักษรตัวใหญ่ต่างจากอักษรตัวเล็ก

ที่กล่าวถึงระบบ Linux ก่อนเช่นนี้ก็เนื่องจากการทำงานบน Windows จะทำงานเลียบแบบระบบ Linux นั่นเอง ซึ่งในขั้นแรกจะต้องเข้า DOS mode โดยที่ Start Menu ให้เลือก All Programs --> Accessories --> Command Prompt แล้วเปลี่ยน directory โดยใช้คำสั่ง cd ไปจนถึง ../R/rw20xx/bin ที่ได้คัดลอกโฟลเดอร์ package ไปไว้ก่อนหน้าแล้ว

จากนั้นที่ prompt พิมพ์คำสั่ง

Rcmd check package_name

ซึ่งเป็นการทำงานดังที่ได้กล่าวไว้ข้างต้นเช่นเดียวกับบนระบบ Linux นั่นเอง แต่สังเกตว่า R CMD คราวนี้จะพิมพ์ติดกัน และสามารถพิมพ์ตัวเล็กหรือตัวใหญ่ก็ได้

ในขั้นตอนการ build ด้วย check นั้น จะเกิดโฟลเดอร์ชื่อ package_name.Rcheck เช่นเดียวกับที่กล่าวข้างต้น โดยโฟลเดอร์นี้จะอยู่ที่ ../R/rw20xx/bin นั่นเอง แต่จะพบว่ามีการรายงานความผิดพลาดเกิดขึ้น ในขณะที่คำสั่งได้สร้างโฟลเดอร์ชื่อ chm ในโฟลเดอร์ package อันเก่าที่เป็นต้นฉบับ ในโฟลเดอร์นี้จะเห็นแฟ้มความช่วยเหลือที่มีนามสกุล html และจะมีหนึ่งแฟ้มที่มีชื่อ package_name.hhp

เมื่อถึงขั้นตอนนี้ ให้เปิดโปรแกรม HTML Help Workshop จาก desktop alias หรือจาก Start Menu ก็ได้ แล้วเลือกที่ File --> Open แล้วเปิดแฟ้มที่ชื่อ package_name.hhp นั้น จากนั้นกลับไปที่ File à Compile… เพื่อสร้างแฟ้มความช่วยเหลือที่มีชื่อเป็น package_name.chm ไว้ในโฟลเดอร์ chm นี้ เมื่อเสร็จแล้วปิดโปรแกรม HTML Help Workshop ได้

ทีนี้กลับมา build package อีกครั้งด้วยคำสั่ง

Rcmd check package_name

ถ้าคำสั่งและแฟ้มความช่วยเหลือทั้งหมดถูกต้อง คราวนี้คำสั่งจะ build ทุกอย่างได้โดยไม่มีข้อผิดพลาด และจะมีโฟลเดอร์ย่อยชื่อ chtml เพิ่มขึ้นมาจากการ build บน Linux หรือ Macintosh

ในระหว่างการ build หากมีข้อผิดพลาดอย่างใดเกิดขึ้น ขอให้อ่านข้อความแจ้งความผิดพลาดให้ละเอียด เพื่อกลับไปแก้ไขข้อผิดพลาดนั้น แล้วกลับมา build ใหม่อีกครั้ง แต่อย่าลืมว่าคราวนี้มีโฟลเดอร์ package ถึงสามโฟลเดอร์ คือโฟลเดอร์ดั้งเดิมที่สร้างขึ้นในการพัฒนาคำสั่ง โฟลเดอร์ package ที่คัดลอกมาไว้ที่ /bin และโฟลเดอร์ package ใน package_name.Rcheck ไม่ต้องไปสนใจโฟลเดอร์ package ใน .Rcheck แต่อย่างใด แต่ทุกครั้งที่แก้ไขต้นฉบับคำสั่งหรือแฟ้มความช่วยเหลือ ควรแก้ไขใน /bin และเมื่อทุกอย่างถูกต้องคือ build ผ่านหมดแล้ว ให้สำเนาโฟลเดอร์นี้ทั้งหมดกลับไปไว้ที่เดิมที่พัฒนา package นั้นด้วย มิฉะนั้นจะสับสนในภายหลังได้ เพราะอาจมีบางคำสั่งใน package ต้นฉบับกับที่ build แล้วแตกต่างกันได้ และนอกจากนี้ยังแนะนำให้สำเนาโฟลเดอร์ package_name.Rcheck เก็บไว้ทั้งโฟลเดอร์ อย่าสำเนาเก็บแต่เฉพาะโฟลเดอร์ package ภายในมาเก็บไว้ เพราะอย่างที่บอกแล้วว่าโฟลเดอร์ package ที่สร้างขึ้นใน .Rcheck นั้นไม่เหมือนกับ package ต้นฉบับ อาจทำให้สับสนได้ว่า package ที่ build แล้วนี้เป็นต้นฉบับได้ แล้วไปลบต้นฉบับจริงทิ้งเสีย การฟื้นต้นฉบับทั้งหมดกลับมานั้นทำได้ยากมาก

อีกประการหนึ่ง หากมีการแก้ไขแฟ้มความช่วยเหลือชนิด .Rd ต้องลบโฟลเดอร์ chm ในโฟลเดอร์ package ที่เป็นต้นฉบับใน /bin ด้วยเสมอ ที่จริงแฟ้มที่สำคัญที่สุดในนั้นคือ package_name.chm ซึ่งหากในระหว่างการ build นั้น โปรแกรม Rcmd พบแฟ้มนี้อยู่ในโฟลเดอร์ chm คำสั่งจะข้ามการแก้ไขทั้งแฟ้มชนิด .htm และ .chm ไปเลย ซึ่งจะทำให้ได้แฟ้มความช่วยเหลือเก่าที่ยังไม่ได้แก้ไขแต่อย่างใด ดังนั้น หากมีการแก้ไขแฟ้มความช่วยเหลือชนิด .Rd ให้ลบโฟลเดอร์ chm ทิ้งเสียด้วย และจะต้องเรียกคำสั่งในการ build สองครั้ง และต้องเรียกโปรแกรม HTML Help Workshop ใหม่ทุกครั้ง แม้ว่าจะเป็นการเสียเวลา แต่ถ้าหากไม่ทำ แฟ้มความช่วยเหลือที่ได้จะไม่ถูกต้อง

เมื่อการ build เรียบร้อยแล้ว ให้เข้าไปในโฟลเดอร์ package_name.Rcheck แล้ว zip โฟลเดอร์ package ในนั้นด้วยโปรแกรม winzip หรือ 7-Zip ก็ได้ แล้วแฟ้ม package_name.zip ที่ได้นี้จะเป็นแฟ้มที่สามารถแจกจ่ายให้ผู้ใช้งาน R บนระบบ Windows ได้นั่นเอง (แต่ผู้ใช้บนระบบ Linux และ Macintosh จะใช้งานแฟ้มนี้ไม่ได้)

สำหรับการ build บน Linux และ Macintosh นั้น เมื่อ check ผ่านหมดทุกขั้นตอนดังนี้แล้ว จะต้องเรียกคำสั่งต่อไปนี้ที่ prompt

R CMD build package_name

เป็นการสร้างแฟ้มชื่อ package_name.tar.gz ขึ้นนั่นเอง บน Windows นั้นก็สามารถสร้างแฟ้มนี้ได้โดยออกคำสั่งต่อไปนี้ที่ DOS prompt

Rcmd build package_name

ในการแจกจ่ายแฟ้ม package สำหรับระบบ Linux และ Macintosh นั้น จะแจกจ่ายเป็นแฟ้ม package_name.tar.gz เมื่อผู้ใช้ต้องการจะติดตั้ง ให้ไปที่ terminal แล้วเรียกคำสั่ง R CMD INSTALL เพื่อติดตั้ง

ส่วนบนระบบ Windows ให้แจกจ่าย package เป็นแฟ้ม package_name.zip ผู้ใช้จะติดตั้งโดยเข้า R console ก่อน แล้วเลือกเมนู Packages --> Install package(s) from local zip files…

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

Posted by: hutcha sriplung / 12:11 0 comments

หัวข้อนี้จะกล่าวถึงการเขียนแฟ้มความช่วยเหลือในรูปแบบ 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 0 comments