animint2 Reference Website

[ampurr]

Here's the thread that will track the development of the animint2 reference website. 🐈

[ampurr]

@tdhock, sorry—I'm gonna ask you to do something for me. I would do it myself, but I don't have security clearance (or whatever it's called). 😅

Could you go to Settings > Pages and deploy the GitHub Pages site from the reference-website-yay branch? Later on we'll probably start deploying from the main branch and automate things with GitHub Actions (unless you don't want to).

But for now I just wanna set up a preliminary site in your repo instead of my fork. Also, usethis::use_pkgdown_github_pages() doesn't work unless GitHub Pages is set up.

Thanks! As always, no rush. :>

[tdhock]

I did that, does it work for you?

[ampurr]

Thanks! Lemme run the pkgdown stuff and play around. I'll you know as soon as I do plus a delay of perhaps up to several minutes, since instantaneous communication is impossible. :>

[ampurr]

Hmm. When you deployed the site, in

Settings > Pages > Build and deployment > Source,

are you using GitHub Actions or are you deploying from the reference-website-yay branch?

[tdhock]

It says Deploy from a branch, is that ok? Can I give you access some how so you can do this config?

[ampurr]

Yeah, deploy from a branch should be right. Weird that it works from my fork but throws up a GitHub API error (404): Not Found error when I do it from my branch in this repo. I'll figure it out.

Feel free to give me access, and I'll happily return it when the GitHub Pages site is set up. But I'm not sure how to do it. Maybe give me admin powers? I can't find anything about whether admins have power over setting up Pages, though. If you have more modular control, feel free to give me access only to the Pages settings or something. But I haven't been able to find anything about that.

[ampurr]

Yeah, deploy from a branch should be right. Weird that it works from my fork but throws up a GitHub API error (404): Not Found error when I do it from my branch in this repo. I'll figure it out.

Hypothesis: I'm using my personal access token, which maybe probably doesn't work for this repo since it's not mine. I may need you to generate a token for this repo and send it to me.

When I started this project, I had no idea it would require so many tedious little tasks from you, which I apologize for. Do you think I should continue this stuff from my fork instead? Of course, that has other problems and probably increases your future workload in exchange for a reduced workload now. 🤔

[tdhock]

OK thanks for the info. I'm not sure how to give you admin access, because I think github changed their web site since the last time I did that. I don't know if this will help, but I saw a message saying "create an organization to grant access controls" so I created the animint organization, and invited you.

[ampurr]

Thanks! I joined but the animint organization doesn’t seem to have access to any repositories. I don’t know if it’s because the animint2 repo wasn’t added, or if it’s cuz I’m missing some sort of permission. Either way: I don’t get access to the settings for animint2 and therefore can’t control the stuff about pages.

Don’t worry about it, though. If it’s okay with you: I can just do stuff on my fork and at some later date we can have an electron meeting and figure it out this GUI stuff together. And I can just merge my fork into a branch here later, too.

[tdhock]

hi @ampurr and @Faye-yufan I gave you admin access to this repo (recently transferred to animint/animint2 from tdhock/animint2) does that work for you?

[ampurr]

@tdhock: It works! Thank you very much. :>

[Faye-yufan]

Hi @tdhock , yes it works, thank you!

[ampurr]

Status update: I'm currently working on editing README.md, which will serve as the home page for the animint2 reference site, and which @tdhock suggested that I edit during our last meeting. (It is currently a mirror image of README.org.)

If there's anything I should really make sure to include or exclude, please let me know. 🐱

[tdhock]

for sure include screenshots, installation, and basic usage example. anything else you want to delete please move to a wiki page.

[ampurr]

Okay, will do! What do you mean by "anything else you want to delete please move to a wiki page"?

[tdhock]

There is a wiki on this github repo, https://github.com/animint/animint2/wiki and you could move the README section "Differences with Other Packages" to a new wiki page with that name.

[ampurr]

Sorry, I'm still confused. My fault, not yours. But I took some time to think about it and I'm less confused than before.

So I'm going to try and say what I'm doing. And then I'm going to say some possible interpretations of what you're requesting. Then you can let me know if any of the interpretations are correct.

I generated README.md from README.org. I'm editing README.md, which does not affect README.org. My goal is to have the animint2 reference site homepage look different from the GitHub README. GitHub will read from the Org file, while the website will get its homepage from the Markdown file. (I'll rename README.md to index.md to prevent a conflict.)

I'm confused partly cuz I'm not deleting anything from README.org, so it's unclear what the benefit of adding parts of it to the animint2 wiki are.

