Add williams percent range indicator

Author: MDUYN

README.md

@@ -33,6 +33,7 @@ pip install pyindicators
 * [Momentum indicators](#momentum-indicators)
   * [Relative Strength Index (RSI)](#relative-strength-index-rsi)
   * [Relative Strength Index Wilders method (Wilders RSI)](#wilders-relative-strength-index-wilders-rsi)
+  * [Williams %R](#williams-r)
 * [Indicator helpers](#indicator-helpers)
   * [Crossover](#crossover)
   * [Is Crossover](#is-crossover)
@@ -213,7 +214,48 @@ pd_df = wilders_rsi(pd_df, source_column="Close", period=14, result_column="RSI_
 pd_df.tail(10)
 ```
 
-![RSI](https://github.com/coding-kitties/PyIndicators/blob/main/static/images/indicators/wilders_rsi.png)
+![wilders_RSI](https://github.com/coding-kitties/PyIndicators/blob/main/static/images/indicators/wilers_rsi.png)
+
+#### Williams %R
+
+Williams %R (Williams Percent Range) is a momentum indicator used in technical analysis to measure overbought and oversold conditions in a market. It moves between 0 and -100 and helps traders identify potential reversal points.
+
+
+```python
+def willr(
+    data: Union[pd.DataFrame, pl.DataFrame],
+    period: int = 14,
+    result_column: str = None,
+    high_column: str = "High",
+    low_column: str = "Low",
+    close_column: str = "Close"
+) -> Union[pd.DataFrame, pl.DataFrame]:
+```
+
+Example
+
+```python
+from investing_algorithm_framework import CSVOHLCVMarketDataSource
+
+from pyindicators import willr
+
+# For this example the investing algorithm framework is used for dataframe creation,
+csv_path = "./tests/test_data/OHLCV_BTC-EUR_BINANCE_15m_2023-12-01:00:00_2023-12-25:00:00.csv"
+data_source = CSVOHLCVMarketDataSource(csv_file_path=csv_path)
+
+pl_df = data_source.get_data()
+pd_df = data_source.get_data(pandas=True)
+
+# Calculate Williams%R for Polars DataFrame
+pl_df = willr(pl_df, result_column="WILLR")
+pl_df.show(10)
+
+# Calculate Williams%R for Pandas DataFrame
+pd_df = willr(pd_df, result_column="WILLR")
+pd_df.tail(10)
+```
+
+![williams %R](https://github.com/coding-kitties/PyIndicators/blob/main/static/images/indicators/willr.png)
 
 ### Indicator helpers
 

pyindicators/__init__.py

@@ -1,5 +1,5 @@
 from .indicators import sma, rsi, is_crossover, crossunder, ema, wilders_rsi, \
-    crossover, is_crossover, wma, macd
+    crossover, is_crossover, wma, macd, willr
 
 __all__ = [
     'sma',
@@ -11,5 +11,6 @@
     'ema',
     'rsi',
     "wilders_rsi",
-    'macd'
+    'macd',
+    'willr'
 ]

pyindicators/indicators/__init__.py

@@ -5,6 +5,7 @@
 from .exponential_moving_average import ema
 from .rsi import rsi, wilders_rsi
 from .macd import macd
+from .williams_percent_range import willr
 
 __all__ = [
     'sma',
@@ -15,5 +16,6 @@
     'ema',
     'rsi',
     'wilders_rsi',
-    'macd'
+    'macd',
+    'willr'
 ]

pyindicators/indicators/rsi.py

@@ -6,7 +6,7 @@
 def rsi(
     data: Union[pd.DataFrame, pl.DataFrame],
     source_column: str,
-    period: int,
+    period: int = 14,
     result_column: str = None,
 ) -> Union[pd.DataFrame, pl.DataFrame]:
     """
@@ -81,7 +81,7 @@ def rsi(
 def wilders_rsi(
     data: Union[pd.DataFrame, pl.DataFrame],
     source_column: str,
-    period: int,
+    period: int = 14,
     result_column: str = None,
 ) -> Union[pd.DataFrame, pl.DataFrame]:
     """

pyindicators/indicators/williams_percent_range.py

@@ -0,0 +1,68 @@
+from typing import Union
+import pandas as pd
+import polars as pl
+from pyindicators.exceptions import PyIndicatorException
+
+
+def willr(
+    data: Union[pd.DataFrame, pl.DataFrame],
+    period: int = 14,
+    result_column: str = None,
+    high_column: str = "High",
+    low_column: str = "Low",
+    close_column: str = "Close"
+) -> Union[pd.DataFrame, pl.DataFrame]:
+    """
+    Function to calculate the Williams %R indicator of a series.
+
+    Args:
+        data (Union[pd.DataFrame, pl.DataFrame]): The input data.
+        source_column (str): The name of the series.
+        period (int): The period for the Williams %R calculation.
+        result_column (str, optional): The name of the column to store
+        the Williams %R values. Defaults to None, which means it will
+        be named "WilliamsR_{period}".
+
+    Returns:
+        Union[pd.DataFrame, pl.DataFrame]: The DataFrame with
+        the Williams %R column added.
+    """
+
+    # Check if the high and low columns are present
+    if high_column not in data.columns:
+        raise PyIndicatorException(
+            f"Column '{high_column}' not found in DataFrame"
+        )
+
+    if low_column not in data.columns:
+        raise PyIndicatorException(
+            f"Column '{low_column}' not found in DataFrame"
+        )
+
+    if isinstance(data, pd.DataFrame):
+        data["high_n"] = data[high_column]\
+            .rolling(window=period, min_periods=1).max()
+        data["low_n"] = data[low_column]\
+            .rolling(window=period, min_periods=1).min()
+        data[result_column] = ((data["high_n"] - data[close_column]) /
+                               (data["high_n"] - data["low_n"])) * -100
+        return data.drop(columns=["high_n", "low_n"])
+
+    elif isinstance(data, pl.DataFrame):
+        high_n = data.select(pl.col(high_column).rolling_max(period).alias("high_n"))
+        low_n = data.select(pl.col(low_column).rolling_min(period).alias("low_n"))
+
+        data = data.with_columns([
+            high_n["high_n"],
+            low_n["low_n"]
+        ])
+        data = data.with_columns(
+            ((pl.col("high_n") - pl.col(close_column)) /
+             (pl.col("high_n") - pl.col("low_n")) * -100).alias(result_column)
+        )
+        return data.drop(["high_n", "low_n"])
+
+    else:
+        raise PyIndicatorException(
+            "Unsupported data type. Must be pandas or polars DataFrame."
+        )