/ / लाइब्रेरी (packagename) 'लोड होने पर पैकेज विगनेट्स के उपयोगकर्ताओं को सतर्क करने के लिए सर्वोत्तम अभ्यास? [बंद] - आर, आर पैकेज, विग्नेट

'पुस्तकालय (packagename)' लोड होने पर पैकेज विग्नेट के उपयोगकर्ताओं को सतर्क करने के लिए सर्वोत्तम अभ्यास? [बंद] - आर, आर पैकेज, विग्नेट

मैं एक आर पैकेज लिख रहा हूं और प्रलेखन विगेट्स पर बहुत समय बिताता हूं। मैं सोच रहा हूं कि मुझे कुछ जोड़ना चाहिए

.onAttach <- function( libname , pkgname ){
packageStartupMessage("use `browseVignettes("packagename")` to see vignettes")
}

जब उपयोगकर्ता कॉल करता है तो तुरंत दिखाई देगा

library(packagename)

पैकेज विगेट्स के बारे में उपयोगकर्ताओं को सूचित करने का सबसे अच्छा तरीका क्या है? या क्या यह अभी माना जाता है कि उपयोगकर्ता स्पष्ट अधिसूचना के बिना उनकी तलाश करेंगे?

उत्तर:

उत्तर № 1 के लिए 6

एक रोजमर्रा आर उपयोगकर्ता की आंखों में विगनेट्स के बारे में ध्यान में रखने के लिए कुछ चीजें ...

  1. सीआरएएन पैकेज पेज पर उपलब्ध है (यदि लेखक के पास है तो यह पैकेज पर एक अच्छी गुणवत्ता जांच है!)
  2. पैकेज बाइनरी में जोड़ा गया और विग्नेट सहायता अनुभाग के माध्यम से दिखाएं browseVignettes(package = "pkgname") [जैसा कि आपने बताया है]
  3. आर पैकेज स्रोत के भीतर एम्बेडेड
  4. एक अलग स्क्रिप्ट डेमो के रूप में विग्नेट में एम्बेडेड कोड का उपयोग करने की संभावना /demos के जरिए demo()
  5. सभी का सबसे महत्वपूर्ण हिस्सा: उपयोगकर्ताओं में से कोई भी वास्तव में के बारे में पता नहीं है विगनेट्स बिलकुल।

इस प्रकार, यदि आप पैकेज दस्तावेज पर काफी समय बिताते हैं, तो आपको शायद चाहिए कम से कम स्टार्टअप पर इंगित करें ऐसी सुविधा मौजूद है।

शोषण packageStartupMessage() अंदर .onAttach() उपयोगकर्ताओं के लिए लाभ।

पैकेज लोड पर, कंसोल अपेक्षाकृत स्पष्ट है और उपयोगकर्ता होगा निश्चित रूप से लाल पाठ देखें क्योंकि विपरीत सामान्य नीला आर पाठ के बीच अपेक्षाकृत अधिक है (मानते हुए नहीं चित्रांकनी)। हालांकि, ऐसे कुछ मामले हैं जहां उपयोगकर्ता को विगेट्स की उपस्थिति के बारे में चेतावनी देने का कोई अर्थ नहीं है।

  1. यदि सत्र गैर-इंटरैक्टिव है (उदा। बैश स्क्रिप्ट)।
  2. यदि उपयोगकर्ता आर "समर्थक" है
  3. यदि उपयोगकर्ता आपके पैकेज का उपयोग लंबे, लंबे, लंबे समय तक कर रहा है जिससे उपयोगकर्ता संदेशों को अवहेलना कर सकता है।

इस प्रकार, एक खराब कार्यान्वित करने के लिए नकारात्मक है packageStartupMessage().

