pivotalpath 1.0.0__py3-none-any.whl

pivotalpath/__init__.py

@@ -0,0 +1,65 @@
+"""
+PivotalPath: The Industry Standard for Hedge Fund INDEX Analytics
+
+Analyzes hedge fund indices - composite benchmarks tracking groups of hedge funds.
+"""
+
+from .version import __version__
+
+# Core functionality
+from .core.main_library import (
+    get_catalog,
+    get_returns, 
+    get_info,
+    get_asset_list,
+    get_stats,
+    get_stats_list,
+)
+
+# Important tickers and examples
+from .core import important_tickers
+from .core import examples
+
+# Stats catalog  
+from .stats.catalog import stats_catalog
+
+# LLM-optimized interface for hedge fund indices
+try:
+    from .llm.interface import (
+        quick_index_stats,
+        analyze_hedge_fund_index,
+        compare_hedge_fund_indices,
+        list_hedge_fund_indices,
+        list_available_metrics,
+        generate_index_report,
+    )
+    LLM_AVAILABLE = True
+except ImportError as e:
+    print(f"LLM interface import failed: {e}")
+    LLM_AVAILABLE = False
+
+# Export everything
+__all__ = [
+    "__version__",
+    "get_catalog",
+    "get_returns",
+    "get_info", 
+    "get_asset_list",
+    "get_stats",
+    "get_stats_list",
+    "stats_catalog",
+    "important_tickers",
+    "examples",
+    "LLM_AVAILABLE",
+]
+
+# Add LLM functions if available
+if LLM_AVAILABLE:
+    __all__.extend([
+        "quick_index_stats",
+        "analyze_hedge_fund_index",
+        "compare_hedge_fund_indices", 
+        "list_hedge_fund_indices",
+        "list_available_metrics",
+        "generate_index_report",
+    ])

pivotalpath/core/__init__.py

@@ -0,0 +1,24 @@
+"""Core functionality for hedge fund analysis."""
+
+from .main_library import (
+    get_catalog,
+    get_returns, 
+    get_info,
+    get_asset_list,
+    get_stats,
+    get_stats_list,
+)
+
+from . import important_tickers
+from . import examples
+
+__all__ = [
+    "get_catalog",
+    "get_returns",
+    "get_info",
+    "get_asset_list", 
+    "get_stats",
+    "get_stats_list",
+    "important_tickers",
+    "examples",
+]

pivotalpath/core/examples.py

@@ -0,0 +1,86 @@
+
+from . import main_library as mli
+from . import important_tickers as it
+
+"""
+USECASES AND EXAMPLES OF THE MAIN LIBRARY FUNCTIONS
+
+"""
+
+"""
+example1: example of tickers
+"""
+def example1():
+    return [it.market_ticker, it.riskfree_ticker, it.hedge_fund_composite_index_ticker]
+
+"""
+example2: hedge fund index catalog
+"""
+def example2():
+    return mli.get_catalog(asset_class="index")
+
+"""
+example3: list all hedge fund index tickers
+"""
+def example3():
+    return mli.get_asset_list(asset_class="index")
+
+"""
+example4: list all hedge fund index names
+"""
+def example4():
+    return mli.get_asset_list(asset_class="index", select="name")
+"""
+example5: market returns
+"""
+def example5():
+    return mli.get_returns(ticker=it.market_ticker)
+
+"""
+example6: list available stats tickers
+""" 
+def example6():
+    return mli.get_stats_list()
+"""
+example7: list available stats names
+"""
+def example7():
+    return mli.get_stats_list(select="name")
+"""
+example8: example stats for first 2 hedge fund indices
+"""     
+def example8():
+    return mli.get_stats(
+        target=mli.get_asset_list(asset_class="index")[:2],
+        base=it.market_ticker,
+        start="2020-01",
+        end="2024-12",
+        stat=['annret','annvol','sharpe']
+        )
+
+"""
+example9: example stats with custom labels
+"""
+def example9():
+    return mli.get_stats(
+        target=mli.get_asset_list(asset_class='index')+['SP500'],
+        base=it.market_ticker,
+        start="2020-01",
+        end="2024-12",
+        stat=mli.get_stats_list(),
+        label_as="shortname",
+        )
+"""
+example10: example structured stats
+""" 
+def example10():
+    return mli.get_stats(
+        target=mli.get_asset_list(asset_class='index'),
+        base=it.market_ticker,
+        start="2020-01",
+        end="2024-12",
+        stat=['sharpe','annvol'],
+        label_as="name+period",
+        index_as="name",
+    )   
+

pivotalpath/core/important_tickers.py

@@ -0,0 +1,3 @@
+market_ticker="SP500"
+riskfree_ticker="TBILL3M"
+hedge_fund_composite_index_ticker="PP-HFC"

pivotalpath/core/main_library.py

@@ -0,0 +1,47 @@
+
+from ..data import get_catalog, get_returns, get_info
+from ..stats import stats_calculator,stats_catalog
+import pandas as pd
+
+def _notdf(df):
+    return not(df is None) and not (isinstance(df,pd.DataFrame))
+
+def get_stats(
+        target=None,
+        base=None,
+        riskfree=None,
+        index_as="ticker",
+        transpose=False,
+        **kwargs
+    ):
+    if _notdf(target):
+        target=get_returns(ticker=target)
+    if _notdf(base):
+        base=get_returns(ticker=base)
+    if _notdf(riskfree):   
+        riskfree=get_returns(ticker=riskfree)
+        return pd.DataFrame()
+    df=stats_calculator(target=target,base=base,riskfree=riskfree,**kwargs)
+    if isinstance(index_as,str) and index_as!="ticker":
+        try:
+            df_info=get_info(ticker=df.index.tolist())
+            if isinstance(df_info,pd.DataFrame) and not (df_info.empty):
+                info_map=df_info.set_index("ticker")[index_as].to_dict()
+                df.index=[info_map.get(_,_) for _ in df.index.tolist()]
+            df.index=df[index_as]
+            df.index.name=index_as
+        except:
+            pass
+    if transpose:
+        df=df.T
+    return df
+
+
+def get_stats_list(select="ticker")->list:
+    return [_.get(select) for _ in stats_catalog]
+
+def get_asset_list(asset_class="index",select="ticker")->list:
+    df=get_catalog(asset_class=asset_class,select=select)
+    if isinstance(df,pd.DataFrame) and not (df.empty):
+        return df[select].tolist()  
+    return []

