qutePandas 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

qutePandas/core/display.py

@@ -0,0 +1,183 @@
+import pykx as kx
+import pandas as _pd
+import builtins
+
+def py(obj):
+    """
+    Converts a PyKX object to its Python equivalent.
+
+    Parameters
+    ----------
+    obj : pykx.K
+        The PyKX object to convert.
+
+    Returns
+    -------
+    any
+        The Python equivalent of the PyKX object.
+    """
+    try:
+        return obj.py()
+    except Exception as e:
+        raise RuntimeError(f"Failed to convert PyKX object to Python: {e}")
+
+def np(obj):
+    """
+    Converts a PyKX object to a NumPy array.
+
+    Parameters
+    ----------
+    obj : pykx.K
+        The PyKX object to convert.
+
+    Returns
+    -------
+    numpy.ndarray
+        The NumPy array equivalent.
+    """
+    try:
+        return obj.np()
+    except Exception as e:
+        raise RuntimeError(f"Failed to convert PyKX object to NumPy: {e}")
+
+def pd(obj):
+    """
+    Converts a PyKX object to a Pandas DataFrame or Series.
+
+    Parameters
+    ----------
+    obj : pykx.K
+        The PyKX object to convert.
+
+    Returns
+    -------
+    pandas.DataFrame or pandas.Series
+        The Pandas equivalent.
+    """
+    try:
+        return obj.pd()
+    except Exception as e:
+        raise RuntimeError(f"Failed to convert PyKX object to Pandas: {e}")
+
+def pa(obj):
+    """
+    Converts a PyKX object to a PyArrow Table.
+
+    Parameters
+    ----------
+    obj : pykx.K
+        The PyKX object to convert.
+
+    Returns
+    -------
+    pyarrow.Table
+        The PyArrow equivalent.
+    """
+    try:
+        return obj.pa()
+    except Exception as e:
+        raise RuntimeError(f"Failed to convert PyKX object to PyArrow: {e}")
+
+def pt(obj):
+    """
+    Converts a PyKX object to a PyTorch Tensor.
+
+    Parameters
+    ----------
+    obj : pykx.K
+        The PyKX object to convert.
+
+    Returns
+    -------
+    torch.Tensor
+        The PyTorch equivalent.
+    """
+    try:
+        return obj.pt()
+    except Exception as e:
+        raise RuntimeError(f"Failed to convert PyKX object to PyTorch: {e}")
+
+def print(obj, head=None, tail=None):
+    """
+    Prints a PyKX table in a formatted ASCII box.
+
+    Parameters
+    ----------
+    obj : pykx.Table or pykx.KeyedTable
+        The table to print.
+    head : int, optional
+        Number of rows to show from the beginning.
+    tail : int, optional
+        Number of rows to show from the end.
+    """
+    try:
+        if isinstance(obj, _pd.DataFrame):
+            if len(obj.columns) == 0:
+                builtins.print("Empty DataFrame")
+                return
+
+        if isinstance(obj, kx.Dictionary):
+            try:
+                is_empty = kx.q('{(0=count key x) and (0=count value x)}', obj).py()
+                if is_empty:
+                    builtins.print("Empty DataFrame")
+                    return
+                else:
+                     builtins.print(obj)
+                     return
+            except:
+                 builtins.print(obj)
+                 return
+
+        if isinstance(obj, (kx.Table, kx.KeyedTable)):
+            if head is not None:
+                table = kx.q('{[t;n] n sublist t}', obj, head)
+            elif tail is not None:
+                table = kx.q('{[t;n] neg[n] sublist t}', obj, tail)
+            else:
+                table = obj
+            
+            cols = kx.q('cols', table).py()
+            if len(cols) == 0:
+                builtins.print("Empty Table")
+                return
+            
+            rows_data = []
+            for col in cols:
+                col_data = kx.q('{[t;c] t[c]}', table, col).py()
+                rows_data.append(col_data)
+            
+            num_rows = len(rows_data[0]) if rows_data else 0
+            
+            col_widths = []
+            for i, col in enumerate(cols):
+                max_width = len(str(col))
+                for j in range(num_rows):
+                    val_width = len(str(rows_data[i][j]))
+                    max_width = max(max_width, val_width)
+                col_widths.append(max_width)
+            
+            def format_row(values):
+                parts = []
+                for val, width in zip(values, col_widths):
+                    parts.append(str(val).ljust(width))
+                return "│ " + " │ ".join(parts) + " │"
+            
+            total_width = sum(col_widths) + 3 * len(cols) + 1
+            top_border = "┌" + "┬".join("─" * (w + 2) for w in col_widths) + "┐"
+            mid_border = "├" + "┼".join("─" * (w + 2) for w in col_widths) + "┤"
+            bot_border = "└" + "┴".join("─" * (w + 2) for w in col_widths) + "┘"
+            
+            builtins.print(top_border)
+            builtins.print(format_row(cols))
+            builtins.print(mid_border)
+            
+            for row_idx in range(num_rows):
+                row_values = [rows_data[col_idx][row_idx] for col_idx in range(len(cols))]
+                builtins.print(format_row(row_values))
+            
+            builtins.print(bot_border)
+        else:
+            builtins.print(obj)
+    except Exception as e:
+        raise RuntimeError(f"Failed to print table: {e}")

