ZwiftRacing Documentation

  • (1) Introduction
  • (1.1) What is ZwiftRacing?
  • (1.2) Why Use ZwiftRacing?
  • (1.3) What You'll Find in this Documentation
  • (2) vELO: Result-based Race Categorization
  • (2.1) What is vELO?
  • (2.2) vELO Categories
  • (2.3) Determining Your Initial vELO Rating
  • (2.4) zrCS: ZR's Compound Score
  • (2.5) Ineligible Races
  • (2.6) vELO Execution Online
  • (2.7) Uncommon Scenarios
  • (2.8) Terrain Handicaps
  • (3) Ranking Points
  • (3.1) What are Ranking Points?
  • (3.2) Ineligible Races
  • (3.3) Ranking Points Implementation Outline
  • (3.4) Total Ranking Points
  • (4) Race Achievements
  • (4.1) What are Race Achievements?
  • (4.2) Earning Achievements
  • (4.3) Achievement Types
  • (5) Event Processing
  • (5.1) Schedule
  • (5.2) Ineligible Events
  • (5.3) Event Processing Procedure

1. Introduction

1.1 What is ZwiftRacing?

ZwiftRacing is a cutting-edge web application designed for avid cyclists and competitive racing enthusiasts who use Zwift, the popular online cycling platform. With ZwiftRacing (ZR), you can take your virtual cycling experience to the next level by participating in organized races using the first result-based categorization system ever made for indoor cycling.

1.2 Why Use ZwiftRacing?

Race Organization: The vELO rating system (described below) provides the most competitive and compelling racing on the Zwift platform. Users are able to participate in races organized by the Moderators at ZR as well as many other race organizers that independently use the vELO platform for their own races and/or series.

Performance Analytics: Gain valuable insights into your cycling performance with detailed statistics, including power profile bests, phenotype assignment, and race results. Use this data to monitor your progressand set new personal records!

Community Engagement: Connect with a vibrant community of Zwifters who share your passion for racing on the official ZwiftRacing Discord chat server. From there you can do everything from finding a race to proposing a new feature or improvement opportunity.

User-Friendly Interface: ZwiftRacing is designed with user convenience in mind. Whether you're a seasoned Zwifter or new to the platform, you'll find the application intuitive and easy to use.

1.3 What You'll Find in this Documentation

This documentation serves as your comprehensive guide to using ZwiftRacing. It covers everything from getting started with the application to advanced features and troubleshooting. Whether you're a cyclist looking to enhance your racing experience or a race organizer aiming to streamline event management, this documentation has you covered.


2. vELO: Result-based Race Categorization

2.1 What is vELO?

vELO is the result-based categorization system used at ZwiftRacing to classify riders based on their performance and recent racing history. It helps create balanced and competitive races by ensuring that riders of similar skill and fitness levels compete against eachother. It has its origins in the ELO rating system used in chess to rate players but has been heavily-modified to accommodate the complexities of an indoor cycling platform.

The primary goal of the vELO platform is one of categorization rather than reward. Riders who are actively gaining fitness, either through active racing or a separate training regime, may see steady increases in their vELO as a progress indicator towards a fitness goal but any minor undulations that occur shouldn't be seen as discouraging so long as the resultant rating still categorizes the rider in a fun race against peers of similar fitness.

2.2 vELO Categories

Riders at ZwiftRacing are split into ten categories depending on their vELO ratings. There is a Open (mixed gender) ladder and a Women's Only ladder. The two category ladders share the same category names but with a different vELO rating range.

Details on the vELO categories can be found at the vELO Categories reference page.

2.3 Determining Your Initial vELO Rating

When the ZwiftRacing system calculates the results of your first race on the Zwift platform, it will use a modified version of the Compound Score (CS) formula called zrCS and is detailed below. This seed value will be the rating used in the vELO algorithm that runs to determine what change (if any) should occur to that rating as a result of your performance in the race.

2.4 zrCS: ZR's Compound Score

One of the drawbacks to the traditional A-D categories on the Zwift platform is that they are largely based on a rider's performance over 20 minutes relative to their weight (also known as 20m w/kg). The main issue with this approach are the fact that a vast majority of races on Zwift don't challenge your 20m power enough to ensure that riders have a true max effort for categorization. Another drawback is that riders are able to monitor and keep their 20m w/kg efforts low purposefully to maintain a lower category.