pivotalpath/data/__init__.py

@@ -0,0 +1,115 @@
+
+import pandas as pd
+from .api import GetFilteredDataFrame
+from . import utils as tsutil
+
+def _ticker2class(ticker):
+    if isinstance(ticker,list):
+        return [_ticker2class(_) for _ in ticker]
+    else:
+        # tba: add confirmation
+        if ticker.startswith("PP"):
+            return "index"
+        else:
+            return "factor"
+            
+def _ticker2map(ticker=[]):
+    out=dict(
+        index=[_ for _ in ticker if _.startswith("PP")],
+        factor=[_ for _ in ticker if not (_.startswith("PP"))]
+    )
+    return {_:__ for _,__ in out.items() if __}
+
+
+"""
+main functions
+"""
+
+def get_catalog(asset_class="index",filter_by=dict(),select="*")->pd.DataFrame:
+    if isinstance(asset_class,list):
+        df=pd.DataFrame()
+        for _ in asset_class:
+            df_i=get_catalog(asset_class=_,filter_by=filter_by,select="*")
+            df=pd.concat([df,df_i]).set_index("ticker")
+        return df
+    table_name=f"{asset_class}_catalog"
+    return GetFilteredDataFrame(table_name,filter_by=filter_by)
+    
+
+def get_info(ticker=None):
+
+    if not ticker:
+        return {}
+
+    if isinstance(ticker,str):
+        asset_class=_ticker2class(ticker)
+        table_name=f"{asset_class}_catalog"
+        return GetFilteredDataFrame(table_name,filter_by=dict(ticker=ticker)).iloc[0].to_dict()
+    
+    if isinstance(ticker,list):
+        tickermap=_ticker2map(ticker)
+        out=pd.DataFrame()
+        for asset_i,ticker_i in tickermap.items():
+            table_name=f"{asset_i}_catalog"
+            df_i=GetFilteredDataFrame(table_name, filter_by=dict(ticker=ticker_i))
+            if isinstance(df_i,pd.DataFrame) and not (df_i.empty):
+                out=pd.concat([out,df_i],axis=0)
+        return out
+    
+
+def get_returns(
+        ticker=[],
+        month_list=[],
+        start=None,
+        end=None,
+        lookback=None,
+        column_label="ticker",
+        freq="M",
+        freq_aggregation="compounded",
+        annualized=False,
+        rounding_places=6,
+        pivot=True,
+        
+    )->pd.DataFrame:
+
+    """
+    Get returns data for specified tickers.
+    
+    Returns:
+        pd.DataFrame or None: DataFrame with returns data, or None if no ticker provided
+    """
+    if not ticker:
+        return pd.DataFrame()
+    if isinstance(ticker,str):
+        ticker=[ticker]
+    tickermap=_ticker2map(ticker=ticker)
+    if not month_list:
+        month_list=tsutil.build_month_list(start=start,end=end,lookback=lookback)
+    df=pd.DataFrame()
+    for asset_i, ticker_i in tickermap.items(): 
+        table_name=f"{asset_i}_returns"
+        rows=GetFilteredDataFrame(table_name, filter_by=dict(ticker=ticker_i))
+        if start:
+            rows=rows[rows['month']>=start]
+        if end:
+            rows=rows[rows['month']<=end]   
+
+        if df.empty:
+            df=rows
+        else:
+            df=pd.concat([df,rows])
+            
+    df=df[df['ticker'].isin(ticker)]
+    if freq!="M":
+        pivot=True
+
+    if pivot:
+        df=df.pivot_table(index='month', columns='ticker', values='return')
+        df=df[[_ for _ in ticker if _ in df.columns]]
+    
+    if freq!="M":
+        df=tsutil.frequency_aggregation(df, freq=freq,freq_aggregation=freq_aggregation,annualized=annualized)
+       
+    return round(df,rounding_places)
+
+    

pivotalpath/data/api.py

@@ -0,0 +1,35 @@
+
+import pandas as pd
+import warnings
+import requests
+
+class ApiCaller:
+    
+    base_url = "http://apps.pivotalpath.com/p3ypi/resources/api/v1/"
+    api_key = "p3k_7H9mK2pL8qX3nR5vW1cY4jZ6sA0uE9"
+    
+    @classmethod
+    def get_headers(cls):
+        return {
+            "Authorization": f"Bearer {cls.api_key}",
+            "Content-Type": "application/json"
+        }
+    
+    @classmethod
+    def get_data(cls,endpoint=None,params=dict()):
+        url=cls.base_url+endpoint
+        headers=cls.get_headers()
+        response=requests.get(url,headers=headers,params=params)
+        if response.status_code==200:
+            try:
+                return pd.DataFrame(response.json())
+            except ValueError:
+                warnings.warn("Failed to parse JSON response")
+                return pd.DataFrame()
+        else:
+            warnings.warn(f"API call failed with status code {response.status_code}")
+            return pd.DataFrame()
+
+
+def GetFilteredDataFrame(table_name=None, filter_by=dict())->pd.DataFrame:
+    return ApiCaller.get_data(endpoint=table_name,params=filter_by)

pivotalpath/data/utils.py