qutePandas/grouping/__init__.py

@@ -0,0 +1,4 @@
+from .groupby_sum import groupby_sum
+from .groupby_avg import groupby_avg
+
+__all__ = ['groupby_sum', 'groupby_avg'] 

qutePandas/grouping/groupby_avg.py

@@ -0,0 +1,39 @@
+import pykx as kx
+import pandas as pd
+from ..utils import _ensure_q_table, _handle_return, _validate_columns
+
+
+def groupby_avg(df, by_cols, avg_col, return_type='q'):
+    """
+    Groups table by specified column(s) and averages target column.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame or pykx.Table
+        Input DataFrame.
+    by_cols : str or list of str
+        Group by column(s).
+    avg_col : str
+        Column to average.
+    return_type : str, default 'q'
+        Desired return type ('p' or 'q').
+
+    Returns
+    -------
+    pandas.DataFrame or pykx.Table
+        Grouped and averaged DataFrame.
+    """
+    try:
+        q_table = _ensure_q_table(df)
+        if isinstance(by_cols, str):
+            by_cols = [by_cols]
+        
+        _validate_columns(q_table, by_cols + [avg_col])
+        by_clause = ",".join(by_cols)
+        
+        keyed_result = kx.q(f"{{select avg {avg_col} by {by_clause} from x}}", q_table)
+        result = kx.q("{0!x}", keyed_result)
+        return _handle_return(result, return_type)
+    except Exception as e:
+        raise RuntimeError(f"Failed to group by avg: {e}")
+ 

qutePandas/grouping/groupby_sum.py

@@ -0,0 +1,40 @@
+import pykx as kx
+import pandas as pd
+from ..utils import _ensure_q_table, _handle_return, _validate_columns
+
+
+def groupby_sum(df, by_cols, sum_col, return_type='q'):
+    """
+    Groups table by specified column(s) and sums target column.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame or pykx.Table
+        Input DataFrame.
+    by_cols : str or list of str
+        Group by column(s).
+    sum_col : str
+        Column to sum.
+    return_type : str, default 'q'
+        Desired return type ('p' or 'q').
+
+    Returns
+    -------
+    pandas.DataFrame or pykx.Table
+        Grouped and summed DataFrame.
+    """
+    try:
+        q_table = _ensure_q_table(df)
+        if isinstance(by_cols, str):
+            by_cols = [by_cols]
+        
+        _validate_columns(q_table, by_cols + [sum_col])
+        by_clause = ",".join(by_cols)
+        
+        keyed_result = kx.q(f"{{select sum {sum_col} by {by_clause} from x}}", q_table)
+        result = kx.q("{0!x}", keyed_result)
+        
+        return _handle_return(result, return_type)
+    except Exception as e:
+        raise RuntimeError(f"Failed to group by sum: {e}")
+ 

qutePandas/indexing/__init__.py

@@ -0,0 +1,3 @@
+
+from .loc import loc
+from .iloc import iloc

qutePandas/indexing/iloc.py