नतीजतन, मैं चार अलग-अलग स्थितियों के तहत स्टार्टअप संदेश पेश करने की अनुशंसा करता हूं।

  1. (सभी) यह देखने के लिए जांचें कि कोई इंसान पूछताछ कर रहा है या नहीं interactive()। यदि ऐसा है, तो आगे बढ़ें:
  2. (मानक) कम से कम 3 अलग स्टार्टअप संदेशों की एक सूची है और प्रदर्शित करने के लिए यादृच्छिक रूप से एक प्रति स्टार्टअप का चयन करें;
  3. (सामान्य) यादृच्छिक रूप से यह निर्धारित करने के लिए संख्या उत्पन्न करें कि कोई स्टार्ट अप संदेश प्रदर्शित होना चाहिए या नहीं;
  4. (प्रो) पैकेज लोड, बाद में गणना करें x जब तक पैकेज पैकेज को पुनर्स्थापित नहीं करता तब तक पैकेज लोड स्टार्टअप संदेश को मार देते हैं।

मैं अगले दो समाधान प्रस्तुत करूंगा जो सादगी के लिए (1) - (3) और फिर केवल (1) और (4) के सिद्धांत का पालन करते हैं।

यादृच्छिक रूप से पैकेज संकेतों का चयन

इस संस्करण के भीतर हम बस जांचना चाहते हैंइंसान, पैकेज लोड संदेश जोड़ने से एक ब्रेक प्रदान करते हैं, और यादृच्छिक रूप से प्रदर्शित करने के लिए एक संकेत चुनते हैं। दायरे के बाहर केवल एक निर्भरता की आवश्यकता है base, द stats::runif [0,1] के बीच संभावना उत्पन्न करने के लिए आदेश।

#" @importFrom stats runif
.onAttach <- function(...) {

# If interactive, hide message
# o.w. check against rng seed.
if (!interactive() || stats::runif(1) > 0.5){
return()
}

# Create a list of helpful tips
pkg_hints = c(
"Check for updates and report bugs at https://cran.r-project.org/web/packages/pkgname/.",
"Use `suppressPackageStartupMessages()` to remove package startup messages.",
"To see the user guides use `browseVignettes("pkgname")`"
)

# Randomly pick one hint
startup_hint = sample(pkg_hints, 1)

# Display hint
packageStartupMessage(paste(strwrap(startup_hint), collapse = "n"))
}

पैकेज लोड की गणना

काउंटर का उपयोग करने के लिए, हम क्षमता का उपयोग करते हैंपैकेज की स्थापना निर्देशिका में सहेजें और "काम करने वाली" निर्देशिका / उपयोगकर्ता स्थान नहीं। इसमें कुछ समस्याएं हैं जिनसे मैं संक्षेप में उल्लेख करूंगा:

  1. उपयोगकर्ताओं को केवल देखने का अधिकार हो सकता है लेकिन संशोधित नहीं किया जा सकता है system पुस्तकालय (उपयोगकर्ता पुस्तकालय ठीक है)।
    • इस प्रकार, वे करेंगे हमेशा इस विधि के तहत पैकेज संकेत प्राप्त करें क्योंकि वे काउंटर को बढ़ा नहीं सकते हैं।
  2. अगर पैकेज में है तो काउंटर साझा किया जा सकता है system पुस्तकालय।
    • यह सभी संकेतों का जल्दी से उपयोग किया जाएगा।
  3. त्रुटि लॉग आकार में वृद्धि हो सकती है।

बेशक, आप उपयोगकर्ता के स्थान के माध्यम से अपना खुद का फ़ोल्डर बना सकते हैं R_USER या HOME पर्यावरण चर इन समस्याओं को अस्वीकार करने के लिए। (पाठक को व्यायाम छोड़ दियासंकेत: प्रयोग करें Sys.getenv() तथा dir.create()।)

भले ही, इस समारोह की सुंदरियों में से एकबाद में आप शायद पैकेज में "पैकेज उपयोग आंकड़े भेजें" फ़ंक्शन शामिल कर सकते हैं। यह वास्तव में एक उचित सटीक - फोन घर - सांख्यिकी बनाम वर्तमान RStudio CRAN दर्पण पैकेज डाउनलोड जानकारी दे देंगे। लेकिन मैं पीछे हटा।

इस विधि के लिए काम करने के लिए, हमें सीआरएएन को दिए गए प्रारंभिक पैकेज पर थोड़ा और अधिक काम करने की ज़रूरत है। विशेष रूप से, हमें शायद काउंटर को पूर्व-सेटअप करना चाहिए:

# Set working directory to package
setwd("package_dir")