Some interpretations:

1. You want the Org and Markdown READMEs to be in sync. That's why I need to move some deleted parts to the wiki.
2. The Org and Markdown READMEs cannot be in sync. You want the information present in the Org file but excluded from the Markdown file to be part of the wiki.
3. My status update was unclear, and your request is based on an assumption that I'm unaware of.

EDIT: Interpretation 2 said the READMEs were in sync when they should've said they cannot be in sync. Whoops.

[tdhock]

yes for 1, and actually just delete the org file in your PR please.

[ampurr]

Understood. Will do. Thanks for clarifying. :>

[ampurr]

Today I learned that I do not know how GitHub's milestone thingy works.

[ampurr]

Status update: added the "Differences with other packages" section from README.org to the animint2 repo wiki. I'll be linking that wiki page on the animint2 reference homepage.

No plans to add anything else to the wiki.

[ampurr]

Minor status update: I'm unable to include basic usage examples in the README. Why? GitHub doesn't support JavaScript in its READMEs, and animints are made of sugar and spice and also JavaScript. I'm moving the examples to a vignette and including a link in the Use section.

[ampurr]

Status update: work on the examples vignette is going all right. The biggest difficulty is selecting a built-in dataset that shows off animint2's features. I've tried morley and Theoph, but they're too sparse to display the faceted graphs well. Will probably try msleep next.

[ampurr]

Status update: work on the examples vignette is going all right. The biggest difficulty is selecting a built-in dataset that shows off animint2's features. I've tried morley and Theoph, but they're too sparse to display the faceted graphs well. Will probably try msleep next.

Just simulate the data. You’re demonstrating some package features, not doing science. 😛

[ampurr]

Ah-ha. From the pkgdown reference site: "build_articles() renders each R Markdown file underneath vignettes/ and saves it to articles/." That explains why it's generating the animints in vignettes/.

[ampurr]

Status Update

I've moved the quick start guide to a "Get started" section on the nav-bar.

On a related note, I got the animints working... Is what I wanna say. What actually happened is that renaming the file and moving it to its own section somehow got the animints to work. So it's not accurate to say that I got the animints working.

Why did this work? I can't think of any plausible hypotheses. This is so strange.

[ampurr]

Unrelated: In the animint2 repo, I think this issue has the most comments by far. Possibly the highest word count, too. A graphomanic's paradise and a reader's nightmare. 😅

[ampurr]

Status Update

This workday was CSS-heavy.

I've managed to hack together code annotations in the comments. Except for the hash sign, I think it looks a little bit better than Quarto's solution. Since I had no control over the HTML of the codeblock, I'm pretty proud of my workaround solution. (Maybe I'll be less proud when I wake up. 😛)

Due to certain limitations in CSS's ::marker pseudo-element, getting the writing explaining the code annotations to look like Quarto's solution is harder. Currently it's a WIP.

Quarto's solution is to use <dt> and a CSS grid. I'm trying to get an ordered list to work instead.

Unrelated: I've managed to increased the gap between the animints and the paragraphs following them. Make it easier to read.

[ampurr]

Status Update

Got the CSS for the explanations for the code annotation working. Gonna throw together a PR to see how my commits test and then I'm gonna sleep. 😴

[ampurr]

Status update: I moved website_setup.Rmd to my GSOC subdomain—at some point I realized it wasn't necessary. Replacing it with a shorter document on maintaining the website.

[tdhock]

the progress seems good, but now I get 404 from https://animint.github.io/animint2/articles/quick-start.html did you delete it?

[ampurr]

@tdhock, I moved it to its own space on the navbar. It's here now: https://animint.github.io/animint2/articles/animint2.html

[ampurr]

Status Update

• Finished the website maintenance/debugging internal documentation. It's readme_website.md and can be read here.
• Converted NEWS to NEWS.md and made a couple of minor changes. This lets me put it on the website as the Changelog. If you don't want that, lemme know and I'll revert. :>
  • All headings are now Markdown headings, e.g. # Changes in....
  • All headings have had "version" removed, e.g. "Changes in 2023.6.11" instead of "# Changes in version 2023.6.11."
  • No other changes.

[tdhock]

Hi thanks for sharing. Looks great overall. Glad you could get the line numbering and animint rendering to work. Can you please document the solution to those issues somewhere? (maybe on the wiki?)
Here are a few minor comments/suggestions:

