GoldenCheetah/doc/user/GC3-FAQ.texinfo

\input texinfo   @c -*-texinfo-*-
@ifnotinfo
@input palatino
@end ifnotinfo
@c %**start of header
@setfilename FAQ.texinfo
@settitle Golden Cheetah FAQ
@c %**end of header
@paragraphindent 0

@copying
This manual is for Golden Cheetah, version 3.1.

Copyright @copyright{} 2013 Mark Liversedge
@end copying

@titlepage
@title Golden Cheetah FAQ
@c @subtitle subtitle-if-any
@c @subtitle second-subtitle
@author Mark Liversedge

@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying

@end titlepage

@c So the toc is printed at the start.
@contents

@ifnottex
@node Top,Top,Top,
@top title

This manual is for GoldenCheetah, version 3.1.
@end ifnottex

@menu
* MOST COMMON QUESTIONS OF ALL::    Most common questions
* GENERAL:: General Questions
* DATA::    Working with Data
* METRICS:: Working with Metrics
* UPLOADING AND DOWNLOADING::   Uploading and Downloading Data
* SEASONS AND EVENTS::  Seasons and Events
* CHARTS::  Configuring and Using Charts
* INDEX::   Index
@end menu

@node MOST COMMON QUESTIONS OF ALL,GENERAL,INDEX,Top
@chapter MOST COMMON QUESTIONS OF ALL


@section How do I override / manually enter TSS for a ride?
@cindex TSS

The details chart on the analysis view allows you to override metrics on the metrics tab. 
By default the most common metrics are listed, including average HR, distance and so on.
From v3.1 the default setup will also include TSS as a metric you can override here.

If the metric is not there you will need to configure GoldenCheetah to allow it to be shown.
This is simple to do and described in 3.9 below. The 3.1 upgrade process should have added it
to the Metric tab if it was not already there.

@section How do I add or remove a chart?
@cindex add
@cindex remove

To add a new chart to the view you can select from the hamburger menu on the right hand side of 
the chart bar.

Depending upon which view you are on the charts available will differ. For example realtime
plots only appear on the Train view, whilst charts that work with individual rides will only
appear on the analysis view.

To remove a chart, when you mouse over a chart (in tabbed or tiled mode) the word 'More...'
will appear in the top left of the chart. This is a menu drop down, if you click on it
you will see a `Close' option. This is the option to remove (close) the chart.

@section Can I enter my weight and track/plot it?
@cindex weight

Weight can be maintained in 3 ways;

@itemize @bullet

@item Every athlete is setup with a weight value -- this is the fallback value should no
    other weight measure be available. It can be found under preferences and athlete.

@item The 'Weight' field can be maintained in the details screen. This is found on the 
    'Workout' tab in the details screen by default. Any entry here will be used for this ride
    ONLY.

@item You can download weight from a withings scale. This is performed manually via the
    menu option Tools->Get Withings Data. This is then used to update the local measures
    database.
@end itemize

When calculating W/KG the Activity value is used if present, if not we then fall back to
the last Withing measure that was collected, and if that is not available we then fall
back to the default value for the athlete.

The weight from withings and weight from the activity can both be plotted separately in
the LTM plots.



@section How do I plot x sec power best?
@cindex best

In v3.1 it is now possible to plot custom durations for any data series on a metric
trends chart in the Trends view. You will need to add a curve for the data series
and select `Best' instead of `Metric' or `Estimate' on the curve settings.

For v3.0 or earlier it is still not possible to plot custom durations for power bests. We are
looking to add this in version 3.1, but for now you can only plot 1s, 5s, 10s, 15s, 20s,
30s, 1min, 2min, 5min, 10min, 20min, 30min and 60min bests.



@section I can't find Aerolab / Performance Manager?
@cindex Aerolab
@cindex PMC

By default we do not add these charts to the layout. Aerolab can be added to the Analysis
view via the '+' menu found to the right hand side of the GoldenCheetah scope bar.

Similarly, the Performance manager can be added to the Home layout via the '+' menu. We
may deprecate this chart in the near future since the LTM charts can be used to plot a PMC
and we expect to implement an interactive PMC for planning in v3.1.



@section What happened to weekly summary?
@cindex weekly summary

It has been deprecated since the Diary view allows you to summarise by day, week and month
and add charts to the view that summarise for the selection. As the weekly summary was fixed
on specific charts and did not handle other selections (e.g. monthly) it has been deprecated
in view of the diary view.

At present you can treat the Diary view as you would have the weekly summary -- they offer
the same functionality. We expect the diary view to extend to planned workouts when we
implement planning functionality in v3.1.



@section Where are all the chart settings?
@cindex settings

All chart settings can be found under the drop down menu that appears in the top left hand
corner of a chart when you mouse over it, titled `More...'. They will appear as a popup dialog box.