The use of Compound Score (CS), which is a measure of 5 minute power rather than 20 minute, does a good job addressing the drawbacks mentioned above. The original formula, however, was developed using a study of U23 professional cyclists (Leo et al. 2022) and didn't produce results that looked or felt 'right' for riders whose weight was either above or below the subjects of the study. Because of this, we developed a modified version of this formula whose results feel a lot more true to how an initial seed in the vELO system ought to operate. Credit for the modified formula goes to many in the Contributors group of the ZR discord but, in particular, Marco (@m.b.zas) and is defined below:

CS (Compound Score) = 5m Watts * 5m Watts per Kilo

zrCS = CS * (65 / (65 - (0.4 * (65 - weight in kg))))

zrCS Calculator

zrCS

1130
2.5 Ineligible Races

The vELO algorithm runs against the results of nearly every race held on the Zwift platform. There are some cases, however, where vELO does not run and only new zrCS values trigger any change to a rider's rating. They are:

Chase Races
Disabled because the intent of this format is to work together and is not considered an individual event.

Team Time Trial
Similar to chase races, these are team-based events where an individual's finish position isn't necessarily an accurate reflection of their effort in the race.

Zwift Racing League
ZwiftRacing uses ZwiftPower as a "source of truth" for result data. ZRL races are ineligible for vELO rating changes because the results listed in ZwiftPower for this series are usually inaccurate. The series organizer does not, for reasons that are understandable, update ZwiftPower with the real finish order after applying intermediate points and disqualifications. Because of this, Zwift Racing League races are not vELO enabled events.

Zwift Grand Prix
This eSports professional series uses race formats that are not supported in ZwiftPower. Because of this, the results listed there are not an accurate reflection of the real outcome. This means that these events cannot be vELO enabled.

2.6 vELO Execution Outline

The vELO algorithm that executes on eligible races does so by completing these steps:

2.6.1 Calculate Race 'Before' Rating

The first step in the vELO algorithm is to determine what rating to use as the default input value for each result. This is typically the rider's existing current vELO rating but, if the rider set a new zrCS value as a result of the effort in the race that is higher than their current vELO, an alternative 'before' rating is used.

Major Adjustment
If the new zrCS is more than a 10% improvement, the new zrCS is used as the before rating and the change is registered as a Major Adjustment.

Minor Adjustment
If the new zrCS is less than a 10% improvement, the zrCS improvement is added to the current vELO rating and used as the before rating and the change is registered as a Minor Adjustment.

2.6.2 Apply Terrain Handicap (if enabled)

Scratch races use terrain handicaps to modify the input vELO rating based on the rider's power profile and the parcours of the race. These are described in detail below but the resulting value is either added or subtracted from the existing before rating to complete the setup process.

2.6.3 Calculate Rating Change

The amount of change (delta) and the direction of change (positive or negative) for each rider in a vELO-enabled race is calculated based on three values.

Score
A value representative of a rider's finish position relative to the number of finishers in the race. This score is boosted for riders (a so-called 'podium bonus') who finish in a podium place if that rider's current vELO rating is <300 more than their current zrCS and there are at least 5 finishers in the race.

Expected Score
A probabilistic value representative of the rider's performance relative to the vELO ratings of the other finishers.

Volatility
Calculated based on how often the rider has raced in the last 1, 7, 30 and 90 days. Racing more often lowers the result.

2.7 Uncommon Scenarios

There are times when the delta output from vELO is overwritten or ignored if one of a few edge-case scenarios are observed:

Effort
If the effort putforth during the race doesn't meet a minimum threshold relative to the rider's past power data, any change to their vELO as a result of the race is ignored. This is in place mostly as a preventative measure against willfully lowering your rating.

Power Floor
If the delta would lower the rider's vELO more than 200 points below their current zrCS value, the rider's vELO is limited to lowering to 200 below zrCS.

Floor
If the delta would lower the rider's vELO below 100 points, the rider's vELO is limited to lowering to 100 points.

2.8 Terrain Handicaps

As described above, a concept called terrain handicaps are applied in 'Scratch' races. The goal of these handicaps are to give vELO information about your strengths over different terrain relative to your vELO rating in order to make more accurate changes to your rating.