@@ -0,0 +1,40 @@
+import pandas as pd
+
+def _do_compound(df):
+    return (1 +df).prod(min_count=1) - 1
+def _do_sum(df):
+    return df.sum()
+def _compute_default_end():
+    return (pd.Timestamp.today()-pd.DateOffset(months=1)).strftime("%Y-%m")
+def _compute_default_start():
+    return "1998-01"
+
+
+def build_month_list(start=None,end=None,lookback=None, _default_start="1998-01",_default_rule="rule_of_7"):
+    if not end:
+        end=_compute_default_end()
+    if not start:
+        if lookback:
+            start=(pd.Timestamp(end)-pd.DateOffset(months=lookback-1)).strftime("%Y-%m")
+        else:
+            start=_compute_default_start()
+    return [_.strftime("%Y-%m") for _ in pd.period_range(start=start,end=end,freq="M")]
+
+def timeseries_aggregation(df,freq="Q",freq_aggregation="compounded",annualized=False,rounding_places=6):
+    if not isinstance(df.index, pd.DatetimeIndex):
+        df.index = pd.to_datetime(df.index, format='%Y-%m')
+    df_agg=df.resample(freq)
+    if freq_aggregation=="compounded":
+        out=df_agg.apply(_do_compound)
+        if annualized:
+            out=(1+out)**4-1
+    elif freq_aggregation=="sum":
+        out= df_agg.apply(_do_sum)
+        if annualized:
+            out=4*out
+    if rounding_places:
+        out=round(out,rounding_places)
+    out.index=out.index.to_period(freq).astype(str)
+    if freq=="Y":
+        out.index=[f"Y{_}" for _ in out.index]
+    return out

pivotalpath/llm/__init__.py

@@ -0,0 +1,19 @@
+"""LLM-optimized interface for hedge fund index analysis."""
+
+from .interface import (
+    quick_index_stats,
+    analyze_hedge_fund_index,
+    compare_hedge_fund_indices,
+    list_hedge_fund_indices,
+    list_available_metrics,
+    generate_index_report,
+)
+
+__all__ = [
+    "quick_index_stats",
+    "analyze_hedge_fund_index",
+    "compare_hedge_fund_indices",
+    "list_hedge_fund_indices",
+    "list_available_metrics", 
+    "generate_index_report",
+]

pivotalpath/llm/interface.py

