System
DynaMo ForceDecks ForceFrame HumanTrak NordBord SmartSpeed VALD Hub Integrations
Contact us

Search

A guide to using the valdrViz R package

Camille Owen
  • Updated

The valdrViz R package provides you with an easy-to-use visualization tool to turn your raw ForceDecks data into practical insights.

This guide will walk you through creating interactive dashboards, spotting trends, and generating clear reports, all from your R environment.

Before you begin

To use valdrViz R package you must have the base valdr package up and running. This requires valid API credentials provided from VALD support and some setup to install R and RStudio.

Follow our guide to the valdr R package and then return here to explore visualization options.

Getting started

Expand All

Step 1 Install the valdrViz package

You can install the valdrViz package through the RStudio Tools menu or using the R Console.

Option 1 – Tools GUI (Recommended)

  1. Open RStudio Logo.svg RStudio on your computer.
  2. Navigate to Tools > Install Packages.
  3. Ensure 'Install from:' is set to Repository (CRAN).
  4. In the Packages field, enter valdrViz.

R_Install_valdrViz_Package.png

  1. Click Install.

Option 2 – R Console

  1. In the Console, enter the following command and wait for the package to install successfully.
install.packages("valdrViz")

Step 2 Load the valdrViz package

Before you can use the functionality from the valdrViz package, you need to load the package into your R session.

This will tell R that you want to use the valdrViz package in your current session. You can have both valdr and valdrViz active in a single session at the same time.

In the RStudio Console, enter the following command:

library("valdrViz")

Step 3 Launch the dashboard

The valdrViz dashboard runs just like any other R function. Call the following function by typing it into the console.

forcedecks_performance_dashboard()

The dashboard will open, and you will see:

  • A left sidebar for Data import and Filters
  • Tabs across the top: Metric Explorer, Radar Chart, Compare, Quadrant, Player Report

Step 4 Retrieve and load your data

ForceDecks data to be visualized with valdrViz is retrieved from the existing valdr package, which queries and formats your data directly from VALD's External ForceDecks API.

To add your data to the dashboard, you will first need to use the valdr CSV export function to obtain a data file.

Export ForceDecks data to CSV with valdr

The valdr package contains the following function:

export_forcedecks_csv() This CSV export function queries ForceDecks data and writes a file to the /Downloads/VALD_Exports folder – unless another directory is specified.

Note that this function will use the stored start date, usually configured by you when setting up your valdr package.

If you have not run the start_date() command already, you can add it to the export function parameters as shown below.

export_forcedecks_csv(start_date)
Note: Data processing limitation

If the CSV export of ForceDecks data is too large – file size of 250 MB or more – you may experience difficulty loading it to use for visualization.

A possible solution is to adjust the dates of the export in order to process and load your data in smaller chunks.

If you consistently run into issues loading your ForceDecks data, contact the VALD support team.

Load your data

Choose from the two options depending on how many data files you wish to pull from.

Option 1 – File path upload

  1. In Data import, select Folder.
  2. Paste your folder path to the /Downloads/VALD_Exports folder.
  3. Click Load CSVs.

Option 2 – Single file upload

  1. Select Upload.
  2. Select one or more CSV files.*
    * The app combines them into one dataset.

Package features

The package contains a number of ways to visualize your ForceDecks data for various purposes. Read on to find out what you'll see in the visualizations, plus how to read them, and when to use them.

Metric Explorer

View metrics for your group of athletes at a glance

This tab allows you to quickly scan and get an overview of typical values, spreads and outliers.

  1. Choose one or more metrics.
  2. Pick a plot style – Boxplot, Box + Jitter, Violin, Violin + Box, Scatter.
  3. Use the toolbar (zoom, pan, save) to inspect plot details.
valdrViz_Metric_Explorer_1.png
Best for:

→ Answering "What's normal here?" and spotting outliers quickly.

Radar Chart

Build an instant athlete profile across multiple KPIs

This plot places several metrics in a single view so you can compare athletes side-by-side. The chart is scaled 0–100 so different metrics can be compared on the same radar.

  1. Select up to 10 metrics.
  2. Select up to 20 athletes.

Tip: Double-click to reset after zooming/panning.

valdrViz_Radar_Chart_1.png
Best for:

→ Fast athlete profiling and 'strengths versus gaps' conversations.

Compare

Track athlete progress across multiple tests over time

This view shows day-to-day results and a smoothed trend line.

  1. Pick athletes and metrics.
  2. Choose a rolling mean (7d or 14d).
  3. Read your chart:
    • Solid line = best-of-day (daily summary)
    • Dashed line = rolling mean (same athlete, same colour)
      Note: (single data point cases) If an athlete/metric only has one day of data, you’ll see a point (no line). This avoids plot errors.
    • Trend table: Turn it on to see slope, p-value, N, and SpanDays
      If there isn’t enough data, slope/p will show “-” (which is expected)
valdrViz_Compare_1.png
Best for:

→ Comparing athletes, monitoring progress and spotting trend changes early.

Quadrant

Visualize athlete performance patterns by plotting two metrics against one another

This chart helps quickly contextualize performance by showing a comparison across two key metrics. You are also able to generate multiple quadrants side-by-side.

  1. Add or remove quadrants.
  2. Choose aggregation (Latest, Mean over last N days, Best).
  3. Pick X and Y metrics for each plot.
    Dashed lines are the medians (they create the quadrants)

Tip: Toggle Show legend if you want labels under the chart to be visible.

valdrViz_Quadrant_1.png
Best for:

→ Expeditious screening and identification of athlete 'types' or trade-offs.

Player Report

Generate a simple and shareable summary for one athlete

This report combines key trends with several easy-to-read tables, including:

  • Time-series plot(s) – one per metric
  • Recent form table – 14d versus 28d
  • Stability table (CV%, TE)

Designed to be exported to a PDF file.

  1. Select an athlete.
  2. Select one or more metrics.
  3. Review the plots and tables.
  4. Click Download Player Report (PDF).
Best for:

→ Providing a tidy update to a coach or athlete without manual reporting.

 

Comments

0 comments

Please sign in to leave a comment.

Related articles