# Create the inst directory if it does not exist
if(!dir.exists("inst")){
dir.create("inst")
}

# Create a counter variable
pkg_count = 0

# Save it into a .rda file
save(pkg_count, file="inst/counter.rda")

और अब, पर .onAttach() काउंटर कार्यान्वयन!

.onAttach <- function(...){
if (!interactive()) return()

# Get the install directory location of the counter
path_count = system.file("counter.rda", package = "pkgname")

# Suppress messages by default
displayMsg = FALSE

# Are we able to load the counter?
a = tryCatch(load(path_count), error = function(e){"error"}, warning = function(e){"warning"})

# Set error variable
count_error = a %in% c("error","warning")

# Check if the count is loaded
if(!count_error){

# Check if load count is low...
if(pkg_count < 10){
pkg_count = pkg_count + 1

# Try to save out
try(save(pkg_count, file = path_count), silent=TRUE)
displayMsg = T
}
}

# Display message (can be suppressed with suppressPackageStartupMessages)
if(displayMsg){
packageStartupMessage("use `browseVignettes("packagename")` to see vignettes")
}
}

एक आखिरी विचार

कृपया ध्यान रखें कि यदि आपके पास है कोई पैकेज निर्भरता (उदा। Depend: में DESCRIPTION), उनके पास स्टार्टअप संदेशों का अपना सेट हो सकता है जो प्रदर्शित होंगे से पहले आपके पैकेज में लिखे गए हैं।


जवाब के लिए 6 № 2

मैं विपरीत राय पेश करूंगा (राय हैंStackOverflow पर अनुमति है?) कि स्टार्टअप संदेश विज्ञापन विगनेट्स सहायक नहीं हैं। पैकेजों के लिए व्यापक निर्भरता होने के लिए यह तेजी से आम है, और फिर संदेश संदर्भ से बाहर दिखाई देता है (जब मैं बार संलग्न कर रहा हूं तो मुझे पैकेज फू पर मार्गदर्शन क्यों मिल रहा है?), अन्य पैकेजों के स्टार्टअप संदेशों में दफनाया गया है, इसमें उलझन में है एक चेतावनी या त्रुटि, या प्रक्रिया के अन्य हिस्सों में उत्पन्न संभावित रूप से सूचनात्मक संदेश (उदाहरण के लिए, मुखौटा प्रतीकों के बारे में) overwhelms। इसके अलावा, BioConductor पैकेज विगेट्स बहुत आम हैं और उपयोगकर्ता जल्दी से अपना मूल्य सीखते हैं (गैर-गैर-उपलब्ध अद्भुत विगेट्स में से कुछ का मूल्य भी-BioConductor संकुल), इसलिए उपयोगकर्ता चित्रित किए गए विगेट्स के अस्तित्व और मूल्य से अपरिचित नहीं हो सकते हैं।

कोड की प्रत्येक पंक्ति के लिए अवसर प्रदान करता हैबग, इसलिए विगनेट्स के बारे में सशर्त रूप से प्रदर्शित जानकारी के लिए जटिल कोड लिखना प्रोग्रामर समय का एक मूल्यवान उपयोग नहीं है या निर्बाध उपयोगकर्ता अनुभव के अनुकूल है, खासकर जब पैकेज के उपयोग के लिए कोड का सफल निष्पादन आवश्यक है! @ कोटेलेस "समाधान में और केवल इस बिंदु को स्पष्ट करने के लिए, स्थापित पैकेज स्थान पर लिखने के बारे में चिंता के अलावा, मैं भी उपयोग के बारे में चिंतित होगा T बजाय TRUE, load() / save() बजाय readRDS() / saveRDS(), गैर-विशिष्ट तरीका जिसमें त्रुटियों या चेतावनियों को पकड़ा जाता है लेकिन उपयोगकर्ता को सूचित नहीं किया जाता है, अतिरिक्त पैकेज निर्भरताओं का परिचय stats::runif()), और शायद स्टार्टअप संदेश में मार्कडाउन नोटेशन का उपयोग।

इसके बजाय, विवरण में विग्नेट का वर्णन करें: विवरण फ़ाइल का फ़ील्ड, और व्यक्तिगत सहायता पृष्ठों पर।