@@ -0,0 +1,227 @@
+"""
+LLM-optimized interface for PivotalPath.
+Designed for hedge fund INDEX analysis only.
+
+PivotalPath analyzes hedge fund indices - composite benchmarks that track 
+groups of hedge funds by strategy. It does NOT analyze individual hedge funds.
+"""
+
+from typing import Dict, List, Optional, Union, Any
+import pandas as pd
+from datetime import datetime
+
+# Import from your existing modules
+from ..core.main_library import get_stats, get_returns, get_asset_list, get_catalog
+
+
+def quick_index_stats(
+    index_ticker: str,
+    benchmark: str = "SP500",
+    period: str = "5Y"
+) -> Dict[str, Any]:
+    """
+    Get essential performance stats for a hedge fund index.
+    
+    Args:
+        index_ticker: Hedge fund index ticker (e.g., "PP-HFC")
+        benchmark: Market benchmark (default: "SP500")
+        period: Time period - "1Y", "3Y", "5Y", "YTD"
+        
+    Returns:
+        Dictionary with essential index performance metrics
+    """
+    import pandas as pd
+    
+    end_date = (pd.Timestamp.now() - pd.DateOffset(months=1)).strftime("%Y-%m")
+    
+    if period == "YTD":
+        start_date = f"{pd.Timestamp.now().year}-01"
+    elif period.endswith("Y"):
+        years = int(period[:-1])
+        start_date = (pd.Timestamp.now() - pd.DateOffset(years=years)).strftime("%Y-%m")
+    else:
+        start_date = "2020-01"
+    
+    essential_stats = ['annret', 'annvol', 'sharpe', 'maxddc', 'beta']
+    
+    try:
+        results = get_stats(
+            target=index_ticker,
+            base=benchmark,
+            start=start_date,
+            end=end_date,
+            stat=essential_stats
+        )
+        
+        if isinstance(results, pd.DataFrame) and not results.empty:
+            data = results.iloc[:, 0].to_dict()
+            data.update({
+                'index_ticker': index_ticker,
+                'asset_type': 'hedge_fund_index',
+                'benchmark': benchmark,
+                'period': period,
+                'analysis_date': pd.Timestamp.now().strftime("%Y-%m-%d")
+            })
+            return data
+        else:
+            return {
+                'error': f"No data available for index {index_ticker}",
+                'suggested_indices': list_hedge_fund_indices()[:3]
+            }
+    except Exception as e:
+        return {
+            'error': f"Index analysis failed: {str(e)}",
+            'index_ticker': index_ticker
+        }
+
+
+def analyze_hedge_fund_index(
+    index_ticker: str,
+    benchmark: str = "SP500",
+    start_date: str = "2020-01",
+    end_date: str = "2024-12"
+) -> Dict[str, Any]:
+    """
+    Comprehensive analysis of a hedge fund index.
+    
+    Args:
+        index_ticker: Hedge fund index ticker (e.g., "PP-HFC")
+        benchmark: Market benchmark (default: "SP500")
+        start_date: Start date in YYYY-MM format
+        end_date: End date in YYYY-MM format
+        
+    Returns:
+        Dictionary with comprehensive index performance metrics
+    """
+    all_stats = ['annret', 'annvol', 'sharpe', 'beta', 'alpha', 'maxddc', 'sortino', 'calmar']
+    
+    try:
+        results = get_stats(
+            target=index_ticker,
+            base=benchmark,
+            start=start_date,
+            end=end_date,
+            stat=all_stats
+        )
+        
+        if isinstance(results, pd.DataFrame) and not results.empty:
+            analysis_dict = results.iloc[:, 0].to_dict()
+            analysis_dict.update({
+                'index_ticker': index_ticker,
+                'asset_type': 'hedge_fund_index',
+                'benchmark': benchmark,
+                'period': f"{start_date} to {end_date}",
+                'analysis_date': datetime.now().strftime("%Y-%m-%d")
+            })
+            return analysis_dict
+        else:
+            return {
+                'error': f"No data available for index {index_ticker}",
+                'index_ticker': index_ticker
+            }
+    except Exception as e:
+        return {
+            'error': f"Index analysis failed: {str(e)}",
+            'index_ticker': index_ticker
+        }
+
+
+def compare_hedge_fund_indices(
+    index_tickers: List[str],
+    benchmark: str = "SP500",
+    metrics: List[str] = ['annret', 'annvol', 'sharpe', 'maxddc'],
+    start_date: str = "2020-01",
+    end_date: str = "2024-12"
+) -> pd.DataFrame:
+    """
+    Compare multiple hedge fund indices side by side.
+    
+    Args:
+        index_tickers: List of hedge fund index tickers
+        benchmark: Market benchmark (default: "SP500")
+        metrics: Metrics to compare
+        start_date: Start date in YYYY-MM format
+        end_date: End date in YYYY-MM format
+        
+    Returns:
+        DataFrame comparing indices
+    """
+    try:
+        results = get_stats(
+            target=index_tickers,
+            base=benchmark,
+            start=start_date,
+            end=end_date,
+            stat=metrics,
+            transpose=True
+        )
+        
+        if isinstance(results, pd.DataFrame) and not results.empty:
+            return results.round(4)
+        else:
+            return pd.DataFrame(index=metrics, columns=index_tickers)
+            
+    except Exception as e:
+        print(f"Index comparison failed: {e}")
+        return pd.DataFrame(index=metrics, columns=index_tickers)
+
+
+def list_hedge_fund_indices() -> List[str]:
+    """Get list of all available hedge fund index tickers."""
+    try:
+        return get_asset_list(asset_class="index", select="ticker")
+    except Exception:
+        return ["PP-HFC", "PP-L-EH", "PP-L-MA", "PP-L-ED", "PP-L-EM"]
+
+
+def list_available_metrics() -> List[str]:
+    """Get list of all available performance metrics."""
+    try:
+        from ..core.main_library import get_stats_list
+        return get_stats_list(select="ticker")
+    except Exception:
+        return ['annret', 'annvol', 'sharpe', 'maxddc', 'beta', 'alpha', 'sortino', 'calmar']
+
+
+def generate_index_report(
+    index_ticker: str,
+    benchmark: str = "SP500",
+    start_date: str = "2020-01",
+    end_date: str = "2024-12"
+) -> str:
+    """
+    Generate a formatted report for a hedge fund index.
+    
+    Returns:
+        Formatted string report for the index
+    """
+    analysis = analyze_hedge_fund_index(index_ticker, benchmark, start_date, end_date)
+    
+    if 'error' in analysis:
+        return f"Index Report Failed: {analysis['error']}"
+    
+    return f"""
+HEDGE FUND INDEX PERFORMANCE REPORT
+{'='*50}
+
+Index: {analysis.get('index_ticker', 'N/A')}
+Period: {analysis.get('period', 'N/A')}
+Benchmark: {analysis.get('benchmark', 'N/A')}
+
+PERFORMANCE METRICS
+{''*25}
+Annual Return:     {analysis.get('annret', 0):>8.1%}
+Volatility:        {analysis.get('annvol', 0):>8.1%}
+Sharpe Ratio:      {analysis.get('sharpe', 0):>8.2f}
+Max Drawdown:      {analysis.get('maxddc', 0):>8.1%}
+
+MARKET EXPOSURE
+{''*25}
+Beta:              {analysis.get('beta', 0):>8.2f}
+Alpha:             {analysis.get('alpha', 0):>8.1%}
+
+Analysis Date: {analysis.get('analysis_date', 'N/A')}
+
+NOTE: This report analyzes a hedge fund INDEX, which represents
+aggregated performance of multiple hedge funds, not an individual fund.
+"""

pivotalpath/stats/__init__.py

@@ -0,0 +1,55 @@
+
+import warnings
+import pandas as pd
+from .params import configureParams
+from .wrapper import basicstats
+from .catalog import stats_catalog
+
+
+def stats_calculator(
+        target=None,
+        base="SP500",
+        riskfree="TBILL3M",
+        configured_params=[],
+        **kwargs
+    )->pd.DataFrame:
+    
+    if not kwargs.get("_default_start"):
+        kwargs.update(_default_start=target.index[0])
+        
+    if not kwargs.get("_default_end"):
+        kwargs.update(_default_end=target.index[-1])
+        
+    if not configured_params:
+        # note: configured_params will most certainly be empty, unles it is repurposed from a different call
+        configured_params=configureParams(**kwargs)
+    
+    df=target
+    out=None
+
+    for i,param_i in enumerate(configured_params):
+        stat_i=basicstats(df,base=base,riskfree=riskfree,**param_i)
+        if stat_i is None:
+            continue
+        stat_i=pd.DataFrame(stat_i)
+        if out is None:
+            out=stat_i.copy()
+        else:
+            try:
+                out=out.join(stat_i)
+            except:
+                warnings.warn("could not join the ith stat output")
+        
+    return out
+
+
+# Import everything from catalog
+from .catalog import stats_catalog, stat_dict
+
+__all__ = [
+    "stats_calculator",
+    "stats_catalog",
+    "stat_dict", 
+    "basicstats",
+    "configureParams",
+]

pivotalpath/stats/catalog.py

