Setting up your dashboard repository

  1. To get started, go to the metricminer-dashboard template GitHub repo
  2. Click the green “Use this template” button in the upper right corner. If you do not see it, make sure you are logged in to GitHub and have an account.
  3. Name your new metricminer dashboard repository on this screen. Then click “Create new repository”.
  4. Create your GitHub secret by going to https://github.com/settings/tokens/new
  5. Make sure your GitHub secret has the repo and workflow scopes checked. Name it something that will remind you it has to do with your metricminer dashboard, scroll to the bottom, and click “Generate Token”. Keep this page open for now.
  6. Return to your metricminer dashboard repository and go to Settings > Secrets and variables > Actions.
  7. Click on New repository secret. Name your new secret exactly GH_PAT. OTTR uses this secret for general website tasks, including checks and rendering.
  8. Copy and paste your personal access token in the Secret box and then click the green “Add secret” button.

Table of Contents generated with DocToc

Setting up your config file

Return to the Code on your metricminer dashboard GitHub repository and find the _config_automation.yml file. Open up that file and we will start setting up which metrics you’d like to retrieve.

Overall settings

metricminer dashboard is an OTTR website with additional metric collecting functionality powered by metricminer. You can read more details about how to update your metricminer/OTTR website here. If you are not familiar with pull requests, we recommend you go read those OTTR docs first.

At the top of the config file you will see a listing of the checks that are run upon filing a pull request. If at any time you don’t want these checks to be run you can set them to no and GitHub Actions will not run them.

# Check that urls in the content are not broken
url-checker: yes
# Render preview of content with changes (Rmd's and md's are checked)
render-preview: yes
# Spell check Rmds and quizzes
spell-check: yes
# Style any R code
style-code: yes

Where your data are saved

By default there are two destinations you can save your data for metricminer, although if you change the code yourself you can save the data wherever you like. Built in to metricminer-dashboard, you have GitHub and Google as your data destination options.

By default your data is saved to GitHub. This is only appropriate for small amounts of data. You could use git-lfs, but we find it can be a bit of a hassle.

### Options are "github" or "google"
data_dest: github
folder_path:

If in your config file you choose “google” as your data destination, you will need to do two things:

  1. Set up your Google Authentication secrets in this repository.
  2. Give a folder path to your Google Drive where you’d like your data to be saved.

Setting up Google Authentication

Your metricminer dashboard will need permissions to Google if you are saving data there, or wanting to use any data from a Google product including Google Analytics, Google Forms, Google Drive, or YouTube.

To set up Google Authentication for your metricminer dashboard, you’ll need to open up R on your local computer and run the following code. If you aren’t a regular R user you can always use posit.cloud to avoid the installation process.

install.packages("metricminer")
library("metricminer")
token <- authorize("google")

Then you can use this object to extract two secrets by printing them out like this and you will need to store both to your metricminer dashboard GitHub secrets.

First, return to your metricminer dashboard repository and go to Settings > Secrets and variables > Actions.

  • Click on New repository secret. Name your new secret exactly METRICMINER_GOOGLE_ACCESS
  • Copy what is printed out in R when you run:
token$credentials$access_token

and paste it into the Secret box and then click the green “Add secret” button.

Repeat the same steps for the refresh token except call this METRICMINER_GOOGLE_REFRESH.

token$credentials$refresh_token

Setting up Calendly

To set up Calendly authorization, go to the Calendly API and webhooks integrations page and click “Generate Token”.

Underneath “Choose a name for this token”, pick a name that will remind you of this project. Click “Create Token” and Calendly will send you an authorization code to your email. After you enter that authorization code, click “Copy Token” and keep this handy.

Then, return to your metricminer dashboard repository and go to Settings > Secrets and variables > Actions.

  • Click on New repository secret. Name your new secret exactly METRICMINER_CALENDLY
  • Paste your token into the Secret box and then click the green “Add secret” button.

Important: metricminer does not remove or redact identifying information that may be included in the data you collect, such as names, email addresses, or Calendly meeting notes. Review your data before sharing or publishing it.

After you’ve set up authorization you’ll need to check the following items in the _config_automation.yml file.