Additionally, when you move the cursor towards the title of a chart in a view that is tabbed
(not tiled) then a small selection of the most important settings for the chart will appear
for convenience.

@section Where is the preferences / options panel?
@cindex preferences
@cindex options

On a Mac the configurations page can be found under 'GoldenCheetah -> Preferences' on the
main menu. Whilst on all other platforms it is found via 'Tools -> Options'.

We do this to match the general guidelines for the operating system.

@section How do I change the colour of the rides on the calendar/list?
@cindex colour

Activities are coloured according to keywords embedded in their details (metadata) you can
configure the field that is used and the values that are matched and the colours they are
shown in from the preferences pane via the 'Data Fields' toolbar option then select Notes
Processing. The keywords and related words are scanned for to determine if the associated
colour should be used for this ride.

They are processed in the order they are defined with the first match being returned. Take
care when using values such as 'TT' and 'race' since these can also be part of an English
word (e.g. ATTEMPT contains 'TT' and graceful contains 'race'.

@section GoldenCheetah doesn't find my PowerTap on Ubuntu Linux.
@cindex powertap
@cindex cervo
@cindex usb

If you're using the USB cradle (as opposed to the older, serial one), the FTDI driver sometimes 
conflicts with the braille terminal in the default Ubuntu installation. Try unplugging the PT cradle 
from the computer and uninstalling brltty: sudo apt-get remove brltty
Then plug the device back in and it should work.

@section GoldenCheetah.dmg installation didn't seem to work.

Are you running OS X Snow Leopard (10.6) or later? You need to be. If you are, and you're still
having this problem, open Terminal (in Applications -> Utilities) and type this at the prompt:

/Applications/GoldenCheetah.app/Contents/MacOS/GoldenCheetah then press <return>
and send an email to the mailing list with whatever it prints out. We'll help you debug it.

@node GENERAL,METRICS,MOST COMMON QUESTIONS OF ALL,Top
@chapter GENERAL


@section What is GoldenCheetah?

GoldenCheetah is primarily a program for cyclists that own a power meter. It allows them to
record, track and review their performance against recorded data. It also allows you to ride
your turbo and collect data as you ride.

If you do not have a power meter then some of the functionality will not be of use to you
as a cyclist. But you can still record and track progress. We support HR based TRIMP metrics
for a HR based PMC for example.



@section What is a good book or resource on training with power?

Unquestionably the bible for working with a power meter is Training and Racing with a Power
Meter by Hunter Allan and Andy Coggan. Make sure you look at the 2nd edition since it is
revised quite dramatically. Whilst it is heavily  biased towards WKO+ as a software package
most of the functions of note are also available in GoldenCheetah.



@section Where can I download the installer for GoldenCheetah ?
@cindex download
@cindex install

Stable releases are available from @url{http://www.goldencheetah.org} whilst the latest and greatest
code build is available from @url{http://goldencheetah.stand2surf.net}. Development builds are for the
brave, since they may contain bugs. In reality the development builds are a changing feast
and often contain latest fixes too.



@section Where can I get the source code?
@cindex source
@cindex github
@cindex clone

The GoldenCheetah source code is hosted on github and can be cloned using the following url;
@code{git://github.com/GoldenCheetah/GoldenCheetah.git}



@section I am a triathlete is GoldenCheetah appropriate for me?
@cindex triathlete

GoldenCheetah is not a multi-sport program. For tracking cycling performance it is a good
choice. But if you are looking for running and swimming metrics and tracking then these
features are not available at present. It is an excellent choice for analysing cycling
aspects of triathlon, or working on the trainer.



@section Is there a mailing list?
@cindex mail

The mailing list for GoldenCheetah users is maintained via Google Groups at
@url{http://groups.google.com/forum/?fromgroups=#forum/golden-cheetah-users} the first post you
make is moderated and may take a while to appear. Once your first post is made you can
make future posts without moderation.



@section How do I report a bug or request a new feature?
@cindex feature
@cindex bug
@cindex report

We use Github issues to record bugs and feature requests. You will need to create an
account on github and then post a new request or bug at 
@url{http://www.github.com/GoldenCheetah/GoldenCheetah/issues}



@section How can I contribute?
@cindex contribute

Patches are most welcome via the mailing list or a pull request in github. Of equal
importance is the timely reporting of bugs and help in testing fixes. We also desperately
need volunteers to translate into non-English languages and help with writing documentation
including the maintenance of this FAQ.

If you want to help, post a note on the golden-cheetah-users mailing list.



@section Can I donate to the project?
@cindex donate

We are an open source project. Our software is developed by a community. We do not have
any facility to collect funding or spend it! We would rather you spread the word if you
think our software is good, and maybe help out with documentation, tutorials or
translations if you can.



@node METRICS,DATA,GENERAL,Top
@chapter METRICS


@section What is the difference between xPower, NP and Daniels EqP?
@cindex xPower
@cindex NP
@cindex Daniels
@cindex EqP

They all serve the same purpose -- to express the variable power you have generated over
a given period of time as a single value. This is so you can quantify the intensity of
the ride and therefore the training stress of the ride.

In practice, NP and xPower are largely the same, whilst Daniels EqP place much higher
emphasise on upper intensity work. For more info on xPower see Dr Skiba's paper on BikeScore
@url{http://www.physfarm.com/bikescore.pdf}



@section What is the difference between CP and FTP?
@cindex CP
@cindex FTP

CP is a shorthand for CP60 in GoldenCheetah, and is computed using the Scherer/Monod
protocol using 3 and 20 minutes. Functional Threshold Power (FTP) is an actual measure of
the power an athlete sustains for 60 minutes.

Since it is very difficult for an athlete to maintain the desired intensity FTP 'reality'
tends to result in a number that is much lower than CP 'theory'. Often users will
consider the two as the same.

In GC we compute TSS and BikeScore using your 'CP' value. If you set it to your FTP value
TSS will be accurate, BikeScore is likely to be lower. And if you set it to your CP value
BikeScore will be accurate, but TSS will be overstated.



@section Why does my CP chart show higher watts for a longer duration?
@cindex CP

A higher power average for a longer time is possible if an effort has been "book ended".
If, for example, you did a massive 30 second effort, followed by freewheeling for 29:30
then another massive 30 second effort, then your best average for a continuous 30 minutes
would in fact be lower that your best average for a continuous 30minutes and 30 seconds.
(Thanks for Jon Hill from the Golden Cheetah Users mailing list for this example).



@section Can I set a different CP/FTP for different reasons e.g. CP/FTP on a trainer?
@cindex CP
@cindex FTP
@cindex trainer

We allow you to override the CP value for a specific ride by setting the "CP" field to
the value you wish to use for the ride in question. We do not have a concept of 'separate'
Cps for different purposes -- you will need to specify the CP when the data is imported
into GC. But this allows you to make manual adjustments.

We provide this functionality at user request -- we do not endorse the concept of multiple
CP values. But we do recognise the ongoing debate regarding physiological stress from
working on a trainer vs on the road.


@section How do I seed the CTL for my PMC?
@cindex PMC
@cindex CTL
@cindex LTS

You can seed the starting CTL (we call it LTS, for long term stress) when you define a
season. That way it is re-usable in a number of places. To do this you edit the season
(date range) in the Home View and can set the Starting LTS.

@section Why is elevation different in GoldenCheetah to my other training software / website?
@cindex elevation

Different programs will use different hysteresis values to smooth the small changes in
altitude. In GC we use a hysteresis value of 3m.

If this is of great concern you can adjust the hysteresis value in preferences under the
general tab.



@section Why is a metric e.g. TSS or average power different in GoldenCheetah to Garmin Connect?
@cindex TSS
@cindex AP
@cindex Garmin Connect

The algorithms for calculating TSS, AP etc are static. They are implemented exactly the
same way in GoldenCheetah, Garmin Connect, TrainingPeaks etc. The algorithms are extremely
simple and not prone to difficulty in implementation.

However, how each application treats pauses and stops or loss of data accounts for most
differences. In GoldenCheetah we always calculate AP,TSS etc including stop time. Other
applications choose to ignore or smooth segments of short duration.

In addition, if there are anomalies in your data, with large gaps or even time going
backwards, this will drastically affect GoldenCheetah's calculations.

We NEVER attempt to interpret data anomalies -- if the results are not as you would expect
you will need to correct the data. We do not 'silently' fix the data for you. There is no
secret sauce in GoldenCheetah, we are open and transparent with your data.



@section How do I set the metrics shown for intervals in the various summaries?

In the GoldenCheetah preference pane under the Metrics tab you can choose the metrics
that will be shown in the ride summary charts and the metrics that will be shown in the
interval summary in the analysis sidebar.



@section How do I add a metric to the details screen (so I can override it) ?
@cindex override

If the metric you want (e.g. TSS) is not shown then you will need to add it via the
GoldenCheetah preferences pane. On Mac this is from the menu option
GoldenCheetah->Preferences whilst on Windows and Linux it is under Tools->Options.

You will need to select 'Data Fields' option from preferences toolbar and then the
'fields' tab. You will see a list of fields that are associated with a particular screen
tab. If you scroll down you should find entries for the 'Metrics' screen tab, you can
insert a new entry here with the '+' button. You should make sure the new entry is
called exactly the same thing as the metric in question.

For 'TSS' this is relatively straight forward. For others, e.g. 'Average Heart Rate' you
must make sure that the name includes spaces etc. Once your metric has been added to the
configuration you should save that and return to the details screen where you can now
maintain it.

If you are creating a manual entry then there is no 'details' tab in the dialog. Once
you have created the entry (and again in this case TSS can be entered in the dialog)
you should go to the details tab to maintain any other specific fields. The manual entry
dialog is designed to be simple and accept only the most common of entries.



@section Can you calculate gradient, virtual power or other derived series from the ride data?

Not in 3.1. We plan to extend this functionality in v3.2.



@section Can I export metrics or access the metric database GC uses?

The metrics are stored within a Sqlite 3 Database called 'metricDBv3' that can be found
in the athlete directory. You can use any Sqlite 3 tools to query and work with the db.

Alternatively you can export the db in its entirety using the Activity->Export Metrics
as CSV to export to a format you can use in a spreadsheet program. 



@node DATA,UPLOADING AND DOWNLOADING,METRICS,Top
@chapter DATA



@section How do I split, merge or join files?
@cindex split
@cindex merge
@cindex join

You can split a file by time using the activity->split ride menu item (or toolbar button).

To join two rides together (making one longer ride from two rides) you can copy rows
in the activity editor and paste special in the ride editor (right click) and then select
append mode.

If you wish to merge rides, in v3.1 there is a new Activity->Merge wizard that will walk
you through merging ride files and also provide the ability to synchronise timestamps.



@section How can I find 'spikes' or specific values in activity data?
@cindex spikes
@cindex anomalies

The activity editor has a function to find data on its toolbar. You can specify a range
or upper or lower limit and find values less than, greater than or between a range of values.

Additionally, the editor will scan the file looking for anomalies -- where the data
appears to be out of normal ranges. These are shown with a wiggly red line in the editor
and can also be listed by clicking on the anomalies icon on the editor toolbar.

If the anomalies icon is not enabled on the toolbar then there are no anomalies in the
currently selected ride.



@section How can I fix 'spikes' or 'anomalies' in activity data?
@cindex spikes
@cindex anomalies

You can either manually edit the values in the activity editor (there is full undo and
redo in the editor). Or you can use the fix tools that are listed under the tool menu
option (fix power spikes, fix gaps in recording, fix gps errors, fix torque.

Each of the fix tools opens a dialog that displays texts to explain what the fix tool does.



@section How can I add/remove a field to edit on the details screen?

The fields (metadata) that is editable can be configured in the preferences pane under
the data fields tab. Where no screen is specified (its left blank) it will not be made
available.

GoldenCheetah ships with a number of fields defined in the config but with no screen set.
If you wish to use them simply set the screen tab to the tab you would like it to be
shown on. To remove a field set the field tab to blank.



@section What are 'special fields' ?

There are a number of fields that when maintained in the details screen will be used
elsewhere in the code to calculate metrics or for other purposes.

Some examples include;

    Weight - used in W/KG calculations, Sport and Workout code are
    used  when exporting to other file formats, Identifier is used to assign a UUID to the
    activity when it is uploaded to online services and so on.

There is a full list of special fields and their meaning in the Golden Cheetah user
guide appendices.



@section How do I find/add/sort/delete/edit intervals ?

The context menu (on the right hand side of the splitter handle) for the interval
sidebar in Analysis view contains a number of options for working with intervals.

Additionally, you can click and drag on the performance (aka ride) plot to visually
define an interval.



@section How can I export to a specific file format?
@cindex PWX
@cindex JSON
@cindex TCX
@cindex CSV
@cindex FITLOG

Activity->Export allows you to export the activity to csv, fitlog, gc (xml), json,
Training Peaks PWX or Garmin TCX format.



@section Can I use GC to convert data from one format to another on the command line?

No. It is something we may add in v3.2



@section Can I delete an athlete and all his/her data?

No. It must be done manually by removing the athlete directory via the operating
system. Please ensure you do this when GoldenCheetah is not running.



@node UPLOADING AND DOWNLOADING,SEASONS AND EVENTS,DATA,Top
@chapter UPLOADING AND DOWNLOADING



@section Why does upload to TrainingPeaks keep failing?
@cindex TrainingPeaks
@cindex upload

The Sport field in TrainingPeaks must have very specific values, although this is not
documented in the XML Schema. We recommend using a sport of "Bike" if you plan on
uploading rides to training peaks.



@section Why does download from TrainingPeaks say I need a premium account?
@cindex TrainingPeaks
@cindex download

Training Peaks only allow paid up members to get access to their data. If you are
using a free service they do not let you retrieve your data.



@section What settings do I need to get GoldenCheetah to upload to my Google Calendar?
@cindex Google

The upload to Google Calendar uses their CalDAV API, and as such needs to specify a
collection. This means when entering the details in the passwords pane of preferences
you should use the following for the caldav url:
    
    @url{https://www.google.com/calendar/dav/xxxx@@gmail.com/events/}

Where xxxx is your username. The username will need to be repeated in the username
field and obviously set the password too.


@section When setting up my Withings wifi scales where do I get the userid and key ?
@cindex Withings

You will need to login to your Withings account (@url{http://my.withings.com}) and
click on the `share' button at the top of the dashboard. From there you will get a
popup box with lots of options.

If you click on `share on my website' you will be greeted with a number of code
snippets you can embed in a web page. If you look closely in the top right hand
corner there will be a box containing the user id and public key. These are the
two values you need to enter into the options dialog.

You will now be able to retrieve withings data via the tools menu.

@node SEASONS AND EVENTS,CHARTS,UPLOADING AND DOWNLOADING,Top
@chapter SEASONS AND EVENTS



@section Why are there different types of seasons?
@cindex season
@cindex adhoc
@cindex cycle

This is to help with planning functions. As of v3 there is no real distinction made.
Adhoc seasons are expected to be used solely as date ranges and have no associated plan.
Whilst other season types may contain plans. This is only relevant for planning
functions that are not available yet.



@section What is event used for?
@cindex event

It is only used to annotate a LTM chart -- so you can show an 'event' that happened at
a particular date. There are no rules about what constitutes and event. It could be a
race, a training camp or just a day that was particularly meaningful e.g. illness, crash.


@section How do create/edit/delete seasons and events?
@cindex event
@cindex season

Seasons and Events are created and edited in the sidebar for the Home view. Seasons are
listed under date ranges, whilst events are listed under the events sidebar item. In
both cases they can be created and deleted from the sidebar item's drop down menu.

Please note that in v3.1 events can only be created when a user season is selected, since
events are associated with a particular season. This constraint will be removed in v3.2.

@node CHARTS,INDEX,SEASONS AND EVENTS,Top
@chapter CHARTS



@section I want to plot month -1,-2 and -3 how do I do that?
@cindex month
@cindex prior

Assuming the chart allows you to specify a date range you can select 'This' 'month'
and select prior '3' to specify a month 3 years prior, similarly 'This' 'month' and
prior '2' is a month 2 months ago, whilst 'This' 'month' and prior '1' is last month.

'This' 'month' prior and 0 is just this month.



@section How should I use Aerolab?
@cindex Aerolab
@cindex Chung
@cindex VE

The following is a brief piece of advice from Robert Chung, from a discussion on the
Golden Cheetah Users mailing list:

    Ideally, you'll want calm conditions (both in terms of wind and traffic) but here's a
    quickie test you can do just to get a handle on what to do. Try to find a loop without
    stop signs, or an out-and-back with maybe a little dip or something in the middle. Make
    sure you won't get hit by a car and have good sight lines. I just go around my block a
    few times. Do a loop in the drops, then another loop faster, then a loop slower; then
    repeat with your hands on the hoods.

    Weigh yourself and the bike and ballpark the air density. 

    See whether you can come close to modeling the "true" elevation profile by sliding the
    CdA slider around. Even with this informal test, as long as the wind isn't blowing too
    hard, you ought to be able to see a difference between the loops where you were in the
    drops and the loops where you on the hoods, and to spot little bumps and dips in the road. 

There is also an overview of Virtual Elevation to measure aerodynamics in this
YouTube video from the power seminar at Interbike 2011 given by Jim Meyer the founder
of Quarq:

    @url{http://www.youtube.com/watch?v=b8tJnFE_BFg&feature=youtu.be&t=27m58s}

Finally, Robert Chung's original paper is included in the docs section of the GoldenCheetah
repository, you can it up here (click on 'View Raw' to download):

    @url{https://github.com/GoldenCheetah/GoldenCheetah/blob/master/doc/contrib/ChungVE.pdf}



@section My map doesn't show?
@cindex map

This is most likely because you have a proxy that requires authentication or session
details. We do not have sophisticated support for internet proxy servers. We will
re-use the operating system settings where they are configured.



@section What is the treemap plot used for?
@cindex treemap

Typically it is used to visualise where you spend your time or where you get best
results.  It is not particularly useful if you do not maintain details for each ride
e.g. workout code, sport et al.



@section Can I change the colors in plot x ?
@cindex colour

With the exception of the Long Term Metric plots the colours on the charts are
configured in the GoldenCheetah preferences pane. It is possible to apply a theme
or change each individual color.

We want to use the same colours to plot each data series across the charts, so you
can change them globally.

The only colours you cannot change are the colours assigned to intervals when plotting
them on scatterplot or PfPv. These colours are assigned according to their sequence.



@section How do you zoom in on a chart?
@cindex zoom

You can zoom in on the distribution, scatterplot and PfPv charts by selecting the zoom
area with the left click of the mouse.

On the performance (ride) plot you can zoom with the span slider at the bottom of the
chart (if you select the full plot in the chart settings).

There are no other zoom options for the other charts.



@section I zoomed in but can't zoom out?
@cindex zoom
@cindex unzoom

Right click will zoom back out to the previous zoom level (in the case of zooming
multiple times).  If you select another activity the chart will return to fully
zoomed out.



@section GoldenCheetah is saying there is no data for a chart, but I'm sure there is?

You should check in the editor if the data series is present. if the activity is a
manual activity entry it will contain no data.

@node INDEX,MOST COMMON QUESTIONS OF ALL,CHARTS,Top
@unnumbered Index

@printindex cp

@bye