@@ -0,0 +1,164 @@
+stats_catalog=[
+    dict(
+        ticker='totret',
+        name='Total Return',
+        shortname='TotRet',
+        description="full sample return",
+        latex_expression='$\prod_{i=1}^N(1+r_i)-1$',
+    ),
+    dict(
+        ticker='annret',
+        name="Annualized Return",
+        shortname='AnnRet',
+        description="annualized mean return",
+        latex_expression='$(12/N)\sum_{i=1}^Nr_i$',        
+    ),
+    
+    dict(
+        ticker='annretc',
+        name="Compounded Annualized Return",
+        shortname='AnnRet(c)',
+        description="compounded annualized return",
+        latex_expression='$(\prod_{i=1}^N(1+r_i))^{12/N}-1$',        
+    ),
+
+    dict(
+        ticker='annvol',
+        name='Annualized Volatility',
+        shortname='AnnVol',
+        description="annualized volatily",
+        latex_expression="$\sqrt{12}\\times\mathbb E[(r_i-\\bar{r_i})^2]^{1/2}$",
+    ),
+
+    dict(
+        ticker='maxddc',
+        name='Max Drawdown',
+        shortname='MaxDD',
+        description='max loss (peak to trough)',
+        latex_expression="$\\min_{1\leq s\leq t\leq N}\prod_{i=s}^t(1+r_i)-1$",
+    ),
+
+    dict(
+        ticker='skewness',
+        name='Skewness',
+        shortname='Skewness',
+        description="skewness",
+        latex_expression='$\mathbb E[(\\frac{r_i-\mu}{\sigma})^3]$',
+    ),
+
+    dict(
+        ticker='exckurt',
+        name='Excess Kurtosis',
+        shortname='Kurt(exc)',
+        description="excess kurtosis",
+        latex_expression='$\mathbb E[(\\frac{r_i-\mu}{\sigma})^4]-3$',
+    ),
+
+    dict(
+        ticker='sharpe',
+        name='Sharpe Ratio',
+        shortname='Sharpe',
+        latex_expression='AnnReturn/AnnVol'
+    ),
+
+    dict(
+        ticker='sharpec',
+        name='Sharpe Ratio (compounded)',
+        shortname='SR(c)',
+        latex_expression='AnnReturn(c)/AnnVol'
+    ),
+
+
+    dict(
+        ticker='sharperf',
+        name='Sharpe Ratio (riskfree)',
+        shortname='SR(rf)',
+        latex_expression='Sharpe(return-TBill3M)'
+    ),
+
+    dict(
+        ticker="sharpeadj",
+        name="Adjusted Sharpe Ratio",
+        shortname="SR(adj)",
+        latex_expression='$\operatorname{SR}(1 + (1/6) \cdot \operatorname{Skewness} \cdot \operatorname{SR} - (1/24)\operatorname{ExcKurt}\cdot \operatorname{SR}^2)$',
+    ),
+
+    
+    dict(
+        ticker='calmar',
+        name='Calmar',
+        shortname='Calmar',
+        description="calmar ratio (36M)",
+        latex_expression='AnnReturn(c)/MDD',
+    ),
+  
+    dict(
+        ticker='omega',
+        name='Omega',
+        shortname='Omega',
+        description="omega ratio",
+        latex_expression='$\mathbb E[r_i|r_i>0]/\mathbb E[|r_i||r_i<0]$ '
+    ),
+
+    dict(
+        ticker='sortino',
+        name='Sortino Ratio',
+        shortname='Sortino',
+        latex_expression='AnnRet/($\sqrt{12}\\times$DDEV)'
+    ),
+
+    dict(
+        ticker='ddev',
+        name='Downside Deviation',
+        shortname='DDEV',
+        latex_expression='$\mathbb E[\\min(0,r_i)^2]^{1/2}$',
+    ),
+
+    dict(
+        ticker='hitratio',
+        name='Hit Ratio',
+        shortname='HR',
+        description='proportion of positive returns',
+        latex_expression="Prob(r_i≥0)",  
+    ),
+
+    dict(
+        ticker='alpha',
+        name='Annualized Alpha',
+        shortname='Alpha',
+        description="annualized alpha",
+        latex_expression='$12\\times(\mathbb E[r_i]-\\beta\mathbb E[f_i])$',
+    ),
+
+    dict(
+        ticker='beta',
+        name='Beta',
+        shortname='Beta',
+        description="beta",
+        latex_expression='$\operatorname{cov}(r_i,f_i)/\operatorname{var}(f_i)$',
+    ),
+    
+    dict(
+        ticker='corr',
+        name='Correlation',
+        shortname='Corr',
+        description='Pearson correlation coefficient',
+        latex_expression='$\operatorname{cov}(r_i,f_i)/(\operatorname{std}(r_i)\operatorname{std}(f_i))$',
+    ),
+
+    dict(
+        ticker='r2',
+        name='RSquared',
+        shortname='R2',
+        description='r squared',
+        latex_expression='$\operatorname{var}[\epsilon_i]$',
+    ),
+    
+]
+
+stat_dict={
+    item['ticker']:item 
+    for item in stats_catalog
+}
+
+

pivotalpath/stats/kernel.py

