py-alpha-lib 0.1.0__cp314-abi3-win_amd64.whl

alpha/lang/to_python.py

@@ -0,0 +1,239 @@
+import sys
+from typing import Callable
+from .parser import Lark_StandAlone, Transformer, v_args
+import numpy as np
+import re
+import math
+import io
+
+parser = Lark_StandAlone()
+
+
+class ExecContext:
+  def __call__(self, name: str) -> np.ndarray:
+    pass
+
+
+@v_args(inline=True)
+class AlphaTransformer(Transformer):
+  def __init__(
+    self,
+    name_convertor: Callable[[str], str] | None = None,
+  ):
+    self.name_convertor = name_convertor
+    self.variables = set()
+
+  def start(self, expr):
+    return expr
+
+  def ternary_expr(self, cond, true_case, false_case):
+    return f"np.where({cond}, {true_case}, {false_case})"
+
+  def logical_or_expr(self, left, *rights):
+    result = left
+    for right in rights:
+      result = f"np.bitwise_or({result}, {right})"
+    return result
+
+  def logical_and_expr(self, left, *rights):
+    result = left
+    for right in rights:
+      result = f"np.bitwise_and({result}, {right})"
+    return result
+
+  def eq(self, left, right):
+    return f"{left} == {right}"
+
+  def ne(self, left, right):
+    return f"{left} != {right}"
+
+  def lt(self, left, right):
+    return f"{left} < {right}"
+
+  def gt(self, left, right):
+    return f"{left} > {right}"
+
+  def le(self, left, right):
+    return f"{left} <= {right}"
+
+  def ge(self, left, right):
+    return f"{left} >= {right}"
+
+  def sum(self, first, *rest):
+    result = first
+    it = iter(rest)
+    for op, val in zip(it, it):
+      result = f"{result} {op} {val}"
+    return result
+
+  def product(self, first, *rest):
+    result = first
+    it = iter(rest)
+    for op, val in zip(it, it):
+      result = f"{result} {op} {val}"
+    return result
+
+  def power(self, base, *rest):
+    result = base
+    it = iter(rest)
+    for op, val in zip(it, it):
+      result = f"np.power({result}, {val})"
+    return result
+
+  def neg(self, minus, item):
+    return f"-{item}"
+
+  def func_call(self, name, args=""):
+    # Unwrap ctx('...') if present, because function names shouldn't be wrapped
+    if name.startswith("ctx('") and name.endswith("')"):
+      name = name[5:-2]
+    return f"ctx.{name}({args})"
+
+  def arguments(self, *args):
+    return ", ".join(args)
+
+  def NAME(self, name):
+    name = str(name)
+    if self.name_convertor:
+      name_key = self.name_convertor(name)
+    else:
+      name_key = name
+    self.variables.add(name_key)
+    return f"ctx('{name_key}')"
+
+  def NUMBER(self, name):
+    return str(name)
+
+  def dotted_name(self, *names):
+    real_names = []
+    for n in names:
+      if n.startswith("ctx('") and n.endswith("')"):
+        real_names.append(n[5:-2])
+      else:
+        real_names.append(n)
+
+    full_name = ".".join(real_names)
+
+    # Treating dotted name as a variable access string too, similar to NAME
+    # Assuming dotted names are also data fields provided by ctx
+    if self.name_convertor:
+      key = self.name_convertor(full_name)
+    else:
+      key = full_name
+    self.variables.add(key)
+    return f"ctx('{key}')"
+
+  def add_op(self, op):
+    return str(op)
+
+  def mul_op(self, op):
+    return str(op)
+
+
+def to_python(
+  name: str,
+  code: str,
+  /,
+  indent: int = 0,
+  indent_by: str = "  ",
+  as_function: bool = False,
+  name_convertor: Callable[[str], str] | None = None,
+  optimize: bool = False,
+) -> str:
+  """
+  Convert a parse tree to Python code.
+
+  There are two modes:
+    1. Function mode: Convert the code as a function.
+      - All function arguments are (ctx: ExecContext)
+      - In generated function, convert each variable name to ctx('VARIABLE_NAME') to get the data.
+      - Return the result of the code.
+    2. Variable mode: Convert the code as a variable.
+      - assume there is a global ExecContext variable named 'ctx'
+      - In generated variable, convert each variable name to ctx('VARIABLE_NAME') to get the data.
+
+  Args:
+    name: The name of the target function or variable.
+    code: The code to convert.
+    indent: The init number of spaces to indent the code.
+    indent_by: The string to use for indentation.
+    as_function: Whether to convert the code as a function or a variable.
+    name_convertor: A optional function to convert the identifier name in the code. For example, 'to_lower_case' or 'to_snake_case'.
+    optimize: In function mode, optimize the code by declare variables when multiple times used.
+
+  Returns:
+    The converted code.
+  """
+  if not code.strip():
+    return ""
+
+  try:
+    tree = parser.parse(code)
+  except Exception as e:
+    raise ValueError(f"Failed to parse code: {code}") from e
+
+  transformer = AlphaTransformer(name_convertor=name_convertor)
+  converted_expr = transformer.transform(tree)
+
+  indent_str = indent_by * indent
+
+  if as_function:
+    lines = []
+    lines.append(f"{indent_str}def {name}(ctx):")
+
+    body_indent = indent_str + indent_by
+
+    if optimize:
+      # Count occurrences
+      var_usage = {}
+      for var in transformer.variables:
+        pattern = re.escape(f"ctx('{var}')")
+        count = len(re.findall(pattern, converted_expr))
+        var_usage[var] = count
+
+      # Sort variables to ensure consistent output
+      sorted_vars = sorted([v for v, c in var_usage.items() if c > 1])
+
+      for var in sorted_vars:
+        safe_var_name = "_" + var.replace(".", "_")  # simple safe name
+        lines.append(f"{body_indent}{safe_var_name} = ctx('{var}')")
+        # Replace in expression
+        converted_expr = converted_expr.replace(f"ctx('{var}')", safe_var_name)
+
+    lines.append(f"{body_indent}return {converted_expr}")
+    return "\n".join(lines)
+  else:
+    return f"{indent_str}{name} = {converted_expr}"
+
+
+def to_python_file(
+  codes: list[str],
+  names: list[str] | str = "alpha_",
+  /,
+  fp: io.StringIO | None = None,
+  imports: list[str] | None = [],
+  name_convertor: Callable[[str], str] | None = None,
+):
+  if isinstance(names, str):
+    n = len(codes)
+    w = math.ceil(math.log10(n))
+    names = [f"{names}{i + 1:0{w}d}" for i in range(n)]
+
+  assert len(names) == len(codes)
+
+  if fp is None:
+    fp = sys.stdout
+
+  for i in imports:
+    print(f"{i}", file=fp)
+
+  if "import numpy as np" not in imports:
+    print("import numpy as np", file=fp)
+
+  for name, code in zip(names, codes):
+    print(f"# {code}", file=fp)
+    py_code = to_python(
+      name, code, as_function=True, optimize=True, name_convertor=name_convertor
+    )
+    print(py_code, file=fp)
+    print("\n\n", file=fp)

