[Bioc-devel] LazyData in DESCRIPTION file
Martin Morgan
mtmorg@n@b|oc @end|ng |rom gm@||@com
Fri May 1 14:52:35 CEST 2020
One can write arbitrary documentation pages in roxygen2; the page doesn’t have to rely on automatic generation from data objects. For instance filling in the following template would get you (close to) what you want
#' @rdname
#' @name
#' @description
#' @usage
#' @details
#' @return
#' @examples
NULL
But as Kasper says it could well be that there's a better roxygen2 solution (and that it doesn't make sense to choose data storage format based on perceived document tool limitation).
Martin
On 5/1/20, 8:17 AM, "Bioc-devel on behalf of Kasper Daniel Hansen" <bioc-devel-bounces using r-project.org on behalf of kasperdanielhansen using gmail.com> wrote:
Your diagnose sounds reasonable to me. I don't use roxygen2 myself, so I
can't really help here (and this is one of several reasons: it adds another
layer of potential problems to the documentation process). Perhaps someone
who uses roxygen2 can comment? Or perhaps they (roxygen2 developers) have a
GitHub or email list?
Best,
Kasper
On Fri, May 1, 2020 at 5:51 AM Vinh Tran <tran using bio.uni-frankfurt.de> wrote:
> Dear Kasper,
>
> I think the issue was not with the loading data in the examples of the
> functions, but with the Rd documents of the datasets themselves, where it
> says “usage{data_name}” instead of “usage{data(data_name)}”. These Rd
> documents are however automatically created using roxygen2. I still cannot
> find any other solutions yet except using "LazyData: true”.
>
> Best regards,
> Vinh
>
> --------------------------------
> Dr. Vinh Tran
>
> Dept. for Applied Bioinformatics
> Inst. for Cell Biology and Neuroscience
> Goethe University Frankfurt
>
> Biologicum, Room 3.209
> Phone +49 (0)69/798-42118
>
> On 30. Apr 2020, at 16:02, Kasper Daniel Hansen <
> kasperdanielhansen using gmail.com> wrote:
>
> This seems really weird, and I don't think you should be using lazyData to
> get a message to disappear. Is there a GitHub page where we can browse the
> code and do you have the full output of R CMD check somewhere?
>
> On Thu, Apr 30, 2020 at 9:05 AM Vinh Tran <tran using bio.uni-frankfurt.de>
> wrote:
>
>> Dear Kasper,
>>
>> Many thanks for your reply. Yes, I am using data() to load the data.
>> However, the problem is, when I checked my package using CMD Check, it
>> threw me the warning that I am using that data only in the example but not
>> in code. I see the disadvantages of LazyData, but I just want to know in
>> this case, how can I solve that issue by not using LazyData. If you have
>> any solutions, I am very appreciated!
>>
>> Btw, I added “LazyData: true” to the DESCRIPTION and the warning went
>> away. So, I am not sure if it must always be uppercase.
>>
>> Best regards,
>> Vinh
>>
>> --------------------------------
>> Dr. Vinh Tran
>>
>> Dept. for Applied Bioinformatics
>> Inst. for Cell Biology and Neuroscience
>> Goethe University Frankfurt
>>
>> Biologicum, Room 3.209
>> Phone +49 (0)69/798-42118
>>
>> On 30. Apr 2020, at 14:55, Kasper Daniel Hansen <
>> kasperdanielhansen using gmail.com> wrote:
>>
>> If you don't have lazy data on, you should be able to load the data by
>> using data(). Let us say you example data is called expData.
>>
>> With lazy data
>> print(expData)
>>
>> Without lazy data you need explicit loading
>> data(expData)
>> print(expData)
>>
>> For the purpose of examples, there is also a user-level advantage of
>> using an explicit data() statement: the user can see that the data comes
>> from somewhere, instead of appearing out of nowhere. For examples, I
>> actually only see advantages of not using lazyData, because of these
>> explicit statements.
>>
>> My historical impression: I would say that when lazyData was introduced,
>> it seems to me that the intention was widespread use. It seems to me that
>> the tides have turned against lazy data and the official recommendation is
>> to not use it unless you have good reasons. One disadvantage with
>> widespread use of lazyData is that the names of these objects have to be
>> accessible somewhere.
>>
>> Note: one thing I have realized very belatedly is that the lazyData field
>> is a boolean, the right statements are one of
>> lazyData: TRUE
>> lazyData: FALSE
>> For example, I think it has to be all uppercase.
>>
>> Best,
>> Kasper
>>
>> On Wed, Apr 29, 2020 at 6:05 PM Vincent Carey <stvjc using channing.harvard.edu>
>> wrote:
>>
>>> I see this is guideline 7 at
>>> https://bioconductor.org/developers/package-guidelines/
>>>
>>> I have used LazyData: TRUE so that [pkgname]::[entity] can be used
>>> instead
>>> of data(). The
>>> claim that it is "rarely a good thing" and slows down package loading can
>>> be weighed against
>>> convenience. I am not sure you should use LazyData to avoid a
>>> documentation warning
>>> however. Can you give more details on what package is generating the
>>> warning?
>>>
>>> On Wed, Apr 29, 2020 at 5:34 PM Vinh Tran <tran using bio.uni-frankfurt.de>
>>> wrote:
>>>
>>> > Dear Bioc members,
>>> >
>>> > I have just encountered a warning during the CHECK that some data
>>> objects
>>> > are used in the documents but not in code (e.g. “Variables with usage
>>> in
>>> > documentation object ‘ppTree’ but not in code"). They are the demo
>>> data,
>>> > that I am using only in the examples for demonstrate the usage of some
>>> > functions. Adding LazyData: True to the DESCRIPTION can solve that
>>> issue,
>>> > but according to the package guidelines it is not recommended. Could
>>> you
>>> > please show me what should I do in this case? The demo data is only
>>> about
>>> > 15 KB at max.
>>> >
>>> > Many thanks for your advices!
>>> >
>>> > Best regards,
>>> > Vinh
>>> >
>>> > --------------------------------
>>> > Dr. Vinh Tran
>>> >
>>> > Dept. for Applied Bioinformatics
>>> > Inst. for Cell Biology and Neuroscience
>>> > Goethe University Frankfurt
>>> >
>>> > Biologicum, Room 3.209
>>> > Phone +49 (0)69/798-42118
>>> >
>>> >
>>> > [[alternative HTML version deleted]]
>>> >
>>> > _______________________________________________
>>> > Bioc-devel using r-project.org mailing list
>>> > https://stat.ethz.ch/mailman/listinfo/bioc-devel
>>> >
>>>
>>> --
>>> The information in this e-mail is intended only for the ...{{dropped:18}}
>>>
>>> _______________________________________________
>>> Bioc-devel using r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>>>
>>
>>
>> --
>> Best,
>> Kasper
>>
>>
>>
>
> --
> Best,
> Kasper
>
>
>
--
Best,
Kasper
[[alternative HTML version deleted]]
_______________________________________________
Bioc-devel using r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel
More information about the Bioc-devel
mailing list