@@ -0,0 +1,73 @@
+import pykx as kx
+from ..utils import _ensure_q_table, _handle_return, _validate_columns
+
+def iloc(df, rows=None, cols=None, return_type='q'):
+    """
+    Pure integer-location based indexing for selection by position.
+    
+    Parameters
+    ----------
+    df : pykx.Table or pd.DataFrame
+        Input data.
+    rows : int, list, slice, or None
+        Row indices to select.
+    cols : int, list, slice, or None
+        Column indices to select.
+    return_type : str, default 'q'
+        'q' for pykx.Table, 'p' for pandas DataFrame.
+        
+    Returns
+    -------
+    pykx.Table or pd.DataFrame
+        Subset of the inputs.
+    """
+    table = _ensure_q_table(df)
+    
+    count = kx.q("count", table).py()
+    all_cols = kx.q("cols", table).py()
+    
+    if rows is None:
+        row_indices = None
+    elif isinstance(rows, int):
+        q_rows = rows
+        if q_rows < 0: q_rows += count
+        row_indices = [q_rows]
+    elif isinstance(rows, slice):
+        row_indices = list(range(*rows.indices(count)))
+    else:
+        row_indices = list(rows)
+        row_indices = [r + count if r < 0 else r for r in row_indices]
+
+    if cols is None:
+        target_cols = None
+    else:
+        if isinstance(cols, int):
+            target_cols = [all_cols[cols]]
+        elif isinstance(cols, slice):
+            target_cols = [all_cols[i] for i in range(*cols.indices(len(all_cols)))]
+        else:
+            target_cols = [all_cols[i] for i in cols]
+            
+    if row_indices is None and target_cols is None:
+        return _handle_return(table, return_type)
+
+    if row_indices is not None and target_cols is not None:
+        q_query = '{?[x y;();0b;z]}'
+        syms = kx.SymbolVector(target_cols)
+        cols_dict = kx.q('!', syms, syms)
+        q_res = kx.q(q_query, table, kx.LongVector(row_indices), cols_dict)
+        
+    elif row_indices is not None:
+        q_query = '{x y}'
+        q_res = kx.q(q_query, table, kx.LongVector(row_indices))
+        
+    elif target_cols is not None:
+        q_query = '{?[x;();0b;y]}'
+        syms = kx.SymbolVector(target_cols)
+        cols_dict = kx.q('!', syms, syms)
+        q_res = kx.q(q_query, table, cols_dict)
+        
+    else:
+        q_res = table
+
+    return _handle_return(q_res, return_type)

qutePandas/indexing/loc.py

@@ -0,0 +1,53 @@
+import pykx as kx
+from ..utils import _ensure_q_table, _handle_return, _validate_columns
+
+def loc(df, rows=None, cols=None, return_type='q'):
+    """
+    Pure label-location based indexing for selection by label (or boolean array).
+    
+    Parameters
+    ----------
+    df : pykx.Table or pd.DataFrame
+        Input data.
+    rows : list of bool, pykx.BooleanVector, or None
+        Boolean mask for row selection.
+    cols : str, list of str, or None
+        Column names to select.
+    return_type : str, default 'q'
+        'q' for pykx.Table, 'p' for pandas DataFrame.
+        
+    Returns
+    -------
+    pykx.Table or pd.DataFrame
+        Subset of the inputs.
+    """
+    table = _ensure_q_table(df)
+    
+    q_rows = None
+    if rows is not None:
+        if isinstance(rows, list):
+            q_rows = kx.toq(rows)
+        else:
+            q_rows = rows
+             
+    q_cols = None
+    if cols is not None:
+        if isinstance(cols, str):
+            cols = [cols]
+        _validate_columns(table, cols)
+        syms = kx.SymbolVector(cols)
+        q_cols = kx.q('!', syms, syms)
+        
+    if q_rows is not None and q_cols is not None:
+        q_res = kx.q("{?[x;enlist y;0b;z]}", table, q_rows, q_cols)
+        
+    elif q_rows is not None:
+        q_res = kx.q("{?[x;enlist y;0b;()]}", table, q_rows)
+        
+    elif q_cols is not None:
+        q_res = kx.q("{?[x;();0b;y]}", table, q_cols)
+        
+    else:
+        q_res = table
+        
+    return _handle_return(q_res, return_type)

qutePandas/introspection/dtypes.py

@@ -0,0 +1,25 @@
+import pykx as kx
+from ..utils import _ensure_q_table, _handle_return
+
+def dtypes(df, return_type='q'):
+    """
+    Returns the data types of each column in the DataFrame.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame or pykx.Table
+        Input DataFrame.
+    return_type : str, default 'q'
+        Desired return type ('p' or 'q').
+
+    Returns
+    -------
+    pykx.MetaTable or pandas.DataFrame
+        Table containing column names and their kdb+ types.
+    """
+    try:
+        q_table = _ensure_q_table(df)
+        res = kx.q("{meta x}", q_table)
+        return _handle_return(res, return_type)
+    except Exception as e:
+        raise RuntimeError(f"Failed to retrieve data types: {e}")

qutePandas/io/__init__.py

@@ -0,0 +1,4 @@
+from .to_csv import to_csv
+from .from_csv import from_csv
+
+__all__ = ['to_csv', 'from_csv'] 