py_alpha_lib-0.1.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: py-alpha-lib
+Version: 0.1.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Dist: numpy>=2
+License-File: LICENSE
+Summary: Alpha Library: A high-performance rolling window calculation library implemented in Rust with Python bindings. Used for financial data analysis and factor research.
+Author: LiJia
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# Introduction
+
+`alpha-lib` is a Python library that implements various algorithms and functions commonly used in quantitative finance and algorithmic trading.
+
+For financial data analysis, there are many algorithms required a rolling window calculation. This library provides efficient implementations of these algorithms.
+
+## Algorithms
+
+| Name       | Description                                                  | Ref Link                                                                |
+| ---------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| BARSLAST   | Bars since last condition true                               | https://www.amibroker.com/guide/afl/barslast.html                       |
+| BARSSINCE  | Bars since first condition true                              | https://www.amibroker.com/guide/afl/barssince.html                      |
+| COUNT      | Count periods where condition is true                        | https://www.amibroker.com/guide/afl/count.html                          |
+| CROSS      | CROSS(A, B): Previous A < B, Current A >= B                  | https://www.amibroker.com/guide/afl/cross.html                          |
+| DMA        | Exponential Moving Average                                   | https://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average |
+| HHV        | Highest High Value                                           | https://www.amibroker.com/guide/afl/hhv.html                            |
+| HHVBARS    | Bars since Highest High Value                                | https://www.amibroker.com/guide/afl/hhvbars.html                        |
+| LLV        | Lowest Low Value                                             | https://www.amibroker.com/guide/afl/llv.html                            |
+| LLVBARS    | Bars since Lowest Low Value                                  | https://www.amibroker.com/guide/afl/llvbars.html                        |
+| LONGCROSS  | LONGCROSS(A,B,N): Previous N A < B, Current A >= B           |                                                                         |
+| MA         | Moving Average                                               | https://en.wikipedia.org/wiki/Moving_average#Simple_moving_average      |
+| RANK       | rank by group dim                                            |                                                                         |
+| RCROSS     | RCROSE(A, B): Previous A > B, Current A <= B                 |                                                                         |
+| REF        | Reference to value N periods ago                             | https://www.amibroker.com/guide/afl/ref.html                            |
+| RLONGCROSS | RLONGCROSS(A,B,N): Previous N A > B, Current A <= B          |                                                                         |
+| SMA        | Exponential Moving Average (variant of EMA)                  | https://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average |
+| SUM        | Sum of value N periods ago                                   | https://www.amibroker.com/guide/afl/sum.html                            |
+| SUMBARS    | Sums X backwards until the sum is greater than or equal to A | https://www.amibroker.com/guide/afl/sumbars.html                        |
+| TS_RANK    | rank by ts dim                                               |
+
+# Usage
+
+## Installation
+
+You can install the library using pip:
+
+```bash
+pip install py-alpha-lib
+```
+
+## Simple Example
+
+```python
+import alpha as al
+import numpy as np
+
+data = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], dtype=np.float64)
+
+# Calculate 3-period moving average, note that first 2 values are average of available values
+result = al.MA(data, 3)
+print(result)
+# Output: [1.  1.5 2.  3.  4.  5.  6.  7.  8.  9. ]
+
+# Calculate 3-period exponential moving average, first 2 values are NaN
+al.set_ctx(flags=al.FLAG_STRICTLY_CYCLE)
+result = al.EMA(data, 3)
+print(result)
+# Output: [ nan  nan 2.  3.  4.  5.  6.  7.  8.  9. ]
+
+# Calculate 3-period exponential moving average, skipping NaN values
+al.set_ctx(flags=al.FLAG_SKIP_NAN)
+data_with_nan = [1, 2, None, 4, 5, 6, 7, 8, 9, 10]
+result = al.MA(data_with_nan, 3)
+print(result)
+# Output: [1.  1.5 2.5 3.5 4.5 5.5 6.5 7.5 8.5 9.5]
+```
+
+## Environment Context
+
+You may notice that some functions have different behaviors based on the context settings. You can set the context using `al.set_ctx()` function. The context includes:
+
+- `groups`: Number of groups to divide the data into for group-wise operations. `groups` used calculations multiple stocks(for example) in a single array.
+  - Each group is assumed to be of equal size and contiguous in the input array.
+  - Each group is processed paralleled and independently. This is why the performance is very good.
+  - For `rank` function, groups is required to be set greater than 1. Because rank is a group-wise operation.
+- `start`: The starting index for calculations.
+  - For some case, this may reduce unnecessary computations.
+  - Default is 0.
+- `flags`: Additional flags to modify function behaviors.
+  - `FLAG_SKIP_NAN`: When this flag is set, functions will skip NaN values during computations.
+  - `FLAG_STRICTLY_CYCLE`: When this flag is set, functions will strictly cycle over the data, meaning that initial periods that do not have enough data will be filled with NaN.
+  - You can combine multiple flags using bitwise OR operation, e.g., `flags=FLAG_SKIP_NAN | FLAG_STRICTLY_CYCLE`.
+
+## Factor expression to Python code
+
+You can convert factor expressions to Python code using the `lang` module. For example:
+
+```bash
+python -m alpha.lang examples/wq101/alpha101.txt
+```
+
+This will read the factor expressions from [`examples/wq101/alpha101.txt`](examples/wq101/alpha101.txt) and generate corresponding Python code using `alpha-lib` functions.
+
+After generating the code, you may need to adjust the code
+
+- Fix type conversions between `float` and `bool`.
+- Add context settings if needed.
+
+# Full Example
+
+## WorldQuant 101 famous alpha 101
+
+[The WorldQuant 101 alpha factors](https://arxiv.org/pdf/1601.009913.pdf) are a set of quantitative trading signals developed by WorldQuant. There are some implementations of these alpha factors, for example:
+[DolphinDB implementation: ](https://github.com/dolphindb/DolphinDBModules/blob/master/wq101alpha/README.md), it provides 101 alpha factors implemented in DolphinDB language also with comparative `pandas` based Python implementation. It's a good starting point for comparing with our `alpha-lib`.
+
+The full implementation of these 101 alpha factors using `alpha-lib` can be found in the [wq101](examples/wq101) folder of this repository. This implementation leverages the efficient algorithms provided by `alpha-lib` to compute the alpha factors.
+
+- `al`: is the factor implemented using `alpha-lib`.
+- `pd_`: is the factor implemented using `pandas` for comparison.
+- Because we can not setup the full featured DolphinDB environment here, we just use it's results.
+
+### Run the example
+
+Show help message:
+
+```
+$ examples/wq101/main.py --help
+usage: main.py [-h] [-s START] [-e END] [-v] [-d DATA] [-o OUTPUT] [--with-pd] [--with-al] [no ...]
+
+positional arguments:
+  no                    alpha numbers to run, e.g., 1 2 3
+
+options:
+  -h, --help            show this help message and exit
+  -s, --start START     start alpha number
+  -e, --end END         end alpha number
+  -v, --verbose         enable verbose logging
+  -d, --data DATA       data file path
+  -o, --output OUTPUT   save output to file
+  --with-pd             run pandas implementation
+  --with-al             run alpha-lib implementation
+```
+
+```bash
+# Run specific alpha factors both pandas and alpha-lib implementations
+examples/wq101/main.py --with-pd --with-al 1 2 3 4
+
+# Run a range of alpha factors using alpha-lib implementation
+examples/wq101/main.py --with-al -s 1 -e 102
+
+```
+
+Because the `pandas` implementation is too slow for some factors, below is a 1~14 factors (`examples/wq101/main.py --with-al -s 1 -e 15`) run time comparison on a sample dataset with 4000 stocks and 261 trading days, total 1,044,000 factors to compute for each factor.
+
+The _pandas/DolphinDB_ is copied from the [DolphinDB implementation result](https://github.com/dolphindb/DolphinDBModules/blob/master/wq101alpha/README.md#31-dolphindb-vs-python-pandas)
+
+The `Value` columns are used to verify the correctness of the implementations, they should be the same or very close.
+
+The hardware/soft environment is:
+
+- CPU: Intel 13th Gen Core i7-13700K (16 cores, 24 threads)
+- RAM: 32GB
+- OS: Ubuntu 22.04 LTS
+- Python: 3.14 without free-threading
+- pandas: 3.0
+- numpy: 2.4
+
+| no   | pandasTime(ms) | alphaLibTime(ms) | SpeedUp<br/>(pandas/alphaLib) | SpeedUp<br/>(pandas/DolphinDB) | pandasValue | alphaLibValue |
+| ---- | -------------- | ---------------- | ----------------------------- | ------------------------------ | ----------- | ------------- |
+| data | 11396          | 718              | 15                            |                                |             |               |
+| #001 | 14231          | 7                | 2033                          | 800                            | 0.182125    | 0.182125      |
+| #002 | 465            | 14               | 33                            | 9                              | -0.64422    | -0.326332     |
+| #003 | 430            | 8                | 53                            | 14                             | 0.236184    | 0.236184      |
+| #004 | 55107          | 6                | 9184                          | 1193                           | -8          | -8            |
+| #005 | 105            | 9                | 11                            | 5                              | -0.331333   | -0.331333     |
+| #006 | 351            | 2                | 175                           | 84                             | 0.234518    | 0.234518      |
+| #007 | 43816          | 17               | 2577                          | 486                            | -1          | -1            |
+| #008 | 222            | 9                | 24                            | 14                             | -0.6435     | -0.6435       |
+| #009 | 97             | 9                | 10                            | 14                             | 17.012321   | 17.012321     |
+| #010 | 145            | 11               | 13                            | 6                              | 0.662       | 0.662         |
+| #011 | 158            | 10               | 15                            | 6                              | 0.785196    | 0.892723      |
+| #012 | 4              | 4                | 1                             | 0.7                            | -17.012321  | -17.012321    |
+| #013 | 446            | 9                | 49                            | 8                              | -0.58       | -0.58         |
+| #014 | 398            | 8                | 49                            | 18                             | 0.095449    | 0.095449      |
+

py_alpha_lib-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+alpha\__init__.py,sha256=rZE0P-d0AT7YG624RuE_EPdwIGKOHz2RMPn6Z-nTu9o,171
+alpha\algo\__init__.py,sha256=F8t1XUjla37_0x-fjGL4HXTZASmSYLotWQbfdOhdfh0,76
+alpha\algo\_algo.pyd,sha256=MK1Nk-4xQngkixcZcQiLLzmKLC5NPE3ZTmDXa3XF4LU,2076672
+alpha\algo\algo.md,sha256=KZjYakkAkTLx4iPDj7hcVZEVv7Fc7Ye9h-zdz7JB7rI,1929
+alpha\algo\algo.py,sha256=Y0R13cZ7uigtsobYd4wo9vtMlPJRwL0ktwPp6GPl0xc,602
+alpha\algo\algo_gen.py,sha256=hSc8c8yJrGcNnZohc56TgJj_7V6Bcxnf_7K04mOiSYc,12269
+alpha\algo.md,sha256=Av1UP0Tj7RHaksHD-0kM4uvppXyvDMlyEQZ6CG7PNYY,3521
+alpha\lang\__init__.py,sha256=JdMw9vZv-4CQgChVfMxIYwpb5pQsYc9d_GleocYfFg4,50
+alpha\lang\__main__.py,sha256=aemLHkuKarwc2x8aejCWBpFsYY49NzQOUhHcUFf19BE,490
+alpha\lang\alpha.lark,sha256=qqMXJ--F3ErYikNdRs1vwHGKoJe_aRUeNmpo87NaTXs,1046
+alpha\lang\parser.py,sha256=WBpwEUYzGJ1nM7iUh_mEimGLhHzVZXS8BAzF58ZRagU,156846
+alpha\lang\to_python.py,sha256=G-bcISR1ItW6AxfccuEZo-xwukl-TtVLgmo3n2nnrPE,6579
+py_alpha_lib-0.1.0.dist-info\METADATA,sha256=clwi8ljMxqv3YKDgmCaufgZ6-jPOpwnndEKSY8jI7vw,11880
+py_alpha_lib-0.1.0.dist-info\WHEEL,sha256=dsg5IA1tFdLNsJihRQJCX59s7GKfDG9N_2EOwwysnks,96
+py_alpha_lib-0.1.0.dist-info\licenses\LICENSE,sha256=3D2Y67XRAnMSiByf02r4DaFv92CdDLw5U6xHyUVkdI4,1289
+py_alpha_lib-0.1.0.dist-info\RECORD,,

py_alpha_lib-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.11.5)
+Root-Is-Purelib: false
+Tag: cp314-abi3-win_amd64

py_alpha_lib-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+# BSD 2-Clause License
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.