###### Calendly ######
refresh-calendly: yes
calendly_googlesheet:

  • In the _config_automation.yml file, make sure that refresh-calendly is set to “yes”.

  • Optionally, if you are saving data to Google, specify a googlesheet ID in calendly_googlesheet where you’d like the Calendly data to be saved. This will only be relevant if you’ve set data_dest to google.

Setting up Citations

  1. Go to https://scholar.google.com/scholar
  2. Search for the paper you are looking for the citation count.
  3. Click the Cited by ___ button below the title of the paper.
  4. Copy and paste this in the _config_automation.yml file in the citation_papers section.
###### Citations ######
refresh-citations: yes
citation_papers: [
  "https://scholar.google.com/scholar?cites=6140457238337460780",
  "https://scholar.google.com/scholar?cites=15945159957067506879" ]
citation_googlesheet:

  • In the _config_automation.yml file, make sure that refresh-citations is set to “yes”.

  • Optionally, if you are saving data to Google, specify a googlesheet ID in citation_googlesheet if you’d like the citation data to be saved. This will only be relevant if you’ve set data_dest to google.

Setting up CRAN

In the _config_automation.yml file you will need to specify the CRAN packages that you would like metricminer to collect data from.

###### CRAN ######
refresh-cran: yes
cran_packages: [ metricminer, ottrpal ]
cran_googlesheet:

  • In the _config_automation.yml file, make sure that refresh-cran is set to “yes”.

  • In cran_packages, type the names of the packages that you’d like to collect data from on CRAN. Type them exactly as they are spelled, case sensitive, separated by commas. Delete the example package names we’ve put there.

  • Optionally, if you are saving data to Google, specify a googlesheet ID in cran_googlesheet where you’d like the CRAN data to be saved. This will only be relevant if you’ve set data_dest to google.

Setting up GitHub

  1. Create your GitHub secret by going to https://github.com/settings/tokens/new
  2. Make sure your GitHub secret has the repo and workflow scopes checked. Name it something that will remind you it has to do with your metricminer dashboard GitHub data, scroll to the bottom, and click “Generate Token”. Keep this page open for now.
  3. Return to your metricminer dashboard repository and go to Settings > Secrets and variables > Actions.
  4. Click on New repository secret. Name your new secret exactly METRICMINER_GITHUB_PAT.
  5. Copy and paste your personal access token in the Secret box and then click the green “Add secret” button.

This secret will be used by metricminer when collecting data from GitHub repositories.

In the _config_automation.yml file you will need to specify which GitHub repositories you would like metricminer to collect data from.

###### GitHub ######
refresh-github: yes
github_repos: [ fhdsl/metricminer, fhdsl/metricminer.org ]
github_googlesheet:

  • In the _config_automation.yml file, make sure that refresh-github is set to “yes”.

  • In github_repos, specify the names of the repositories you’d like to collect data from. Make sure each one includes the owner/repository, for example fhdsl/metricminer, not just metricminer. Separate repositories with commas. Delete the example repositories we’ve put there.

  • Optionally, if you are saving data to Google, specify a googlesheet ID in github_googlesheet where you’d like the GitHub data to be saved. This will only be relevant if you’ve set data_dest to google.

Setting up Google Analytics

Follow the steps from the Google authentication section and make sure that the account you have authenticated has access to the Google Analytics properties you wish to collect.

You’ll need to collect the Google Analytics property IDs for the websites you want to retrieve data from.

  1. Go to https://analytics.google.com/. You may have to login. These instructions are assuming you have already set up Google Analytics and have been collecting data.
  2. Click on the website at the top of the navbar. It will bring you to a dropdown that shows all your websites.
  3. Click on one of the websites where you’d like to retrieve data from. The URL will look something like this:
https://analytics.google.com/analytics/web/?authuser=1#/p<PROPERTY_ID_HERE>/reports/home

Copy the property ID and put it in the ga_property_ids part of the _config_automation.yml file. Repeat these same steps for all the properties you’d like to collect data for, separating the IDs by commas. Delete the example IDs we have put there as placeholders.

