User Interface Overview#
After clicking the Get Started button on the welcome page of your RSPM instance, you are taken to an interface that looks like this:
This screenshot has two areas highlighted in orange boxes. On the left, we have the list of repositories. At the top, we have the repository name, followed by three tabs to show the information in the currently selected repository.
Below the top bar, we see the Packages display pane, which allows you to search and explore the package metadata, as well as links to manually download the package source files.
Getting frozen URLs for improving reproducibility#
One of the primary features of RSPM is its "time machine" ability. A user specifies a date, and RSPM provides a collection of software limited to what was available on that date (subject to snapshot availability).
The user interface for picking this date is available on the Setup tab in the top bar.
To get started with a frozen URL, you click one of the boxes around a day in the calendar. The Latest button will become unselected, and the Freeze button will become selected. Observe the URL in the gray box below the calendar. This is a frozen URL. It encodes information about all the sources in this repository, and the snapshot to which RSPM should freeze. You can click the Copy button to the top right of the gray box to copy the displayed URL to your clipboard.
Just below the gray box, you may see text indicating the contents of your repository. RSPM tries to keep the URL as simple as possible, and will use only the date if that's enough. Frequently, RSPM needs to encode more complicated information, so you'll see some random-looking text after the date in the URL. Any of these criteria results in an encoded URL:
- Use of more than one source in a repository.
- Use of a source that does not support date aliases.
- Selecting a date that a date alias can't apply to (a date where a snapshot doesn't exist, and a past snapshot must be referenced instead).
- Selecting the Lock check box, described below.
When you get an encoded URL, RSPM also provides you with information about what the encoded URL contains. For example, this screenshot below shows a URL from a repository that contains two sources, CRAN and bioc-3.12:
You may have noticed that the Bioconductor source does not pin to a date - only to the bioconductor version. You can read more about that in the Bioconductor source details.
Let's return to the Source and Binary buttons. This setup page is also where you can choose between source packages and binary packages. Click the change link to the right of the OS name. You'll see a pop-up dialog that lets you choose your operating system. After selecting your OS, you'll notice that the Binary button is now selected, and the URL in the gray box reflects your OS choice.
There's one further option for configuring your frozen URL. You can further lock the state of the repo by selecting the Lock check box. The default repository snapshot URL uses date aliases where possible. Date aliases refer to source snapshots by their date instead of by their transaction ID. Date aliases are portable across RSPM installations. If your repository contains only sources that support date aliases, then you can use your repository snapshots on different RSPM installations, such as a staging server and production. For projects that require strict reproducibility, we recommend not using date aliases. Date aliases allow metadata version migrations that may happen if the RSPM team needs to fix or improve metadata issues. While these metadata migrations may fix issues, they may also affect behavior that created your environment, resulting in a different set of packages.
For less flexible, but more reproducible snapshots, select the Lock check box. This will use transaction IDs instead of date aliases, and these will not change over time. However, transaction numbers are not portable, so your link will only work on your particular RSPM installation with its particular database history. For reproducibility, sometimes it's better to be wrong but consistent than correct but varying.
Reviewing sync activity#
If you are wondering when your repository last synced with the RSPM service, you can view the Activity tab.
On the left of each row, you can click the arrow to expand and examine which changes occurred in a given snapshot. In the above screenshot, the second row has been expanded this way, and you can see the various actions from that snapshot. If you're wondering why a snapshot hasn't happened yet today, please see the details about RStudio's Package Service.
If your repository subscribes to more than one source, you'll see a drop-down menu, allowing you to select which source to show activity from. Only one source's activity can be shown at a time.