qutePandas/io/from_csv.py

@@ -0,0 +1,27 @@
+import pykx as kx
+import pandas as pd
+from ..utils import _handle_return
+import pyarrow.csv as pa_csv
+
+def from_csv(path, return_type='q'):
+    """
+    Imports DataFrame from CSV file.
+
+    Parameters
+    ----------
+    path : str
+        File path to load CSV from.
+    return_type : str, default 'q'
+        Desired return type ('p' or 'q').
+
+    Returns
+    -------
+    pandas.DataFrame or pykx.Table
+        Loaded DataFrame.
+    """
+    try:       
+        pa_tab = pa_csv.read_csv(path)
+        q_table = kx.toq(pa_tab)
+        return _handle_return(q_table, return_type)
+    except Exception as e:
+        raise RuntimeError(f"Failed to load CSV file {path}: {e}")

qutePandas/io/to_csv.py

@@ -0,0 +1,39 @@
+import pykx as kx
+import pandas as pd
+import pyarrow.csv as pa_csv
+from ..utils import _ensure_q_table
+
+def to_csv(df, path):
+    """
+    Exports DataFrame to CSV file.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame or pykx.Table
+        Input DataFrame.
+    path : str
+        File path to save CSV.
+
+    Returns
+    -------
+    str
+        Success message.
+    """
+    try:
+        if hasattr(df, 'pa'):
+            pa_tab = df.pa()
+            pa_csv.write_csv(pa_tab, path)
+            return f"Table saved to: {path}"
+        
+        if isinstance(df, (kx.Table, kx.KeyedTable)):
+            pd_df = df.pd()
+        elif isinstance(df, pd.DataFrame):
+            pd_df = df
+        else:
+            pd_df = pd.DataFrame(df)
+            
+        pd_df.to_csv(path, index=False)
+        return f"Table saved to: {path}"
+
+    except Exception as e:
+        raise RuntimeError(f"Failed to save table to CSV: {e}")

qutePandas/joining/__init__.py

@@ -0,0 +1,3 @@
+from .merge import merge
+
+__all__ = ['merge']

qutePandas/joining/merge.py

@@ -0,0 +1,94 @@
+import pykx as kx
+import pandas as pd
+from ..utils import _ensure_q_table, _handle_return
+
+
+def merge(left, right, how='inner', on=None, left_on=None, right_on=None, left_index=False, right_index=False, sort=False, return_type="q"):
+    """
+    Merge DataFrame or pykx.Table objects with a database-style join.
+
+    Parameters
+    ----------
+    left : pandas.DataFrame or pykx.Table
+        Left object.
+    right : pandas.DataFrame or pykx.Table
+        Right object.
+    how : {'left', 'right', 'outer', 'inner'}, default 'inner'
+        Type of merge to be performed.
+    on : label or list
+        Column or index level names to join on. These must be found in both DataFrames.
+    left_on : label or list
+        Column or index level names to join on in the left DataFrame.
+    right_on : label or list
+        Column or index level names to join on in the right DataFrame.
+    left_index : bool, default False
+        Use the index from the left DataFrame as the join key(s). (Currently not fully supported)
+    right_index : bool, default False
+        Use the index from the right DataFrame as the join key(s). (Currently not fully supported)
+    sort : bool, default False
+        Sort the join keys lexicographically in the result DataFrame. (Currently not fully supported)
+    return_type : str, default 'q'
+        Desired return type ('p' or 'q').
+
+    Returns
+    -------
+    pandas.DataFrame or pykx.Table
+        Merged object.
+    """
+    try:
+        q_left = _ensure_q_table(left)
+        q_right = _ensure_q_table(right)
+
+        if on is None and left_on is None and right_on is None:
+            left_cols = set(kx.q("cols", q_left).py())
+            right_cols = set(kx.q("cols", q_right).py())
+            common = list(left_cols.intersection(right_cols))
+            if not common:
+                raise ValueError("No common columns found and no join keys specified.")
+            on = common
+
+        l_keys = on if left_on is None else left_on
+        r_keys = on if right_on is None else right_on
+
+        if isinstance(l_keys, str):
+            l_keys = [l_keys]
+        if isinstance(r_keys, str):
+            r_keys = [r_keys]
+
+        if l_keys != r_keys:
+            update_clauses = []
+            for lk, rk in zip(l_keys, r_keys):
+                if lk != rk:
+                    update_clauses.append(f"{lk}:{rk}")
+            
+            if update_clauses:
+                update_str = ",".join(update_clauses)
+                q_right = kx.q(f"{{update {update_str} from x}}", q_right)
+            
+            r_keys = l_keys
+
+        key_cols = "`" + "`".join(l_keys)
+
+        if how == 'inner':
+            keyed_right = kx.q(f'{{ {key_cols} xkey x }}', q_right)
+            result = kx.q("{x ij y}", q_left, keyed_right)
+        elif how == 'left':
+            keyed_right = kx.q(f'{{ {key_cols} xkey x }}', q_right)
+            result = kx.q("{x lj y}", q_left, keyed_right)
+        elif how == 'right':
+            keyed_left = kx.q(f'{{ {key_cols} xkey x }}', q_left)
+            result = kx.q("{x lj y}", q_right, keyed_left)
+            left_all_cols = kx.q("cols", q_left).py()
+            right_all_cols = kx.q("cols", q_right).py()
+            target_cols = "`" + "`".join(left_all_cols + [c for c in right_all_cols if c not in left_all_cols])
+            result = kx.q(f"{{ {target_cols} xcols x }}", result)
+        elif how == 'outer':
+            keyed_left = kx.q(f'{{ {key_cols} xkey x }}', q_left)
+            keyed_right = kx.q(f'{{ {key_cols} xkey x }}', q_right)
+            result = kx.q("{0! x uj y}", keyed_left, keyed_right)
+        else:
+            raise ValueError(f"Invalid how: {how}. Must be one of 'left', 'right', 'outer', 'inner'.")
+
+        return _handle_return(result, return_type)
+    except Exception as e:
+        raise RuntimeError(f"Failed to perform {how} join: {e}")

