ValueAtTime█ OVERVIEW
This library is a Pine Script® programming tool for accessing historical values in a time series using UNIX timestamps . Its data structure and functions index values by time, allowing scripts to retrieve past values based on absolute timestamps or relative time offsets instead of relying on bar index offsets.
█ CONCEPTS
UNIX timestamps
In Pine Script®, a UNIX timestamp is an integer representing the number of milliseconds elapsed since January 1, 1970, at 00:00:00 UTC (the UNIX Epoch ). The timestamp is a unique, absolute representation of a specific point in time. Unlike a calendar date and time, a UNIX timestamp's meaning does not change relative to any time zone .
This library's functions process series values and corresponding UNIX timestamps in pairs , offering a simplified way to identify values that occur at or near distinct points in time instead of on specific bars.
Storing and retrieving time-value pairs
This library's `Data` type defines the structure for collecting time and value information in pairs. Objects of the `Data` type contain the following two fields:
• `times` – An array of "int" UNIX timestamps for each recorded value.
• `values` – An array of "float" values for each saved timestamp.
Each index in both arrays refers to a specific time-value pair. For instance, the `times` and `values` elements at index 0 represent the first saved timestamp and corresponding value. The library functions that maintain `Data` objects queue up to one time-value pair per bar into the object's arrays, where the saved timestamp represents the bar's opening time .
Because the `times` array contains a distinct UNIX timestamp for each item in the `values` array, it serves as a custom mapping for retrieving saved values. All the library functions that return information from a `Data` object use this simple two-step process to identify a value based on time:
1. Perform a binary search on the `times` array to find the earliest saved timestamp closest to the specified time or offset and get the element's index.
2. Access the element from the `values` array at the retrieved index, returning the stored value corresponding to the found timestamp.
Value search methods
There are several techniques programmers can use to identify historical values from corresponding timestamps. This library's functions include three different search methods to locate and retrieve values based on absolute times or relative time offsets:
Timestamp search
Find the value with the earliest saved timestamp closest to a specified timestamp.
Millisecond offset search
Find the value with the earliest saved timestamp closest to a specified number of milliseconds behind the current bar's opening time. This search method provides a time-based alternative to retrieving historical values at specific bar offsets.
Period offset search
Locate the value with the earliest saved timestamp closest to a defined period offset behind the current bar's opening time. The function calculates the span of the offset based on a period string . The "string" must contain one of the following unit tokens:
• "D" for days
• "W" for weeks
• "M" for months
• "Y" for years
• "YTD" for year-to-date, meaning the time elapsed since the beginning of the bar's opening year in the exchange time zone.
The period string can include a multiplier prefix for all supported units except "YTD" (e.g., "2W" for two weeks).
Note that the precise span covered by the "M", "Y", and "YTD" units varies across time. The "1M" period can cover 28, 29, 30, or 31 days, depending on the bar's opening month and year in the exchange time zone. The "1Y" period covers 365 or 366 days, depending on leap years. The "YTD" period's span changes with each new bar, because it always measures the time from the start of the current bar's opening year.
█ CALCULATIONS AND USE
This library's functions offer a flexible, structured approach to retrieving historical values at or near specific timestamps, millisecond offsets, or period offsets for different analytical needs.
See below for explanations of the exported functions and how to use them.
Retrieving single values
The library includes three functions that retrieve a single stored value using timestamp, millisecond offset, or period offset search methods:
• `valueAtTime()` – Locates the saved value with the earliest timestamp closest to a specified timestamp.
• `valueAtTimeOffset()` – Finds the saved value with the earliest timestamp closest to the specified number of milliseconds behind the current bar's opening time.
• `valueAtPeriodOffset()` – Finds the saved value with the earliest timestamp closest to the period-based offset behind the current bar's opening time.
Each function has two overloads for advanced and simple use cases. The first overload searches for a value in a user-specified `Data` object created by the `collectData()` function (see below). It returns a tuple containing the found value and the corresponding timestamp.
The second overload maintains a `Data` object internally to store and retrieve values for a specified `source` series. This overload returns a tuple containing the historical `source` value, the corresponding timestamp, and the current bar's `source` value, making it helpful for comparing past and present values from requested contexts.
Retrieving multiple values
The library includes the following functions to retrieve values from multiple historical points in time, facilitating calculations and comparisons with values retrieved across several intervals:
• `getDataAtTimes()` – Locates a past `source` value for each item in a `timestamps` array. Each retrieved value's timestamp represents the earliest time closest to one of the specified timestamps.
• `getDataAtTimeOffsets()` – Finds a past `source` value for each item in a `timeOffsets` array. Each retrieved value's timestamp represents the earliest time closest to one of the specified millisecond offsets behind the current bar's opening time.
• `getDataAtPeriodOffsets()` – Finds a past value for each item in a `periods` array. Each retrieved value's timestamp represents the earliest time closest to one of the specified period offsets behind the current bar's opening time.
Each function returns a tuple with arrays containing the found `source` values and their corresponding timestamps. In addition, the tuple includes the current `source` value and the symbol's description, which also makes these functions helpful for multi-interval comparisons using data from requested contexts.
Processing period inputs
When writing scripts that retrieve historical values based on several user-specified period offsets, the most concise approach is to create a single text input that allows users to list each period, then process the "string" list into an array for use in the `getDataAtPeriodOffsets()` function.
This library includes a `getArrayFromString()` function to provide a simple way to process strings containing comma-separated lists of periods. The function splits the specified `str` by its commas and returns an array containing every non-empty item in the list with surrounding whitespaces removed. View the example code to see how we use this function to process the value of a text area input .
Calculating period offset times
Because the exact amount of time covered by a specified period offset can vary, it is often helpful to verify the resulting times when using the `valueAtPeriodOffset()` or `getDataAtPeriodOffsets()` functions to ensure the calculations work as intended for your use case.
The library's `periodToTimestamp()` function calculates an offset timestamp from a given period and reference time. With this function, programmers can verify the time offsets in a period-based data search and use the calculated offset times in additional operations.
For periods with "D" or "W" units, the function calculates the time offset based on the absolute number of milliseconds the period covers (e.g., `86400000` for "1D"). For periods with "M", "Y", or "YTD" units, the function calculates an offset time based on the reference time's calendar date in the exchange time zone.
Collecting data
All the `getDataAt*()` functions, and the second overloads of the `valueAt*()` functions, collect and maintain data internally, meaning scripts do not require a separate `Data` object when using them. However, the first overloads of the `valueAt*()` functions do not collect data, because they retrieve values from a user-specified `Data` object.
For cases where a script requires a separate `Data` object for use with these overloads or other custom routines, this library exports the `collectData()` function. This function queues each bar's `source` value and opening timestamp into a `Data` object and returns the object's ID.
This function is particularly useful when searching for values from a specific series more than once. For instance, instead of using multiple calls to the second overloads of `valueAt*()` functions with the same `source` argument, programmers can call `collectData()` to store each bar's `source` and opening timestamp, then use the returned `Data` object's ID in calls to the first `valueAt*()` overloads to reduce memory usage.
The `collectData()` function and all the functions that collect data internally include two optional parameters for limiting the saved time-value pairs to a sliding window: `timeOffsetLimit` and `timeframeLimit`. When either has a non-na argument, the function restricts the collected data to the maximum number of recent bars covered by the specified millisecond- and timeframe-based intervals.
NOTE : All calls to the functions that collect data for a `source` series can execute up to once per bar or realtime tick, because each stored value requires a unique corresponding timestamp. Therefore, scripts cannot call these functions iteratively within a loop . If a call to these functions executes more than once inside a loop's scope, it causes a runtime error.
█ EXAMPLE CODE
The example code at the end of the script demonstrates one possible use case for this library's functions. The code retrieves historical price data at user-specified period offsets, calculates price returns for each period from the retrieved data, and then populates a table with the results.
The example code's process is as follows:
1. Input a list of periods – The user specifies a comma-separated list of period strings in the script's "Period list" input (e.g., "1W, 1M, 3M, 1Y, YTD"). Each item in the input list represents a period offset from the latest bar's opening time.
2. Process the period list – The example calls `getArrayFromString()` on the first bar to split the input list by its commas and construct an array of period strings.
3. Request historical data – The code uses a call to `getDataAtPeriodOffsets()` as the `expression` argument in a request.security() call to retrieve the closing prices of "1D" bars for each period included in the processed `periods` array.
4. Display information in a table – On the latest bar, the code uses the retrieved data to calculate price returns over each specified period, then populates a two-row table with the results. The cells for each return percentage are color-coded based on the magnitude and direction of the price change. The cells also include tooltips showing the compared daily bar's opening date in the exchange time zone.
█ NOTES
• This library's architecture relies on a user-defined type (UDT) for its data storage format. UDTs are blueprints from which scripts create objects , i.e., composite structures with fields containing independent values or references of any supported type.
• The library functions search through a `Data` object's `times` array using the array.binary_search_leftmost() function, which is more efficient than looping through collected data to identify matching timestamps. Note that this built-in works only for arrays with elements sorted in ascending order .
• Each function that collects data from a `source` series updates the values and times stored in a local `Data` object's arrays. If a single call to these functions were to execute in a loop , it would store multiple values with an identical timestamp, which can cause erroneous search behavior. To prevent looped calls to these functions, the library uses the `checkCall()` helper function in their scopes. This function maintains a counter that increases by one each time it executes on a confirmed bar. If the count exceeds the total number of bars, indicating the call executes more than once in a loop, it raises a runtime error .
• Typically, when requesting higher-timeframe data with request.security() while using barmerge.lookahead_on as the `lookahead` argument, the `expression` argument should be offset with the history-referencing operator to prevent lookahead bias on historical bars. However, the call in this script's example code enables lookahead without offsetting the `expression` because the script displays results only on the last historical bar and all realtime bars, where there is no future data to leak into the past. This call ensures the displayed results use the latest data available from the context on realtime bars.
Look first. Then leap.
█ EXPORTED TYPES
Data
A structure for storing successive timestamps and corresponding values from a dataset.
Fields:
times (array) : An "int" array containing a UNIX timestamp for each value in the `values` array.
values (array) : A "float" array containing values corresponding to the timestamps in the `times` array.
█ EXPORTED FUNCTIONS
getArrayFromString(str)
Splits a "string" into an array of substrings using the comma (`,`) as the delimiter. The function trims surrounding whitespace characters from each substring, and it excludes empty substrings from the result.
Parameters:
str (series string) : The "string" to split into an array based on its commas.
Returns: (array) An array of trimmed substrings from the specified `str`.
periodToTimestamp(period, referenceTime)
Calculates a UNIX timestamp representing the point offset behind a reference time by the amount of time within the specified `period`.
Parameters:
period (series string) : The period string, which determines the time offset of the returned timestamp. The specified argument must contain a unit and an optional multiplier (e.g., "1Y", "3M", "2W", "YTD"). Supported units are:
- "Y" for years.
- "M" for months.
- "W" for weeks.
- "D" for days.
- "YTD" (Year-to-date) for the span from the start of the `referenceTime` value's year in the exchange time zone. An argument with this unit cannot contain a multiplier.
referenceTime (series int) : The millisecond UNIX timestamp from which to calculate the offset time.
Returns: (int) A millisecond UNIX timestamp representing the offset time point behind the `referenceTime`.
collectData(source, timeOffsetLimit, timeframeLimit)
Collects `source` and `time` data successively across bars. The function stores the information within a `Data` object for use in other exported functions/methods, such as `valueAtTimeOffset()` and `valueAtPeriodOffset()`. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
source (series float) : The source series to collect. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: (Data) A `Data` object containing collected `source` values and corresponding timestamps over the allowed time range.
method valueAtTime(data, timestamp)
(Overload 1 of 2) Retrieves value and time data from a `Data` object's fields at the index of the earliest timestamp closest to the specified `timestamp`. Callable as a method or a function.
Parameters:
data (series Data) : The `Data` object containing the collected time and value data.
timestamp (series int) : The millisecond UNIX timestamp to search. The function returns data for the earliest saved timestamp that is closest to the value.
Returns: ( ) A tuple containing the following data from the `Data` object:
- The stored value corresponding to the identified timestamp ("float").
- The earliest saved timestamp that is closest to the specified `timestamp` ("int").
valueAtTime(source, timestamp, timeOffsetLimit, timeframeLimit)
(Overload 2 of 2) Retrieves `source` and time information for the earliest bar whose opening timestamp is closest to the specified `timestamp`. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
source (series float) : The source series to analyze. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
timestamp (series int) : The millisecond UNIX timestamp to search. The function returns data for the earliest bar whose timestamp is closest to the value.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : (simple string) Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: ( ) A tuple containing the following data:
- The `source` value corresponding to the identified timestamp ("float").
- The earliest bar's timestamp that is closest to the specified `timestamp` ("int").
- The current bar's `source` value ("float").
method valueAtTimeOffset(data, timeOffset)
(Overload 1 of 2) Retrieves value and time data from a `Data` object's fields at the index of the earliest saved timestamp closest to `timeOffset` milliseconds behind the current bar's opening time. Callable as a method or a function.
Parameters:
data (series Data) : The `Data` object containing the collected time and value data.
timeOffset (series int) : The millisecond offset behind the bar's opening time. The function returns data for the earliest saved timestamp that is closest to the calculated offset time.
Returns: ( ) A tuple containing the following data from the `Data` object:
- The stored value corresponding to the identified timestamp ("float").
- The earliest saved timestamp that is closest to `timeOffset` milliseconds before the current bar's opening time ("int").
valueAtTimeOffset(source, timeOffset, timeOffsetLimit, timeframeLimit)
(Overload 2 of 2) Retrieves `source` and time information for the earliest bar whose opening timestamp is closest to `timeOffset` milliseconds behind the current bar's opening time. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
source (series float) : The source series to analyze. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
timeOffset (series int) : The millisecond offset behind the bar's opening time. The function returns data for the earliest bar's timestamp that is closest to the calculated offset time.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: ( ) A tuple containing the following data:
- The `source` value corresponding to the identified timestamp ("float").
- The earliest bar's timestamp that is closest to `timeOffset` milliseconds before the current bar's opening time ("int").
- The current bar's `source` value ("float").
method valueAtPeriodOffset(data, period)
(Overload 1 of 2) Retrieves value and time data from a `Data` object's fields at the index of the earliest timestamp closest to a calculated offset behind the current bar's opening time. The calculated offset represents the amount of time covered by the specified `period`. Callable as a method or a function.
Parameters:
data (series Data) : The `Data` object containing the collected time and value data.
period (series string) : The period string, which determines the calculated time offset. The specified argument must contain a unit and an optional multiplier (e.g., "1Y", "3M", "2W", "YTD"). Supported units are:
- "Y" for years.
- "M" for months.
- "W" for weeks.
- "D" for days.
- "YTD" (Year-to-date) for the span from the start of the current bar's year in the exchange time zone. An argument with this unit cannot contain a multiplier.
Returns: ( ) A tuple containing the following data from the `Data` object:
- The stored value corresponding to the identified timestamp ("float").
- The earliest saved timestamp that is closest to the calculated offset behind the bar's opening time ("int").
valueAtPeriodOffset(source, period, timeOffsetLimit, timeframeLimit)
(Overload 2 of 2) Retrieves `source` and time information for the earliest bar whose opening timestamp is closest to a calculated offset behind the current bar's opening time. The calculated offset represents the amount of time covered by the specified `period`. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
source (series float) : The source series to analyze. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
period (series string) : The period string, which determines the calculated time offset. The specified argument must contain a unit and an optional multiplier (e.g., "1Y", "3M", "2W", "YTD"). Supported units are:
- "Y" for years.
- "M" for months.
- "W" for weeks.
- "D" for days.
- "YTD" (Year-to-date) for the span from the start of the current bar's year in the exchange time zone. An argument with this unit cannot contain a multiplier.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: ( ) A tuple containing the following data:
- The `source` value corresponding to the identified timestamp ("float").
- The earliest bar's timestamp that is closest to the calculated offset behind the current bar's opening time ("int").
- The current bar's `source` value ("float").
getDataAtTimes(timestamps, source, timeOffsetLimit, timeframeLimit)
Retrieves `source` and time information for each bar whose opening timestamp is the earliest one closest to one of the UNIX timestamps specified in the `timestamps` array. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
timestamps (array) : An array of "int" values representing UNIX timestamps. The function retrieves `source` and time data for each element in this array.
source (series float) : The source series to analyze. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: ( ) A tuple of the following data:
- An array containing a `source` value for each identified timestamp (array).
- An array containing an identified timestamp for each item in the `timestamps` array (array).
- The current bar's `source` value ("float").
- The symbol's description from `syminfo.description` ("string").
getDataAtTimeOffsets(timeOffsets, source, timeOffsetLimit, timeframeLimit)
Retrieves `source` and time information for each bar whose opening timestamp is the earliest one closest to one of the time offsets specified in the `timeOffsets` array. Each offset in the array represents the absolute number of milliseconds behind the current bar's opening time. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
timeOffsets (array) : An array of "int" values representing the millisecond time offsets used in the search. The function retrieves `source` and time data for each element in this array. For example, the array ` ` specifies that the function returns data for the timestamps closest to one day and one week behind the current bar's opening time.
source (float) : (series float) The source series to analyze. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: ( ) A tuple of the following data:
- An array containing a `source` value for each identified timestamp (array).
- An array containing an identified timestamp for each offset specified in the `timeOffsets` array (array).
- The current bar's `source` value ("float").
- The symbol's description from `syminfo.description` ("string").
getDataAtPeriodOffsets(periods, source, timeOffsetLimit, timeframeLimit)
Retrieves `source` and time information for each bar whose opening timestamp is the earliest one closest to a calculated offset behind the current bar's opening time. Each calculated offset represents the amount of time covered by a period specified in the `periods` array. Any call to this function cannot execute more than once per bar or realtime tick.
Parameters:
periods (array) : An array of period strings, which determines the time offsets used in the search. The function retrieves `source` and time data for each element in this array. For example, the array ` ` specifies that the function returns data for the timestamps closest to one day, week, and month behind the current bar's opening time. Each "string" in the array must contain a unit and an optional multiplier. Supported units are:
- "Y" for years.
- "M" for months.
- "W" for weeks.
- "D" for days.
- "YTD" (Year-to-date) for the span from the start of the current bar's year in the exchange time zone. An argument with this unit cannot contain a multiplier.
source (float) : (series float) The source series to analyze. The function stores each value in the series with an associated timestamp representing its corresponding bar's opening time.
timeOffsetLimit (simple int) : Optional. A time offset (range) in milliseconds. If specified, the function limits the collected data to the maximum number of bars covered by the range, with a minimum of one bar. If the call includes a non-empty `timeframeLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
timeframeLimit (simple string) : Optional. A valid timeframe string. If specified and not empty, the function limits the collected data to the maximum number of bars covered by the timeframe, with a minimum of one bar. If the call includes a non-na `timeOffsetLimit` value, the function limits the data using the largest number of bars covered by the two ranges. The default is `na`.
Returns: ( ) A tuple of the following data:
- An array containing a `source` value for each identified timestamp (array).
- An array containing an identified timestamp for each period specified in the `periods` array (array).
- The current bar's `source` value ("float").
- The symbol's description from `syminfo.description` ("string").
Periodic
Periodic Linear Regressions [LuxAlgo]The Periodic Linear Regressions (PLR) indicator calculates linear regressions periodically (similar to the VWAP indicator) based on a user-set period (anchor).
This allows for estimating underlying trends in the price, as well as providing potential supports/resistances.
🔶 USAGE
The Periodic Linear Regressions indicator calculates a linear regression over a user-selected interval determined from the selected "Anchor Period".
The PLR can be visualized as a regular linear regression (Static), with a fit readjusting for new data points until the end of the selected period, or as a moving average (Rolling), with new values obtained from the last point of a linear regression fitted over the calculation interval. While the static method line is prone to repainting, it has value since it can further emphasize the linearity of an underlying trend, as well as suggest future trend directions by extrapolating the fit.
Extremities are included in the indicator, these are obtained from the root mean squared error (RMSE) between the price and calculated linear regression. The Multiple setting allows the users to control how far each extremity is from the other.
Periodic Linear Regressions can be helpful in finding support/resistance areas or even opportunities when ranging in a channel.
The anchor - where a new period starts - can be shown (in this case in the top right corner).
The shown bands can be visualized by enabling Show Extremities in settings ( Rolling or Static method).
The script includes a background gradient color option for the bands, which only applies when using the Rolling method.
The indicator colors can be suggestive of the detected trend and are determined as follows:
Method Rolling: a gradient color between red and green indicates the trend; more green if the output is rising, suggesting an uptrend, and more red if it is decreasing, suggesting a downtrend.
Method Static: green if the slope of the line is positive, suggesting an uptrend, red if negative, suggesting a downtrend.
🔶 DETAILS
🔹 Anchor Type
When the Anchor Type is set to Periodic , the indicator will be reset when the "Anchor Period" changes, after which calculations will start again.
An anchored rolling line set at First Bar won't reset at a new session; it will continue calculating the linear regression from the first bar to the last; in other words, every bar is included in the calculation. This can be useful to detect potential long-term tops/bottoms.
Note that a linear regression needs at least two values for its calculation, which explains why you won't see a static line at the first bar of the session. The rolling linear regression will only show from the 3rd bar of the session since it also needs a previous value.
🔹 Rolling/Static
When Anchor Type is set at Periodic , a linear regression is calculated between the first bar of the chosen session and the current bar, aiming to find the line that best fits the dataset.
The example above shows the lines drawn during the session. The offered script, though, shows the last calculated point connected to the previous point when the Rolling method is chosen, while the Static method shows the latest line.
Note that linear regression needs at least two values, which explains why you won't see a static line at the first bar of the session. The rolling line will only show from the 3rd bar of the session since it also needs a previous value.
🔶 SETTINGS
Method: Indicator method used, with options: "Static" (straight line) / "Rolling" (rolling linear regression).
Anchor Type: "Periodic / First Bar" (the latter works only when "Method" is set to "Rolling").
Anchor Period: Only applicable when "Anchor Type" is set at "Periodic".
Source: open, high, low, close, ...
Multiple: Alters the width of the bands when "Show Extremities" is enabled.
Show Extremities: Display one upper and one lower extremity.
🔹 Color Settings
Mono Color: color when "Bicolor" is disabled
Bicolor: Toggle on/off + Colors
Gradient: Background color when "Show extremities" is enabled + level of gradient
🔹 Dashboard
Show Dashboard
Location of dashboard
Text size
Periodic Activity Tracker [LuxAlgo]The Periodic Activity Tracker tool periodically tracks the cumulative buy and sell volume in a user-defined period and draws the corresponding matching bars and volume delta for each period.
Users can select a predefined aggregation period from the following options: Hourly, Daily, Weekly, and Monthly.
🔶 USAGE
This tool provides a simple and clear way of analyzing volumes for each aggregated period and is made up of the following elements:
Buy and sell volumes by period as red and green lines with color gradient area
Delta (difference) between buy & sell volume for each period
Buy & sell volume bars for each period
Separator between lines and bars, and period tags below each pair of bars for ease of reading
On the chart above we can see all the elements displayed, the volume level on the lines perfectly matches the volume level on the bars for each period.
In this case, the tool has the default settings so the anchor period is set to Daily and we can see how the period tag (each day of the week) is displayed below each pair of bars.
Users can disable the delta display and adjust the bar size.
🔹 Reading The Tool
In trading, assessing the strength of the bulls (buyers) and bears (sellers) is key to understanding the current trading environment. Which side, if any, has the upper hand? To answer this question, some traders look at volume in relation to price.
This tool provides you with a view of buy volume versus sell volume, allowing you to compare both sides of the market.
As with any volume tool, the key is to understand when the forces of the two groups are balanced or unbalanced.
As we can observe on the chart:
NOV '23: Buy volume greater than sell volume, both moving up close together, flat delta. We can see that the price is in range.
DEC '23: Buy volume bigger than Sell volume, both moving up but with a bigger difference, bigger delta than last month but still flat. We can see the price in the range above last month's range.
JAN '24: Buy and sell volume tied together, no delta whatsoever. We can see the price in range but testing above and below last month's range.
FEB '24: Buy volume explodes higher and sell volume cannot keep up, big growing delta. Price explodes higher above last month's range.
Traders need to understand that there is always an equal number of buyers and sellers in a liquid market, the quality here is how aggressive or passive they are. Who is 'attacking' and who is 'defending', who is using market orders to move prices, and who is using limit orders waiting to be filled?
This tool gives you the following information:
Lines: if the top line is green, the buyers are attacking, if it is red, the sellers are attacking.
Delta: represents the difference in their strength, if it is above 0 the buyers are stronger, if it is below 0 the sellers are stronger.
Bars: help you to see the difference in strength between buyers and sellers for each period at a glance.
🔹 Anchor Period
By default, the tool is set to Hourly. However, users can select from a number of predefined time periods.
Depending on the user's selection, the bars are displayed as follows:
Hourly : hours of the current day
Daily : days of the current week
Weekly : weeks of the current month
Monthly : months of the current year
On the chart above we can see the four periods displayed, starting at the top left and moving clockwise we have hourly, daily, weekly, and monthly.
🔶 DETAILS
🔹 Chart TimeFrame
The chart timeframe has a direct impact on the visualization of the tool, and the user should select a chart timeframe that is compatible with the Anchor period in the tool's settings panel.
For the chart timeframe to be compatible it must be less than the Anchor period parameter. If the user selects an incompatible chart timeframe, a warning message will be displayed.
As a rule of thumb, the smaller the chart timeframe, the more data the tool will collect, returning indications for longer-term price variations.
These are the recommended chart timeframes for each period:
Hourly : 5m charts or lower
Daily : 1H charts or lower
Weekly : 4H charts or lower
Monthly : 1D charts or lower
🔹 Warnings
This chart shows both types of warnings the user may receive
At the top, we can see the warning that is given when the 'Bar Width' parameter exceeds the allowed value.
At the bottom is the incompatible chart timeframe warning, which prompts the user to select a smaller chart timeframe or a larger "Anchor Period" parameter.
🔶 SETTINGS
🔹 Data Gathering
Anchor period: Time period representing each bar: hours of the day, days of the week, weeks of the month, and months of the year. The timeframe of the chart must be less than this parameter, otherwise a warning will be displayed.
🔹 Style
Bars width: Size of each bar, there is a maximum limit so a warning will be displayed if it is reached.
Volume color
Delta: Enable/Disable Delta Area Display
Volume Forecasting [LuxAlgo]The Volume Forecasting indicator provides a forecast of volume by capturing and extrapolating periodic fluctuations. Historical forecasts are also provided to compare the method against volume at time t .
This script will not work on tickers that do not have volume data.
🔶 SETTINGS
Median Memory: Number of days used to compute the median and first/third quartiles.
Forecast Window: Number of bars forecasted in the future.
Auto Forecast Window: Set the forecast window so that the forecast length completes an interval.
🔶 USAGE
The periodic nature of volume on certain securities allows users to more easily forecast using historical volume. The forecast can highlight intervals where volume tends to be more important, that is where most trading activity takes place.
More pronounced periodicity will tend to return more accurate forecasts.
The historical forecast can also highlight intervals where high/low volume is not expected.
The interquartile range is also highlighted, giving an area where we can expect the volume to lie.
🔶 DETAILS
This forecasting method is similar to the time series decomposition method used to obtain the seasonal component.
We first segment the chart over equidistant intervals. Each interval is delimited by a change in the daily timeframe.
To forecast volume at time t+1 we see where the current bar lies in the interval, if the bar is the 78th in interval then the forecast on the next bar is made by taking the median of the 79th bar over N intervals, where N is the median memory.
This method ensures capturing the periodic fluctuation of volume.
Morphed Sine WaveIntroduction
If you rescale a sine wave to the price you will need to correlate it with it in order to show good results, today i present a different method that does not involve correlation to "morph" a sine wave to the price in order to provide forecast's and highlight market periodic patterns.
Parameters
length control the period of the sine wave, power control the "morphing" amount, if you see for example that the results are going nuts try to increase power , if the results are just the price and the delayed price try to decrease power .
power = 1
power = 100
Those settings might be different depending on which market you are in.
Various Uses
You can do a lot of things with this indicator, use filters as source :
Use the indicator as source for oscillators in order to create cycles indicators :
And certainly many more things
Conclusion
I presented a way to morph a sine wave to the price i order to highlight cycles. You can use any function that return a value between -1 and 1 instead of sin , this can be a scaled rsi/stochastic or correlation coefficient, its up to you :)
If you need help don't hesitate to commend or pm me. I hope you will like the indicator and that it will inspire you to make great things.
Thanks for reading !
Recursive StochasticThe Self Referencing Stochastic Oscillator
The stochastic oscillator bring values in range of (0,100). This process is called Feature scaling or Unity-Based Normalization
When a function use recursion you can highlights cycles or create smoother results depending on various factors, this is the goal of a recursive stochastic.
For example : k = s(alpha*st+(1-alpha)*nz(k )) where st is the target source.
Using inputs with different scale level can modify the result of the indicator depending on which instrument it is applied, therefore the input must be normalized, here the price is first passed through a stochastic, then this result is used for the recursion.
In order to control the level of the recursion, weights are distributed using the alpha parameter. This parameter is in a range of (0,1), if alpha = 1, then the indicator act as a normal stochastic oscillator, if alpha = 0, then the indicator return na since the initial value for k = 0. The smaller the alpha parameter, the lower the correlation between the price and the indicator, but the indicator will look more periodic.
Comparison
Recursive Stochastic oscillator with alpha = 0.1 and bellow a classic oscillator (alpha = 1)
The use of recursion can both smooth the result and make it more reactive as well.
Filter As Source
It is possible to stabilize the indicator and make it less affected by outliers using a filter as input.
Lower alpha can be used in order to recover some reactivity, this will also lead to more periodic results (which are not inevitably correlated with price)
Hope you enjoy
For any questions/demands feel free to pm me, i would be happy to help you