• the plots with geom_smooth seem to be more complicated than necessary. For an intro / quick start, I think it would be better to just stick to the geom_point, first static then animint.
• using the pipe seems more complicated than necessary. Usually pipes are nice and clear when there are several (more than one) different nested function calls, but on that page the examples have max 1 pipe, so I would suggest re-writing the following

cute_present <- cute_1 |> 
  animint(first = list(Cat = c("Archibald", "Muffin")))

as

cute_present <- animint(
  cute_1, 
  first=list(Cat = c("Archibald", "Muffin"))

For the animated plot, there is a warning,

## Warning in issueSelectorWarnings(meta$geoms, meta$selector.aes, meta$duration):
## to ensure that smooth transitions are interpretable, aes(key) should be specifed
## for geoms with showSelected=Day, problem: geom1_point_associations

can you please specify aes(key) ? I think it should be key=Cat, right?

Also can you add a section which adds a second plot with clickSelects? maybe plot some aggregate vs Day, with geom_tallrect(aes(clickSelects=Day)) ?

Also can you please move the data/aes to inside the geom? (this is more consistent with the other tutorials, and more generally useful, since in animints, different layers tend to have different data sets and aes) For example

cute_1 <- meowtrics |>                                    
  ggplot() +                                              
  geom_point() +
  aes(x = Day, y = Cuteness, group = Cat, color = Cat)

could be changed to

cute_1 <- ggplot()+
  geom_point(aes(
    x = Day,
    y = Cuteness,
    group = Cat, 
    color = Cat),
    data = meowtrics)

or, alternatively, if you think the current version has some kind of advantage, can you please show both versions, discuss how they give the same result, and also discuss the relative advantage/disadvantage of each approach/syntax?

Thanks!

[ampurr]

Thanks for the thorough feedback! I'll make the changes and then get back to you. :>

[ampurr]

Changes to the Quick Guide

Refactoring the Code

• Remove all pipes. Toby says they're needlessly complex.
• Move the data and aes inside the geom. Toby says it's for consistency and usefulness in animint2.
• Specify the animint's aes(key) to remove the warning.

Substantial Changes

• Remove the plots with geom_smooth. Toby said it's too complicated for an intro.
• Add a second plot with clickSelects.
• Add more code annotations to help the reader.
• Add alt text to the plots. (This was only possible to do with the static data viz.)
• Edit and clean up the guide.
• Document how I got the code annotations and animint rendering to work.

[ampurr]

As an aside, turns out that while you can't get code annotations in R Markdown, you can get line numbers for codeblocks. I'm proud of my hacky workaround, but maybe line numbers are better? 🤔

[ampurr]

Status Update

I've finished most of the changes. The quick start guide on the website is currently a mess, though.

Currently I'm stuck on the linked animints (with geom_tallrect). Every time I resolve an error another pops up. But I think I've figured it out—I think I need to remove redundant days in meowtrics$Day. I'll test it out when I get up.

[tdhock]

looks like good progress.
one correction "The specific cats must also be in a list" -> actually should be character vector.
right, for the section about clickSelects you probably need to use something like unique(data.frame(Day=meowtrics$Day)) to create a data frame of unique days.

[ampurr]

Thanks for the correction! I'll fix that.

Yup! That did it, thanks.

Still working on the linked animints. Everything seems right, but it produces a static data viz instead of an animint. Still trying to figure that out.

[tdhock]

Still working on the linked animints. Everything seems right, but it produces a static data viz instead of an animint. Still trying to figure that out.

rather than linked animints do you mean linked plots in a single animint? That is what it should be, there is no way to link two different animints. if you share your code, I can help

[ampurr]

Yes, I meant linked plots in a single animint. I assumed that plots and animints had a one-to-one correspondence (cuz I thought "animint" referred to interactive data viz). What exactly is an animint? 😅

Thanks—I really appreciate the offer. 😄 I actually just figured it out. After hours debugging and re-reading and thinking that my code basically looked the same as the code in the manual, I realized that the problem was basically a typo. Whoops.

Now the linked plots work. Thanks again! 🐈

[ampurr]

Status Update

I've finished with the linked plots and fixed the mistake with c(). I'm sure there are typos and awkward bits of writing, so I'm gonna go over the quick start guide again tomorrow.

If there are any other minor changes I should make, please let me know, and I'll make them.

If there are any major changes I should make, also let me know, and I'll make them after GSOC ends. The work product submission deadline is coming up and I wanna dedicate at least most of a day to it.

In other news, pkgdown footnotes apparently rely on a JS library called Popper. Also, they're not working on the website and I can't control how the HTML comes out [1]. I might just replace them with <aside>s [2].

[1] I tried a bunch of things but I'm real tired and don't wanna list them out.
[2] Unlike JavaScript, HTML has never betrayed me. I love you, HTML. 🐈‍⬛

[ampurr]

Status update: I've replaced the Markdown footnotes (which weren't working and relied on an external JS lib) with HTML ones.