qutePandas/transformation/__init__.py

@@ -0,0 +1,5 @@
+from .rename import rename
+from .cast import cast
+from .drop_col import drop_col
+
+__all__ = ['rename', 'cast', 'drop_col'] 

qutePandas/transformation/cast.py

@@ -0,0 +1,71 @@
+import pykx as kx
+import pandas as pd
+from ..utils import _ensure_q_table, _handle_return
+
+
+def cast(df, col, dtype, return_type='q'):
+    """
+    Converts column to specified data type.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame or pykx.Table
+        Input DataFrame.
+    col : str
+        Column name to cast.
+    dtype : str
+        Target data type ('i' for int, 'f' for float, 's' for symbol, etc.).
+    return_type : str, default 'q'
+        Desired return type ('p' or 'q').
+
+    Returns
+    -------
+    pandas.DataFrame or pykx.Table
+        DataFrame with column cast to new type.
+    """
+    try:
+        q_map = {
+            'int64': 'j', 'int32': 'i', 'int': 'i', 'long': 'j',
+            'float64': 'f', 'float32': 'e', 'float': 'f', 'real': 'e',
+            'object': 's', 'string': 'C', 'str': 'C',
+            'j': 'j', 'i': 'i', 'h': 'h', 'f': 'f', 'e': 'e', 's': 's', 'c': 'c'
+        }
+
+        q_type = q_map.get(dtype, dtype)
+        q_table = _ensure_q_table(df)
+
+        if len(q_type) != 1:
+            raise ValueError(f"Unsupported q cast type: {dtype}")
+
+        curr_type = kx.q(f'{{type x`{col}}}', q_table).py()
+        type_to_code = {
+            'j': 7, 'i': 6, 'h': 5, 'f': 9, 'e': 8, 's': 11, 'c': 10, 'b': 1
+        }
+        target_code = type_to_code.get(q_type.lower())
+
+        if target_code is not None and abs(curr_type) == target_code:
+            return _handle_return(q_table, return_type)
+
+        is_parsing = curr_type in (0, 10)
+        q_char = q_type.upper() if is_parsing else q_type.lower()
+
+        if q_char.lower() == 's':
+            result = kx.q(
+                f'{{update {col}:`$ string {col} from x}}',
+                q_table
+            )
+        elif q_char in ('i', 'j'):
+            result = kx.q(
+                f'{{update {col}:"{q_char}"$(({col}>=0)*floor {col} + ({col}<0)*ceiling {col}) from x}}',
+                q_table
+            )
+        else:
+            result = kx.q(
+                f'{{update {col}:"{q_char}"${col} from x}}',
+                q_table
+            )
+
+        return _handle_return(result, return_type)
+
+    except Exception as e:
+        raise RuntimeError(f"Failed to cast column {col} to type {dtype}: {e}")