Suggestions for the Help Manual

wleoncio commented 3 years ago

0. Setup

I've tested most values below. Not all testings are shown in this report. I only included the testings that are showing errors/warnings or inconsistent results.

set.seed(12334)
n1 <- c(3, 6)
n2 <- c(groups = 4, people = 2)
n3 <- c(school = 3, class = 2, student = 5)
n4 <- c(20, 50)
n5 <- list(school = 3, class = c(2, 1, 3), student = c(20, 20, 10, 30, 30, 30))
n5a <- list(school = 3, class = c(2, 3, 3), student = c(20, 20, 10, 30, 30, 30))
n6 <- list(school = 3, class = c(2, 1, 3), student = ranges(10, 50))
n6a <- list(school = 3, class = c(2, 3, 3), student = ranges(10, 50))
n7 <- list(school = 10, student = ranges(10, 50))
n8 <- list(school = 3, student = c(20, 20, 10))
n8a <- list(school = 3, class = c(2, 2, 2),student = c(20, 20, 10))
n8b <- list(school = 3, class = c(2, 3, 3),student = c(20, 20, 10, 5))
n8c <- list(school = 3, class = c(2, 1, 3),student = c(20, 20, 10))
n9 <- list(school = 10, class = c(2,1,3,1,1,1,2,1,2,1), student = ranges(10, 50))
n10 <- list(country = 2, school = 10, class = c(2,1,3,1,1,1,2,1,2,1), student = ranges(10, 50))
n11 <- list(culture = 2, country = 2, school = 10, class = c(2,1,3,1,1,1,2,1,2,1), student = ranges(10, 50))
n12 <- list(culture = 2, country = 2, district = 3, school = 10, class = c(2,1,3,1,1,1,2,1,2,1), student = ranges(10, 50))
N1 <- c(100, 20)

2. Suggestions for the Help Manual

[x] For function “draw_cluster_structure”, the output with “output=text” is not clearly specified/illustrated compared to “output=tree”.
[x] For function “cluster_gen”, there’re no illustrations on “n_X” and “n_W”. Although they can be referred in function “questionnaire_gen”, it is suggested that they are included in “cluster_gen” or at least referred to those in “questionnaire_gen”.
[x] The illustration of “n_W”(also means, sigmas, levels of data) is not enough for readers to use. It’s better to provide more examples to make it more user-friendly, especially for the list format. / Ask KJ to provide in vignette.
[x] Argument “collapse” can be set as “full” or “partial”, but no corresponding illustration found.
[x] The default number of continuous variables is 3 without specification. However, it should be mentioned in the manual about the default numbers. Same issue for the default mean, variance, and covariance.

wleoncio commented 3 years ago

@mollyolaf, does Hugo have a GitHub username? I'd like to ask him a couple of questions here.

wleoncio commented 3 years ago

@Kondwani84, do you have a vignette addressing this?

The illustration of “n_W”(also means, sigmas, levels of data) is not enough for readers to use. It’s better to provide more examples to make it more user-friendly, especially for the list format. / Ask KJ to provide in vignette.

wleoncio commented 3 years ago

For function “draw_cluster_structure”, the output with “output=text” is not clearly specified/illustrated compared to “output=tree”.

Addressed on f901d78314e1d9e6cdfe99bf818b5eab3dea4e31.

Argument “collapse” can be set as “full” or “partial”, but no corresponding illustration found.

Addressed on 8e10ca61edb8dce3e710bf52ee04e124ebcd7188.

The default number of continuous variables is 3 without specification. However, it should be mentioned in the manual about the default numbers. Same issue for the default mean, variance, and covariance.

Addressed on 2788c3d9dcfa93c4554fe304e3189565085a0e2b (though the default number of continuous variables is randomly generated, not fixed at 3; please provide an example showing otherwise if necessary).

wleoncio commented 3 years ago

The default number of continuous variables is 3 without specification.

I could not reproduce this issue, maybe there's some edge case I'm missing. @Hugo-v587, could you please provide some examples where n_X gets fixed?

Hugo-v587 commented 3 years ago

The default number of continuous variables is 3 without specification.

I could not reproduce this issue, maybe there's some edge case I'm missing. @Hugo-v587, could you please provide some examples where n_X gets fixed?

I re-checked my code and didn't reproduce such issues. From the documentation of _questionnairegen , the _nX means "number of continuous background variables. If not provided, a random number of continuous variables will be generated." I would assume when I tested the functions without specifying the number of continuous variables (_nX) last year, it randomly generated 3 continuous variables for few times, and made me believed that the number of continuous variables was 3 by default. But it's actually totally random and I just got several 3 continuous in a row.

However, when I checked the most recent version of lsasim, I couldn't find the _clustergen function anymore. Did you rearrange the function of _clustergen to other functions?

wleoncio commented 3 years ago

Hi @Hugo-v587, thank you for your reply and the check. Regarding the presence of cluster_gen, it has not been rearranged, please check which version of lsasim you're running with packageVersion("lsasim"). The version we're developing is currently "2.0.2.9007". If the version you have installed is "2.0.2", it means you have the version currently published on CRAN, which doesn't have cluster_gen() yet.

To install the katest development version of the package, you can issue the following command:

remotes::install_github("tmatta/lsasim", "develop")

Please let me know if the issue persists.