A detailed analysis of race results across routes classified into four different categories (flat, rolling, hilly, mountainous) was done to determine which power metrics were most indicative to success. The result of this analysis is then applied to a rider's power profile to determine the four terrain handicaps.

Once calculated, these handicaps are combined with a rider's current vELO rating to determine the rider's event 'before' rating. In cases where the handicap is positive (meaning that the rider is likely to perform well relative to their vELO), that amount is added to the rider's current vELO. If the handicap is negative (meaning that the rider is likely perform poor relative to their vELO) then that amount is subtracted from the rider's current vELO.

As an example, suppose a rider named Sammy Sprinter with a current vELO rating of 1500 enters a race on a flat route and they have a +100 flat terrain handicap, their event vELO rating will be 1600 (1500 + 100) which has the effect of increasing the expectations of that rider in order for the platform to give a postive delta. This means that Sammy's power profile suggests that they are well-placed to perform well on routes like this. Another rider in Sammy's race, Carly Climber, has a current vELO rating of 1600 but a flat terrain handicap of -200. The net event rating of 1400 (1600 - 200) suggests that Sammy will have the edge even though Carly's vELO rating is higher.

This event rating only serves as the input to the system and does not replace the existing vELO value.


3 Ranking Points (RP)

3.1 What is Ranking Points (RP)?

If vELO is the platform designed to correctly categorize riders of the Zwift platform into one of 10 categories, Ranking Points (RP) is an algorithm that aims to reward riders for their performance in those races. The two systems operate completely independently and have no bearing on one another.

The primary purpose of RP is to solve the question of "Which rider in Gold is best?" by awarding points to (mostly) all finshers in all eligible races and seeing which riders best 5 RP performances add up to the highest sum.

3.2 Ineligible Races

The Ranking Points algorithm runs against the results of nearly every race held on the Zwift platform. There are some cases, however, where RP is skipped and no points are awarded. They are:

Chase Races
Disabled because the intent of this format is to work together and is not considered an individual event.

Team Time Trial
Similar to chase races, these are team-based events where an individual's finish position isn't necessarily an accurate reflection of their effort in the race.

Zwift Racing League
ZwiftRacing uses ZwiftPower as a "source of truth" for result data. ZRL races are ineligible for Ranking Points because the results listed in ZwiftPower for this series are usually inaccurate. The series organizer does not, for reasons that are understandable, update ZwiftPower with the real finish order after applying intermediate points and disqualifications. Because of this, Zwift Racing League races do not award Ranking Points.

Zwift Grand Prix
This eSports professional series uses race formats that are not supported in ZwiftPower. Because of this, the results listed there are not an accurate reflection of the real outcome. This means that these events cannot award Ranking Points.

Not Enough Riders
In an effort to encourage riders to seek out races with larger pens, no Ranking Points are awarded in pens with fewer than 5 starters. Riders who DNF are included in this total.

3.3 Ranking Points Implementation Outline

The Ranking Points algorithm that executes on eligible races does so by completing these steps for each pen (if there were the required 5+ starters):

3.3.1 Time Cut

The first step in the Ranking Points algorithm is to calculate the time cut for the race. The purpose of the time cut is to ensure that the only riders who are awarded Ranking Points from the race are those who were reasonably close in finish time to the winner. Without it, riders from lower categories could join and come last (or near the bottom) of a much-higher category race and earn enough points to inflate their rank incorrectly.

The time cut coefficient used to calculate the time cut uses the route profile and winner's average speed (KPH) as inputs according to the following table:

Profile< 2727-3030-3333-3636-3939-4242-4545-48> 48
Flat6%6%6%6%7%8%9%10%11%
Rolling8%8%8%9%10%11%12%13%13%
Hilly10%10%11%12%13%14%15%15%15%
Mountainous12%13%14%15%16%17%17%17%17%
3.3.2 Calculate Winner's Points

With the time cut established, it is time to calculate the points the winner will receive. This calculation uses the factors below to award the winner with the most points in the race:

Field Strength
A measure of how strong the field of riders was in the race depending on how many riders made the time cut:

Non-cut FinishersField Strength
20 or MoreAverage vELO of Top Half (sorted by vELO)
11 to 19Average vELO of Top 10 (sorted by vELO)
5-10Average vELO of All Non-Cut Finishers

