CAGR Custom Range

2021年10月13日

█ OVERVIEW

This script calculates an annualized Compound Annual Growth Rate from two points in time which you can select on the chart. It previews an upcoming feature where Pine scripts will be able to provide users with interactive inputs for time and price values.

👉🏼 We are looking for feedback on our first take of this feature.
     Please comment in this publication's "Comments" section if you have suggestions for improvement.


█ HOW TO USE IT

When you first load this script on a chart, you will enter the new interactive selection mode. At that point, the script is waiting for you to pick two points in time on your chart by clicking on the chart. Once you select the two points, the script will find the close value for each of the two selected bars, and calculate the ​CAGR value from them. It will then display a line between the two points, and the ​CAGR value above or below the last point in time.

If the ​CAGR value is positive, the line and label will display in their "up" color (see the "🠅" color in the script's "Settings/Inputs" tab), otherwise they appear in their "down" color (the "🠇" color in the inputs). You can also control the line's width from the inputs.

You have the option of comparing the chart's ​CAGR value with that of another symbol, which you specify in the "Compare to" input. When a comparison is made, the label's background color will be dependent on the result of the comparison. The line's color will still be determined by the chart's value.

Once time points have been selected on the chart and the script is displaying the line, you can change the time points by clicking on the script's name on the chart. A small, blue rectangular handle will then appear for each point, which you can then grab and move. If you reset the inputs using the "Defaults/Reset Settings" button in the script's inputs, the two time points will reset to the beginning of September and October 2021, respectively.


█ CONCEPTS

The ​CAGR is a notional, annualized growth rate that assumes all profits are reinvested. It calculates from the close value of the two end points. It does not account for drawdowns, so it does not calculate risk. It can be used as a yardstick to compare the performance of two instruments. Because it annualizes values, the function requires a minimum of one day between the two end points (annualizing returns over smaller periods of times doesn't produce very meaningful figures).


█ LIMITATIONS

 • The two selected points must be distant from a minimum of one day. A runtime error will occur otherwise.
 • There is currently no way to restart the interactive mode from scratch without re-adding the script to the chart.
 • The points in time you select on one chart may map quite differently on other charts,
  depending on their constituent bars (e.g., intraday charts for 24x7 and conventional markets).


█ FOR PINE CODERS

 • Our script uses the most recent version of Pine, as the `//version=5` compiler directive indicates.
 • Interactive inputs were a long-standing and highly-requested feature by our beloved community of Pine coders.
  We hope you find this first step promising, as it opens up entirely new possibilities for both Pine coders and script users.
  You can, for example, use interactive inputs to draw shapes with your scripts, or support and resistance levels, etc.
  We're sure you'll come up with more creative uses of the feature than we could ever dream up )
 • Interactive inputs are implemented for input.time() and input.price(), the specialized input functions now available in v5.
  See the User Manual's new page on inputs for more information about them.
  You can also create one interactive input for both time and price values
  by using the same `inline` argument in a pair of input.time() and input.price() function calls.
 • Our min/max filtering when initializing `entryTime` and `exitTime` will handle cases where
  the script user inverts the two points on the chart.
 • The script uses the new runtime.error() function to throw an error in the `if days < 1` conditional structure.
 • We use the `cagr()` function from our recently-published ta Pine library.
  Pine libraries — not to be confused with the Public Library showcasing scripts published by our community of Pine coders —
  are one of the new features available with the recent Pine v5.
 • Note that our `strRightOf()` function cannot be used to generate ticker identifier strings for use in `request.*()` functions.
  This is because it produces results of "series" form while the functions require
  arguments of "simple" form for their `symbol` or `ticker` parameters.
  Have a look at our new User Manual page on Pine's Type system if you need to brush up on Pine forms and types.
 • We use a simple, repainting request.security() call because our calculations are not used to generate orders or alerts.
 • We document our user-defined functions using the same compiler directives used in exported functions in libraries.
  It will make conversion of those functions to library format easier if we ever choose to do so.
 • We use two Unicode hair spaces (U+200A) to push the "%" sign slightly away from values in our str.format() calls.
  While the ​impact is minimal, it increases readability.
 • Note the `priceIsHigh` logic used to determine if we place the label above or below bars.
  When price is higher than recent prices, we place the label above the bar, otherwise we place it below.
  It's not foolproof but it provides optimal positioning most of the time.
 • The point of the complicated "bool" expression initializing `displayCAGR` is to ensure that we only draw the line and labels once.
  When no comparison with another symbol is made, this occurs the first time we encounter a non-na value from the `cagr()` function.
  When a comparison is required, it occurs the first time both values are not na.
 • Before all mentions of "CAGR" in our description, we use a Unicode zero-width space (U+200B)
  to prevent the auto-linking feature to kick in for the term.
  This prevents the dashed underscore and a link like this (CAGR) from appearing every time "CAGR" is mentioned.
 • With Pine v5, the `study()` declaration statement was renamed to indicator().
  Accordingly, we will be eliminating the use of the "study" term from documentation and the ​UI.
  The generic "script" term will continue to designate Pine code that can be an indicator, a strategy or a library, when applicable.
 • We followed our new Style guide recommendations to write our script.
 • We used the techniques explained in the How We Write and Format Script Descriptions publication by PineCoders.
 • That's it! We've covered all the new features and tricks we used. We sincerely hope you enjoy the new interactive inputs,
  and please remember to comment here if you have suggestions for improvement. 💙



Look first. Then leap.