@@ -0,0 +1,205 @@
+import pandas as pd
+import numpy as np
+import pdb
+
+
+def _zeroInsert(df):
+    if "date" in df.columns.tolist():
+        df=df.set_index("date")
+        df.index.name="date"
+        un_indexify=True
+    else:
+        un_indexify=False
+    newrow=pd.DataFrame({k:[0] for k in df.columns},index=["0000-00"])
+    df=pd.concat([newrow,df],axis=0)
+    if un_indexify:
+        df=df.reset_index().rename(columns={'index':'date'})
+    return df
+
+def _outputNull(df,title='stat'):
+    return pd.DataFrame(pd.Series(index=df.columns,name=title))
+
+
+    
+def _nanAlign(df,base):
+    try:
+        base=pd.concat([base] * (df.shape[1]), axis=1, ignore_index=True)
+        base.columns=df.columns    
+        base[df.isnull()] = df.copy()
+        df[base.isnull()] = base.copy()
+        return df,base
+    except:
+        pass
+
+    
+def totret(df,**kwargs):
+    return (1+df).prod(axis=0)-1
+
+def annret(df,**kwargs):
+    return 12*df.mean(axis=0)
+
+def annretc(df,**kwargs):
+    A=(1+df).prod(axis=0)
+    B=df.notna().sum(axis=0)
+    B[B==0]=np.nan
+    return (A**(12/B))-1
+
+def annvol(df,**kwargs):
+    return np.sqrt(12)*df.std(axis=0,ddof=1)
+
+def maxdd(df,**kwargs):
+    nav=_zeroInsert(df).cumsum()
+    peak=nav.expanding(1).max()
+    return (nav-peak).iloc[1:].min(axis=0)
+
+def maxddc(df,**kwargs):
+    nav=(1+_zeroInsert(df)).cumprod()
+    peak=nav.expanding(1).max()
+    return ((nav/peak)-1.0).iloc[1:].min(axis=0)
+
+
+def skewness(df,**kwargs):
+    #scistats.skew(df,nan_policy='omit')
+    sigma=df.std(axis=0,ddof=0)
+    sigma[sigma==0]=np.nan
+    df0=(df-df.mean(axis=0))/sigma
+    return (df0**3).mean(axis=0)
+    
+
+
+def exckurt(df,**kwargs):
+    # scistats.kurtosis(df,nan_policy='omit')
+    sigma=df.std(axis=0,ddof=0)
+    sigma[sigma==0]=np.nan
+    df0=(df-df.mean(axis=0))/sigma
+    return (df0**4).mean(axis=0)-3
+
+def sharpe(df,**kwargs):
+    R=12*df.mean(axis=0)
+    V=np.sqrt(12)*df.std(axis=0,ddof=1)
+    return R/V
+
+def sharpec(df,**kwargs):
+    A=(1+df).prod(axis=0)
+    B=df.notna().sum(axis=0)
+    B[B==0]=np.nan
+    R=(A**(12/B))-1
+    V=np.sqrt(12)*df.std(axis=0,ddof=1)
+    return R/V
+
+def sharperf(df,riskfree=None,**kwargs):
+    if riskfree is None:
+        riskfree=0
+    if isinstance(riskfree,pd.DataFrame) and not riskfree.empty:
+        riskfree=riskfree[riskfree.columns[0]]
+    df=df.sub(riskfree,axis=0)
+    R=12*df.mean(axis=0)
+    V=np.sqrt(12)*df.std(axis=0,ddof=1)
+    return R/V
+
+def sharpeadj(df,base=None,**kwargs):
+    R=12*df.mean(axis=0)
+    V=np.sqrt(12)*df.std(axis=0,ddof=1)
+    SR=R/V
+    lambda_1=(1/6)*skewness(df)
+    lambda_2=(1/24)*exckurt(df)
+    adjustment_factor=1 + (lambda_1* SR) - (lambda_2* (SR**2))
+    return SR * adjustment_factor
+
+def calmar(df,lookback=36,**kwargs):
+    # compute maxdd
+    if len(df)>36:
+        df=df.iloc[-lookback:]
+    nav=(1+_zeroInsert(df)).cumprod()
+    peak=nav.expanding(1).max()
+    currDD=(nav/peak)-1.0
+    maxDD=-currDD.iloc[1:].min(axis=0)
+    maxDD[maxDD==0]=np.nan
+    numPts=df.notna().sum()
+    annRet=(((1+df).prod(min_count=1))**(12/numPts))-1
+    out=annRet/maxDD
+    #out[:]="n/d"
+    #out[maxDD.isna()]="n/a (no drawdown)"
+    return out
+
+def omega(df,**kwargs):
+    ypos=df.copy()
+    ypos[ypos<=0]=np.nan
+    yneg=df.copy()
+    yneg[yneg>=0]=np.nan
+    A=ypos.mean(axis=0)
+    B=-yneg.mean(axis=0)
+    return A/B
+
+def sortino(df,**kwargs):
+    # as on pivotalbase
+    MAR=0
+    ye=df-MAR
+    yn=ye.clip(upper=0)
+    exrt=ye.mean(axis=0)
+    ddev=np.sqrt((yn**2).mean(axis=0))
+    ddev[ddev==0]=np.nan
+    return np.sqrt(12)*exrt/ddev
+
+
+def ddev(df,**kwargs):
+    yn=df.clip(upper=0)
+    return np.sqrt((yn**2).mean(axis=0))
+
+def hitratio(df,**kwargs): 
+    A=(df>=0).sum(axis=0)
+    B=df.notna().sum(axis=0)
+    B[B==0]=np.nan
+    return A/B
+
+#=========================================
+
+def alpha(df,base=None,**kwargs):
+    if base is None:
+        return _outputNull(df,title='alpha')    
+    df,base=_nanAlign(df,base)
+    ex=base.mean()
+    ey=df.mean()
+    base=base-ex
+    df=df-ey
+    exy=(base*df).mean()
+    exx=(base**2).mean()
+    exx[exx.abs()<1e-17]=np.nan
+    beta=exy/exx
+    alpha=ey-beta*ex
+    return 12*alpha
+
+def beta(df,base=None,**kwargs):
+    if base is None:
+        return _outputNull(df,title='beta')        
+    df,base=_nanAlign(df,base)
+    base=base-base.mean()
+    df=df-df.mean()
+    exy=(base*df).mean()
+    exx=(base**2).mean()
+    beta=exy/exx
+    return beta
+
+def corr(df,base=None,**kwargs):
+    if base is None:
+        return _outputNull(df,title='corr')
+    if isinstance(base,pd.DataFrame):
+        base=base[base.columns[0]]
+    return df.apply(lambda x:x.corr(base))
+
+def r2(df,base=None,**kwargs):
+    if base is None:
+        return _outputNull(df,title='r2')
+    if isinstance(base,pd.DataFrame):
+        base=base[base.columns[0]]
+    return df.apply(lambda x:x.corr(base))**2
+
+    
+def numpts(df,**kwargs):
+    return df.notna().sum(axis=0)
+
+def currentvalue(df,**kwargs):
+    return df.iloc[-1]
+
+ 
+