###### Google Analytics ######
refresh-ga: yes
ga_property_ids: [ 422671031, 422558989 ]
ga_googlesheet:

  • In the _config_automation.yml file, make sure that refresh-ga is set to “yes”.

  • In ga_property_ids, specify the Google Analytics property IDs for the websites you’d like to collect data from. Separate property IDs with commas. Delete the example IDs we’ve put there.

  • Optionally, if you are saving data to Google, specify a googlesheet ID in ga_googlesheet where you’d like the Google Analytics data to be saved. This will only be relevant if you’ve set data_dest to google.

Setting up Google Forms

Follow the steps from the Google authentication section and make sure that the account you have authenticated has access to the Google Forms you wish to collect.

Go to a form you’d like to collect data from. The URL should look something like this:

https://docs.google.com/forms/u/1/d/<GOOGLE_FORM_ID_HERE>/edit?usp=drive_web

Extract the Google Form ID from the URL and put it in the google_forms section of the _config_automation.yml file. Do this for each form you’d like to collect data from and separate the form IDs with commas. Delete the example IDs we have put there as placeholders.

###### Google Forms ######
refresh-googleforms: yes
google_forms: [
  1pbFfgUPYH2w9zEoCDjCa4HFOxzEhGOseufw28Xxmd-o,
  1JjmsiuVoGSxvl-1M_oWittcftO955tijzeNc-cgJlo8 ]
googleforms_googlesheet:

  • In the _config_automation.yml file, make sure that refresh-googleforms is set to “yes”.

  • In google_forms, specify the Google Form IDs for the forms you’d like to collect data from. Separate form IDs with commas. Delete the example IDs we’ve put there.

  • Optionally, if you are saving data to Google, specify a googlesheet ID in googleforms_googlesheet where you’d like the Google Forms data to be saved. This will only be relevant if you’ve set data_dest to google.

Setting up Slido

This is assuming you have already exported Slido data to a Google Drive folder. See the Slido export instructions for how to do that.

Navigate to the Google Drive folder that has the Slido data you’d like to collect. Get the URL for this folder. It should look like this:

Important: metricminer does not remove or redact identifying information that may be included in the data you collect, such as names, email addresses, Slido questions, or meeting notes. Review your data before sharing or publishing it.

https://drive.google.com/drive/u/1/folders/<SOME_FOLDER_ID_HERE>

Put the folder ID from this URL in the drive_id category in the _config_automation.yml file.

###### Slido ######
refresh-slido: yes
drive_id: 1XWXHHyj32Uw_UyaUJrqp6S--hHnM0-7l
slido_googlesheet:

  • In the _config_automation.yml file, make sure that refresh-slido is set to “yes”.

  • In drive_id, specify the Google Drive folder ID where your exported Slido data are saved. Delete the example folder ID we’ve put there.

  • Optionally, if you are saving data to Google, specify a googlesheet ID in slido_googlesheet where you’d like the Slido data to be saved. This will only be relevant if you’ve set data_dest to google.

Setting up YouTube

Follow the steps from the Google authentication section and make sure that the account you have authenticated has access to the YouTube videos you wish to collect.

Go to a video you’d like to collect data from. The URL should look something like this:

https://www.youtube.com/watch?v=<YOUTUBE_VIDEO_ID_HERE>

Extract the YouTube Video ID from the URL and put it in the video_ids section of the _config_automation.yml file. Do this for each video you’d like to collect data from and separate the IDs with commas. Delete the example IDs we have put there as placeholders.

###### YouTube ######
refresh-youtube: yes
video_ids: [ XN_QPRrJZAw, YkYnni-WuaQ ]
youtube_googlesheet:

  • In the _config_automation.yml file, make sure that refresh-youtube is set to “yes”.

  • In video_ids, specify the YouTube Video IDs for the videos you’d like to collect data from. Separate video IDs with commas. Delete the example IDs we’ve put there.

  • Optionally, if you are saving data to Google, specify a googlesheet ID in youtube_googlesheet where you’d like the YouTube data to be saved. This will only be relevant if you’ve set data_dest to google.

This work is funded by NCI UE5CA254170 as a part of the ITCR Training Network

See privacy policy