wleoncio commented 3 years ago

Hi @Hugo-v587, I was wondering if you've managed to find the cluster_gen function after trying my solution above.

Hugo-v587 commented 3 years ago

Hi @wleoncio , I checked my current version of lsasim, and it's ‘2.0.1.9007’. Then I used the remotes::install_github to install the latest function, now my version is ‘2.0.2.9007’.

However, I got new issues regarding the clustergen. When I typed '?cluster..' R usually auto-complete the function names, however, I received error pop-out as "R code execution error" and got the following error:

Error in fetch(key) : lazy-load database 'C:/Tools/R-3.6.1/library/lsasim/help/lsasim.rdb' is corrupt

However, I can still use cluster_gen to generate data list, but the "summarize_clusters" function is not valid anymore. I got the following error message:

Error in summarize_clusters(data1) : could not find function "summarize_clusters"

Do you remove or change the function of "summarize_clusters"?

When I typed "summ..." R auto-suggest a function of "summary.lsasimcluster" and I assumed this is the newer version of "summarize_clusters"? But I got the same error message pop out as "R code execution error".

I tried summary.lsasimcluster(data1) and the error message is

Error in summary.lsasimcluster(data1) : could not find function "summary.lsasimcluster"

I've tried the example code sent by Leslie yesterday, and still got the same problem for "summarize_clusters" when I tried "Example 7", line 186.

My current R version is 3.6.1.

wleoncio commented 3 years ago

Hi @Hugo-v587, thank you again for reporting.

Error in fetch(key) : lazy-load database 'C:/Tools/R-3.6.1/library/lsasim/help/lsasim.rdb' is corrupt

This error usually occurs when R gets confused about the location of package documentation (often caused by the presence of multiple versions of the same package on a computer). Perhaps if you remove C:/Tools/R-3.6.1/library/lsasim/help/lsasim.rdb and reinstall the package it will get sorted out.

Regarding the old summarize_clusters function, you are correct that it has been replaced by summary.lsasimcluster(). The latter is internal, but you can access it indirectly by calling summary(x) (where x is an object of class "lsasimcluster", i.e. the output of cluster_gen). You can also access it directly with lsasim:::summary.lsasimcluster(), but end users are not supposed to do that and just use the familiar summary() generic function. For more information, please see issue #23 (closed in January).

Leslie's example code should therefore have all instances of summarize_clusters replaced by summary.

mollyolaf commented 3 years ago

Hi Waldir,

Thanks for the heads up about summary(). Do you have some idea of the places this needs to be changed? I assume vignettes, but do you know if there are others?

Thanks! Leslie

On Mon, May 3, 2021 at 1:48 AM Waldir Leoncio @.***> wrote:

Hi @Hugo-v587 https://github.com/Hugo-v587, thank you again for reporting.

Error in fetch(key) : lazy-load database 'C:/Tools/R-3.6.1/library/lsasim/help/lsasim.rdb' is corrupt

This error usually occurs when R gets confused about the location of package documentation (often caused by the presence of multiple versions of the same package on a computer). Perhaps if you remove C:/Tools/R-3.6.1/library/lsasim/help/lsasim.rdb and reinstall the package it will get sorted out.

Regarding the old summarize_clusters function, you are correct that it has been replaced by summary.lsasimcluster(). The latter is internal, but you can access it indirectly by calling summary(x) (where x is an object of class "lsasimcluster", i.e. the output of cluster_gen). You can also access it directly with lsasim:::summary.lsasimcluster(), but end users are not supposed to do that and just use the familiar summary() generic function. For more information, please see issue #23 https://github.com/tmatta/lsasim/issues/23 (closed in January).

Leslie's example code should therefore have all instances of summarize_clusters replaced by summary.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/tmatta/lsasim/issues/12#issuecomment-831035149, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACSQOEESQSKKGFLPBDY7T73TLY2KZANCNFSM4SEZKU4Q .

wleoncio commented 3 years ago

Hi Leslie,

Thanks for the reminder! I forgot to do a package-wide search for those terms. It turns out there were some references to the old function names in the documentation, but I just fixed that on lsasim 2.0.2.9009.

Best, Waldir

Hugo-v587 commented 3 years ago

Hi Waldir, I deleted the C:/Tools/R-3.6.1/library/lsasim/help/lsasim.rdb and now the auto-complete function seems to be OK now.

I tried example 6 set.seed(4388) n <- c(cnt = 1, sch = 2, stu = 5) cg <- cluster_gen(n = n, n_X = 10, c_mean = c(0.3, 0.4, 0.5, 0.6, 0.7))

Then I tried summary(cg) And got the following warning messages

It seems like all three warning messages are the same. What does the error message mean? Does each message indicate an individual warning for each stage? Maybe we could make it more clear to help users understand where they get these warnings (differently)

wleoncio commented 3 years ago

That's great news, @Hugo-v587. Regarding your warning, I've opened a new issue (#43) to treat it, since it's a separate thing. Should we consider this issue here ("Suggestions for the Help Manual") solved?

Hugo-v587 commented 3 years ago

I read the Help Manual and it looked great! I think we could consider this issue as solved.

wleoncio commented 3 years ago

Fantastic, thank you!

tmatta / lsasim

Suggestions for the Help Manual #12

0. Setup

2. Suggestions for the Help Manual