pivotalpath/stats/params.py

@@ -0,0 +1,179 @@
+import warnings
+import pandas as pd
+import pdb
+ 
+from .catalog import stat_dict
+
+def _islist(x):
+    return isinstance(x,list)
+
+def _isscalar(x):
+    return not isinstance(x,list)
+
+def _computestart(start=None,end=None,lookback=None):
+    if start:
+        return start
+    else:
+        return None if (not all([end,lookback])) else (pd.Timestamp(end)-pd.DateOffset(months=lookback-1)).strftime("%Y-%m") 
+
+def _computelookback(start,end):
+    start_dt,end_dt = [pd.to_datetime(_) for _ in [start,end]]
+    return (12*(end_dt.year - start_dt.year) + (end_dt.month - start_dt.month))+1
+    
+def _computeperiod(start,end):
+    if all([start,end]):
+        return f"{start}:{end}"
+    elif start:
+        return f"{start}:"
+    elif end:
+        return f":{end}"
+    else:
+        return ""
+    
+def _computeperiodformat(start,end):
+    def _safestr(_):
+        return pd.Timestamp(_).strftime("%b%y") if _ else ""
+    start,end=_safestr(start),_safestr(end)
+    if all([start,end]):
+        return f"{start}-{end}"
+    elif start:
+        return f"{start}-"
+    elif end:
+        return f"-{end}"
+    else:
+        return ""
+
+def _completeparams(params={},ticker=None,label=None,label_as=None):
+    if not label:
+        label=_computelabel(params=params,ticker=ticker,label_as=label_as)
+    out={_:__ for _,__ in params.items()}
+    out.update(label=label,ticker=ticker)
+    return out
+
+def _build_period_struct(
+    period=None, # has precedence over start, end
+    start=None,
+    end=None,
+    lookback=None,
+    _default_start=None,
+    _default_end=None,
+    ):
+    # period => start,end
+
+    if period:
+        if _isscalar(period):
+            period=[period]
+        period=[_ if isinstance(_,str) else "" for _ in period]
+        start=[]
+        end=[]
+        period_parse=[_.split(":") if ":" in _ else ["",""] for _ in period]
+        start=[_[0] for _ in period_parse]
+        end=[_[1] for _ in period_parse]
+
+    # align start,end
+    if _isscalar(start):
+        start=[start]
+    if _isscalar(end):
+        end=[end]
+    if _isscalar(lookback):
+        lookback=[lookback]
+
+
+    num_periods=max(len(start),len(end),len(lookback))
+    if len(start)==1:
+        start=start*num_periods
+    if len(end)==1:
+        end=end*num_periods
+    if len(lookback)==1:
+        lookback=lookback*num_periods
+    if len(start)!=num_periods:
+        warnings.warn('mismatch len(start)!=num_periods')
+    if len(end)!=num_periods:
+        warnings.warn('mismatch len(end)!=num_periods')
+    if len(lookback)!=num_periods:
+        warnings.warn('mismatch len(lookback)!=num_periods')
+    
+    # end x lookback => start
+    end=[_ if _ else _default_end for _ in end]
+    start=[_computestart(start_i,end_i,lookback_i) for start_i,end_i,lookback_i in zip(start,end,lookback)]
+    start=[_ if _ else _default_start for _ in start]
+    
+    return [
+        dict(
+            start=start_i,
+            end=end_i,
+            lookback=_computelookback(start_i,end_i),
+            period=_computeperiod(start_i,end_i),
+            periodformat=_computeperiodformat(start_i,end_i),
+        )
+        for start_i, end_i in zip(start,end)
+    ]
+
+def _computelabel(params=None,ticker=None,label_as=None):
+    if not label_as:
+        label_as="ticker"
+    if "+" in label_as:
+        prefix_type,suffix_type=label_as.split("+")
+    else:
+        prefix_type,suffix_type=label_as,None
+    prefix=stat_dict[ticker][prefix_type]
+    if suffix_type=="lookback":
+        suffix=f"{params['lookback']}M"
+    elif suffix_type=="period":
+        suffix=params['periodformat']
+    else:
+        suffix=None
+    return f"{prefix} ({suffix})" if suffix else prefix
+    
+def configureParams(
+    _usecase=None,
+    stat=None,
+    label=None,
+    label_as=None,
+    **providedPeriodInputs
+    ):
+    usecasemap={
+        1:dict(start=None,end=None,stat="sharpe"),
+        2:dict(lookback=[12,18],label_as="ticker+lookback",stat=['sharpe','annvol']),
+        3:dict(start="2020-01",label_as="name+period",stat=['sharpe','annvol']),
+    }
+    if _usecase:
+        return configureParams(_default_start="2020-01",_default_end="2025-07",**usecasemap[_usecase])
+    
+
+    params=_build_period_struct(**providedPeriodInputs)
+    
+    
+    if _isscalar(stat):
+        stats=[stat]
+    else:
+        stats=stat
+    
+    if len(params)==1 and len(stats)>1:
+        params=params*len(stats)
+        
+    elif len(params)>1 and len(stats)==1:
+        stats=stats*len(params)
+    
+    if len(params)!=len(stats):
+        warnings.warn("mismatch len(params)!=len(stat_tickers)")
+
+    if _isscalar(label):
+        label=[label]
+    if len(label)==1:
+        label=label*len(params)
+    if len(params)!=len(label):
+        warnings.warn("mismatch len(params)!=len(label)")
+
+
+    out=[
+        _completeparams(params=param_i,ticker=ticker_i,label=label_i,label_as=label_as)
+        for param_i, ticker_i,label_i in zip(params,stats,label)
+    ]
+
+    return out
+    
+
+
+
+