Time Modifier
Used to award more points for longer races and fewer points for shorter ones. The modifier uses a sliding scale that reaches its lowest point for races 20 minutes and shorter and hits its highest mark for races 60 minutes or longer.

Size Modifier
Used to award more points for big pens and fewer points for small ones. The modifier uses a sliding scale that reaches its lowest point for races with 5 non-cut finishers and hits its highest mark for races with 20 or more non-cut finishers.

3.3.3 Calculate Non-Winner's Points

A mathematical logarithm function is utilized to award points to all the non-cut Finishers who did not win where second place earns more than third, third place earns more than fourth, etc.

3.4 Total Ranking Points

As stated above, the whole purpose for Ranking Points is to rank riders of the same vELO category. This is done by adding up the five best RP awards in the last 90 days of racing on Zwift.


4 - Race Achievements

4.1 What are Race Achievements?

One of the truisms of Zwift and Zwifters generally is that it's a diverse platform of people who are racing for different reasons. This is everyone from the eSports professional to the person who just started cycling. In an effort to meet people where they are and also to encourage them to branch out to events and race types that are foreign to them, there are many achievements available that can be earned.

The achievements have no bearing on your vELO rating nor your Ranking Points ranking amongst your category peers but there is a separate ranking table for the completionists among us to try to climb.

4.2 Earning Achievements

Achievements are earned and awarded after the vELO and Ranking Points calculations are complete. They are currently all based on actions in that one race but likely will expand in the future to include historical race results relevant to the new event.

4.3 Achievement Types

General
A catch-all group of Achievements that are un-related to any of the other types.

Ranking Points
Awarded for milestones related to the Ranking Points system.

Race Type
Achievements that reward Zwifters for branching out and trying all race formats.

Route Type
Rewards Zwifters who try and are successful in races on all four types of routes (Flat, Rolling, Hilly and Mountainous).

World
Encourages riders to seek out and succeed in races on all of the worlds in Zwift.


5. Event Processing

5.1 Schedule

ZwiftRacing uses a series of scheduled jobs to keep up-to-date with new data that ZwiftPower has made available and needs be imported and processed. Great care has been taken to limit the interactions with ZwiftPower so as to not cause any trouble with Zwift or to impact the performance of ZP. Below are the current jobs that are in use:

Find New Completed Events (Hourly at 0:15)
Reviews the Event Result List on ZwiftPower and processes any events that have results that ZwiftRacing has not yet reviewed

Search for .FIT File Updates (Hourly at 0:30)
The power data available immediately after the event completes is considered 'Live Data' and is less accurate than the data that becomes available several hours later after the fit files are processed. In order to capture that more accurate data, this job looks for events that have completed between 4 and 24 hours ago and has results that still are using Live power data and checks for .FIT file replacements on several of them.

Find New Results (Hourly at 0:45)
This job is similar to the one that runs at 0:15 with the only difference being that this is looking for new results on events that ZR already knows about. This job mostly picks up updates that have occurred on the ZwiftPower side (ex. disqualifications, prime applications).

5.2 Ineligible Events

At this point in time, ZwiftRacing only looks for and processes results from events of type Race. This is mostly in effort to eliminate as much interaction with ZwiftPower as possible. There are two exceptions made currently for events of type Group Ride: 'Club Ladder' events and 'ZR.app' events.

5.3 Event Processing Procedure

Whether the event is new or existing, the procedure for processing that event remains the same:

1 - Create (or Update) Event
Persist metadata about the event relevant to subsequent steps or to display of the event on ZwiftRacing

2 - Analyze New/Updated Results
Review any new or updated Race Results with an emphasis on any new personal bests (in the last 90 days) that may have occurred. This includes results that finished in a DNF (did not finish) and DQ (disqualification).

3 - Run vELO Algorithm
Execute the vELO algorithm, a first-ever result-based categorization system designed specifically for indoor cycling platforms, against the available results if eligible. Details about vELO can be found below in this documentation.

4 - Invoke Ranking Points (RP) Algorithm
Execute the Ranking Points algorithm on eligible races. This system rewards riders with points based on a set of criteria and is used to rank you amongst your category peers. Details on RP are found below in this documentation.

5 - Check for Achievements
Looks to see if any riders who completed the event may have matched the criteria needed to gain a new Race Achievement. This system is meant to reward riders for unique achievements in Zwift racing and is described in detail below in this documentation.