[ampurr]

Quick guide status update: I've edited my writing and cleaned up typos.

[tdhock]

Hi again thanks for the updates. things are improving for sure.
the scrolling bug is apparent #92 so you may consider discussing a work around (click Hide Selection Menus Button in animated_associations)
by the way, variable names like animated_associations are preferable to cute_plot_4 (names are easier to understand, numbers in variable names should be avoided) so you you please update the variable names?
also for cute_plot_4 it would be easier to understand if you add

• a geom_text(showSelected="Kind") so that the user can see what Kind is currently selected
• geom_point(color_off="transparent", color="black") or something else to provide greater emphasis about what points are selected (that also offers an opportunity for teaching about color_off)

I would suggest changing the title "Advanced: Linked Plots" by removing the word "Advanced" -- the normal usage of animint is to have at least two linked plots which use clickSelects and showSelected. Using only one plot is typically only in teaching.
Also for that plot it works fine, glad you got it to work. Please consider adding another animint afterwards where you use aligned axes in a single plot, rather than two different plots (y axis is Cuteness). Aligned axes is usually preferable when possible, to (1) save space, (2) avoid repeating legends, and (3) emphasize the common axis. This technique is discussed in https://rcdata.nau.edu/genomic-ml/animint2-manual/Ch02-ggplot2.html#multi-panel

In Conclusion can you please add a link to the Animint2 Manual? Your quick start guide is roughly equivalent to Chapters 2-4, so I would mention something like "You can see another presentation of the same material in more depth in Chapters 2-4 of the Animint2 Manual, https://rcdata.nau.edu/genomic-ml/animint2-manual/Ch02-ggplot2.html#multi-panel"

Thanks again for your great work.

[ampurr]

Sure thing. I'll make those changes and let you know when it's done. :>

Will probably use an <aside> to discuss the bug.

[ampurr]

New checklists:

Changes to the Quick Start Guide

• Write <aside> discussing Firefox bug and the hide selection menus solution.
• Remove variable names with numbers and replace them with words.
• Remove the word "advanced" from "Advanced: Linked Plots."
• Add geom_text(showSelected="Kind") and geom_point(color_off="transparent", color="black") to what is currently cute_plot_4.
• Add a new section where everything is in one plot instead of two. (From Toby: see the manual.)
• Add a link to the animint2 Manual in the conclusion. Mention chapters 2 to 4.
• Document how I got the code annotations and animint rendering to work.

Address Alt Text Redundancy

• Create reproducible example. See here for an example of how to do it.
• Create issue on r-lib/pkgdown. Link reproducible example.

Aesthetic Improvements

• Create an interactive hexagon badge for the Animint2 package.
• Make the <aside> stand out and look aesthetically pleasing.

[ampurr]

Status Update

1. Wrote aside and wrote some CSS to have its background complement the link colors.
2. Added a link to the animint2 Manual in the conclusion.
3. Made other relatively small changes.

[tdhock]

hi @ampurr is this the token you were using to push the gh-pages web site from your own personal computer? or?

I see on your docs https://github.com/animint/animint2/blob/master/readme_website.md#why-dont-you-just-use-github-actions that you did not know how to setup auto deploy in github actions, so I guess that means this token was never necessary for github actions.

[ampurr]

Hey, @tdhock. :>

Yeah, this is the token I used to push the website from my personal computer. People need to renew every year or so, which is kinda annoying. I think the classic token can be permanent. Having never used GitHub Actions, I dunno if this token is necessary for GitHub Actions or not. 😅

It's possible that I might one day figure out auto deploy for this site. But I've still got a few changes I need to make to the site (which you're requested and which I've been terribly slow at addressing). So, no promises on the auto deploy front.

[ampurr]

For Clarity

Well, when I update the website, it does activate a GitHub workflow, which I think is a subset or synonym of a GitHub action. I'm not clear on that, since I've only read a limited subset of the GitHub documentation. If you're using "GitHub action" in the sense that GitHub starts a workflow in the background when I update the site, then this token is necessary for at least some GitHub actions.

I hope my response is relevant to your guess about this token being necessary or unnecessary for GitHub Actions. Sorry if it isn't. 😓