pivotalpath/stats/wrapper.py

@@ -0,0 +1,51 @@
+import pandas as pd
+import pdb
+
+from . import kernel as statsKernel
+
+def _align2target(df,target=None):
+    out=pd.DataFrame(index=target.index,columns=df.columns)
+    common_idx=[_ for _ in target.index.tolist() if _ in df.index.tolist()]
+    out.loc[common_idx,:]=df.loc[common_idx,:].copy()
+    return out
+
+def basicstats(
+        df,
+        base=None,
+        riskfree=None,
+        ticker=None,
+        start=None,
+        end=None,
+        label=None,
+        _roundoff=6,
+        **overflowParams,
+    ):
+
+    if not ticker:
+        return pd.DataFrame()
+    
+    if any([start,end]):
+        df=df.loc[start:end]
+        if base is not None:
+            base=base.loc[start:end]   
+        if riskfree is not None:
+            riskfree=riskfree.loc[start:end]
+
+    if base is not None:
+        base=_align2target(base,target=df)
+    if riskfree is not None:
+        riskfree=_align2target(riskfree,target=df)
+    if not label:
+        label=ticker
+    
+    out=getattr(statsKernel,ticker)(df,base=base,riskfree=riskfree,start=None,end=None,label=None)
+    
+    if isinstance(out,pd.DataFrame):
+        out=out[out.columns[0]]
+    if isinstance(out,pd.Series):
+        out.name=label
+        out=round(out,_roundoff)
+
+    return out
+
+

pivotalpath/version.py

@@ -0,0 +1,2 @@
+"""Version information for pivotalpath."""
+__version__ = "1.0.0"

pivotalpath-1.0.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.1
+Name: pivotalpath
+Version: 1.0.0
+Summary: The industry standard for hedge fund indices data and analytics
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Requires-Python: >=3.7
+Requires-Dist: pandas >=1.3.0
+Requires-Dist: numpy >=1.20.0
+Requires-Dist: requests >=2.25.0
+Requires-Dist: python-dateutil >=2.8.0
+

pivotalpath-1.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+pivotalpath/__init__.py,sha256=JXuQsd1ojdAlHk2WPGh7L_votDt-BSWX3OH-Gqwju20,1463
+pivotalpath/version.py,sha256=i_J42cJKAhNEnqxy7xhrN3kJTwi8BRU5dVTdVERm0gc,69
+pivotalpath/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pivotalpath/core/__init__.py,sha256=EzD2XiPCsjHJCSrgVcZAcHgkFKPr6dEu7tMJriDQj_k,417
+pivotalpath/core/examples.py,sha256=CtCqNMCC2-P2mrInQeMvnpbGn-rtvkhzZ_a42mbz0eo,1970
+pivotalpath/core/important_tickers.py,sha256=xHOAR8wMTZXS5_0PH8_V6WFQpayxpqmcIPsi_yfnIp0,92
+pivotalpath/core/main_library.py,sha256=oTbxiYaVDXjmO3Jr18hjj3Y15PrI-R9KSBFBTM_yn-w,1486
+pivotalpath/data/__init__.py,sha256=tNyy_5DF0XGYxqO_SG0vWJfZmBuC437HY1dAwnH31Fw,3288
+pivotalpath/data/api.py,sha256=my_APfA0Mv_Fy97x2XHCswWfaotSJW_aMu2aPZXlcKQ,1132
+pivotalpath/data/utils.py,sha256=OYmRB2HSlX-7ESU2VokbnanaY97ACvWdFe72ZRH1rf0,1435
+pivotalpath/llm/__init__.py,sha256=q786GSBYq76CmF9xxAuwN-y1d04c25v0eI5hhPUjddY,459
+pivotalpath/llm/interface.py,sha256=P8V9GxEYJ-WLP8K_c9TXzOx3GhptHVNy-rt455ybMUc,7053
+pivotalpath/stats/__init__.py,sha256=z9XQKid32JI3G8KZBEfukmqhOCjMooD_9x-yZJ9bkJg,1378
+pivotalpath/stats/catalog.py,sha256=LJ_5JpV04b0i6DPa_LwWzXlXhzn2wsxkSS74jeV0uho,4306
+pivotalpath/stats/kernel.py,sha256=1X2oFYrjJBhEJ630PMIJWmgZimKgyjgVrmwbxRhDXcE,4940
+pivotalpath/stats/params.py,sha256=UuKMqFHB6nBslzTbCwzJKoEzSnEybdPdYnbJ7p3ECpY,5115
+pivotalpath/stats/wrapper.py,sha256=CW8R892dHufRh1fwm4aKtKPeZefMPqcgM92pwdF_P0g,1297
+pivotalpath-1.0.0.dist-info/METADATA,sha256=JlbGppWdC-pB6ZSLb8Qc4COIREeqKAgfeMQSpPKH8-M,358
+pivotalpath-1.0.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+pivotalpath-1.0.0.dist-info/top_level.txt,sha256=qFWuReiHrH_6fShiOREDcVd0PEbCvMhilLJDpOLQBY8,12
+pivotalpath-1.0.0.dist-info/RECORD,,

pivotalpath-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.42.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pivotalpath-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pivotalpath