Skip to content

Latest commit

 

History

History
125 lines (87 loc) · 3.96 KB

faq.md

File metadata and controls

125 lines (87 loc) · 3.96 KB

FAQ

Table of Contents

Charts

How do chart filters work?

Chart requests allow us to filter runs based on some criteria. In general, filters contains a list of filters, where a run must satisfy all filters to be included. We have the following filter "atoms":

  • label <lbl>: The run must have the label lbl (case-sensitive).
  • datetime <op> <val>: The run's datetime field must satisfy the condition e.g. datetime > 2019.
  • distance <op> <val>: The run must have distance <op> <val> e.g. distance > 5 km.
  • duration <op> <val>: The run must have duration <op> <val> e.g. duration < 2h.
  • pace <op> <val>: The run must have pace <op> <val> e.g. pace <= 4m30s /km.

<op> can be one of:

  • <=
  • <
  • =
  • /=
  • >=
  • >

Filters also support basic boolean logic i.e.

  • not expr: expr must be false.
  • expr1 or expr2: expr1 and/or expr2 must be true.
  • expr1 and expr2: expr1 and expr2 must be true.
  • expr1 xor expr2: Exactly one of expr1 and expr2 must be true.

where expr is either an atom or another expression.

For example, we can have:

[[charts]]
title = 'Races and long runs'
filters = ['label official_race or label marathon', 'distance >= 25 km', 'datetime > 2024']
y-axis = 'distance'

In this case, we will take all runs that satisfy all of the following criteria:

  • Has label official_race and/or marathon.
  • Has distance >= 25 km.
  • Has datetime > 2024 (i.e. 2025 onwards).

Tip

Technically, there is no need to have a separate expr1 and expr2 expression, as we can encode and with multiple filters. Nevertheless we include the redundant functionality, as it may make some expressions simpler.

Running

What is NPM, and why do I need it?

NPM is the "node package manager", and the chart command requires it to be installed, since we use node to build the charts. See https://nodejs.org/en/download for installation instructions.

To test installation, verify that npm -v works and returns some version:

# The version does not necessarily have to be the same.
$ npm -v
10.9.0

Misc

What units are available?

Pacer defines several quantities that require the user to specify the units. In general, we have:

  • distance: meters, kilometers, and miles. Short versions can also be specified: m, km, and mi. There are also several built-in values:

    • marathon
    • half-marathon or hmarathon

    Note that these do not take in a unit. The unit will be based on the context, and if it is ambiguous, defaults to kilometers.

  • duration: "time strings" like 1h2m3s for 1 hour, 2 minutes, and 3 seconds. Each component is optional e.g. 1h3s or 2m.

  • pace: <duration> /<distance> e.g. 5m30s /km. Note that meters are not allowed with paces; only kilometers or miles. In cases where the context is clear, the trailing unit is not required. Also note that because paces are always given in terms of 1 km or 1 mi, the full versions are singular, not plural e.g. 4m /kilometer.

Parsing is designed to be moderately flexible, so numeric values can optionally be separated from the units by whitespace (quotes are then required) e.g. '4 km' or 4km.

Examples

--distance 5m
--distance '42 km'
--distance '42km'
--distance marathon
--distance '10 miles'
--distance '10 mi'

--duration 1h2m3s
--duration 4m30s
--duration 300s

--pace '4m20s /km'
--pace 5m/mi

# Pace unit can be omitted when it can be inferred from context e.g. no need
# to specify 'km' twice here:
#
$ pacer derive --distance 42km --pace 5m
3h 30'00"

# The pace unit is also not required when it is irrelevant e.g. when
# scaling:
#
$ pacer scale --pace 5m -k 0.9
4'30"