turingquant¶
turingquant
é uma biblioteca para coleta, análise e backtesting de ativos e estratégias financeiras.
O projeto está em desenvolvimento ativo pelos membros de Finanças Quantitativas do Grupo Turing.
A API de onde obtemos os dados fundamentalistas é a Alpha Vantage e você pode obter a chave de uso gratuitamente. Essa chave será necessária sempre que você utilizar as funções daily e intraday.
pip install turingquant
instala a última versão estável.
Módulos¶
turingquant.metrics |
Módulo para metrificação de ativos e retornos. |
turingquant.benchmark |
Módulo para comparação e benchmarking de ativos e retornos. |
turingquant.support |
Módulo para coletar informações de ações do mercado financeiro. |
turingquant.optimizers |
Módulo para otimização de portfólios. |
Módulo metrics¶
Módulo para metrificação de ativos e retornos.
-
turingquant.metrics.
alpha
(start_price, end_price, dividends)¶ Essa função, com o fornecimento do preço final, dos dividendos por ação e do preço inicial, a calcula o alfa de um ativo.
Parâmetros: - start_price (float) – preço inicial.
- end_price (float) – preço final.
- dividends (float) – dividendos por ação.
Retorno: alpha do ativo
Tipo de retorno: float
-
turingquant.metrics.
beta
(returns, benchmark)¶ Essa função, a partir do fornecimento dos retornos do ativo e do benchmark, calcula o beta do ativo.
Parâmetros: - returns (pd.Series) – série com o retorno do ativo.
- benchmark (pd.Series) – série com o retorno do benchmark.
Retorno: Beta do ativo
Tipo de retorno: float
-
turingquant.metrics.
cagr
(returns, time_scale=252)¶ Calcula o CAGR que é a taxa composta de crescimento anual. :param returns: série de retornos para a qual será calculado o drawdown. :type returns: pd.Series :param time_scale: fator de escala do cagr, que é o número de amostras em um ano. Caso fosse uma série temporal diária: 252; série temporal mensal: 12 :type time_scale: int
Retorno: cagr do ativo. Tipo de retorno: float
-
turingquant.metrics.
capm
(returns, market_returns, risk_free)¶ Essa função, com o fornecimento dos retornos de um portfólio ou ativo, dos retornos do mercado e da retorno sem risco, calcula o retorno esperado pela abordagem CAPM. Essa abordagem considera o mercado (benchmark) e as relações com os ativos como parâmetro para estimar o retorno esperado.
Parâmetros: - returns (pd.Series ou np.array) – vetor de retornos
- market_returns (pd.Series ou np.array) – vetor de retornos do mercado ou benchmark
- risk_free (float) – retorno livre de risco
Retorno: retorno esperado pela abordagem CAPM
Tipo de retorno: float
-
turingquant.metrics.
cumulative_returns
(returns, return_type)¶ Essa função permite o cálculo do retorno cumulativo ao longo do tempo.
Parâmetros: - returns (pd.Series) – série de retornos da ação ao longo do tempo;
- return_type (string) – tipo de retorno (simples - “simp” ou logarítmico - “log”) presente na série.
Retorno: série com os valores de retorno cumulativo ao longo do tempo
Tipo de retorno: pd.Series
-
turingquant.metrics.
drawdown
(returns)¶ Calcula o drawdown percentual para uma série de retornos.
Parâmetros: returns (pd.Series) – série de retornos para a qual será calculado o drawdown. Retorno: uma série com os valores percentuais do Drawdown. Tipo de retorno: pd.Series
-
turingquant.metrics.
ewma_volatility
(returns, window)¶ Essa função calcula a volatilidade por EWMA ao longo de um período.
Parâmetros: - returns (pd.Series) – série de retornos para o qual o EWMA será calculado.
- window (int) – janela móvel para cálculo da EWMA;
Retorno: uma série com os valores de EWMA dos últimos window dias
Tipo de retorno: pd.Series
-
turingquant.metrics.
garman_klass_volatility
(high_prices, low_prices, close_prices, open_prices, window, time_scale=1)¶ Estima a volatilidade a partir dos seguintes preços: alta, baixa, abertura e fechamento
Parâmetros: - high_prices (pd.DataFrame) – série de preços de alta de uma ação
- low_prices (pd.DataFrame) – série de preços de baixa de uma ação
- close_prices (pd.DataFrame) – série de preços de fechamento de uma ação
- open_prices (pd.DataFrame) – série de preços de abertura de uma ação
- window (int) – janela das estimativa de volatilidade
- time_scale (int) – fator de escala da volatilidade, por padrão é 1 (diária)
Retorno: série das estimativas de volatildade
Tipo de retorno: pd.Series
-
turingquant.metrics.
mar_ratio
(returns, time_window, time_scale=252)¶ Calcula e plota o drawdown percentual para uma série de retornos. :param returns: série de retornos para a qual será calculado o mar ratio. :type returns: pd.Series :param time_window: janela de tempo que o mar ratio será calculado em relação a escala de tempo. time_window = 3 e time_scale = 252 denota uma janela de 3 anos (Calmar Ratio). :type time_window: float :param time_scale: fator de escala do mar ratio, que é o número de amostras em um ano. Caso fosse uma série temporal diária: 252; série temporal mensal: 12 :type time_scale: int
Retorno: valor do mar ratio do ativo Tipo de retorno: float
-
turingquant.metrics.
parkinson_volatility
(high_prices, low_prices, window, time_scale=1, plot=False)¶ Estimando a volatilidade a partir dos preços de Alta e de Baixa
Parâmetros: - high (pd.DataFrame) – série de preços de alta de uma ação
- low (pd.DataFrame) – série de preços de baixa de uma ação
- window (int) – janela das estimativa de volatilidade
- time_scale (int) – fator de escala da volatilidade, por padrão é 1 (diária)
Retorno: série das estimativas de volatildade
Tipo de retorno: pd.Series
-
turingquant.metrics.
returns
(close_prices, return_type='simple')¶ Essa função permite o cálculo rápido do retorno de uma ação ao longo do tempo.
Parâmetros: - close_prices (pd.Series) – série de preços de fechamento que será utilizada de base para o cálculo do retorno;
- return_type (string) – tipo de retorno (simples - “simple” ou logarítmico - “log”) a ser calculado;
Retorno: série com os valores do retorno ao longo do tempo
Tipo de retorno: pd.Series
-
turingquant.metrics.
rolling_beta
(returns, benchmark, window=60)¶ Calcula o beta móvel para um ativo e um benchmark de referência, na forma de séries de retornos.
Parâmetros: - returns (array) – série de retornos para o qual o beta será calculado.
- benchmark (array) – série de retornos para usar de referência no cálculo do beta.
- window (int) – janela móvel para calcular o beta ao longo do tempo.
Retorno: uma série com os valores do Beta para os últimos window dias. A série não possui os window primeiros dias.
Tipo de retorno: pd.Series
-
turingquant.metrics.
rolling_sharpe
(returns, window, risk_free=0)¶ Calcula o sharpe móvel para um ativo e um benchmark de referência, na forma de séries de retornos.
Parâmetros: - returns (pd.Series) – série de retornos para o qual o Sharpe Ratio será calculado.
- window (int) – janela móvel para calcular o Sharpe ao longo do tempo.
- risk_free (float) – valor da taxa livre de risco para cálculo do Sharpe.
Retorno: uma série com os valores do Sharpe para os últimos window dias. A série não possui os window primeiros dias.
Tipo de retorno: pd.Series
-
turingquant.metrics.
rolling_std
(returns, window)¶ Essa função calcula volatilidade a partir do cálculo da desvio padrão móvel.
Parâmetros: - returns (pd.Series) – série de retornos para o qual o desvio padrão será calculado.
- window (int) – janela móvel para cálculo do desvio padrão móvel;
Retorno: uma série indexado à data com os valores de desvio padrão móvel dos últimos window dias
Tipo de retorno: pd.Series
-
turingquant.metrics.
sharpe_ratio
(returns, risk_free=0, time_scale=252)¶ Essa função, a partir da definição do parâmetro de retorno, fornece o sharpe ratio do ativo, com base na média histórica e desvio padrão dos retornos. O risk free considerado é nulo.
Parâmetros: - returns (pd.series) – série com o retorno do ativo.
- risk_free (float) – risk free utilizado para cálculo do sharpe ratio.
- time_scale (int) – fator de escala do sharpe ratio, que é o número de amostras em um ano. Caso fosse uma série temporal diária: 252; série temporal mensal: 12
Retorno: índice de sharpe do ativo.
Tipo de retorno: float
Módulo benchmark¶
Módulo para comparação e benchmarking de ativos e retornos.
-
turingquant.benchmark.
benchmark
(ticker, start: datetime.datetime, end: datetime.datetime, source='yahoo', plot=True)¶ Essa função fornece um plot de retorno acumulado de um ativo ao longo de um dado intervalo de tempo, definido pelos parâmetros start e end. Os dados são coletados da API do yahoo, caso haja dados faltantes, os retornos são contabilizados como nulos.
Parâmetros: - ticker (str) – recebe o ticker do papel que será obtido.
- start (datetime) – início do intervalo.
- end (datetime) – final do intervalo.
- plot (bool) – opcional; exibe o gráfico caso True.
Retorno: uma série de ativos indexados com o tempo com o retorno cumulativo para o período.
Tipo de retorno: pd.series
-
turingquant.benchmark.
benchmark_ibov
(start: datetime.datetime, end: datetime.datetime, source='yahoo', plot=True)¶ Essa função produz um plot da evolução do Índice Bovespa ao longo de um dado intervalo, definido pelos parâmetros start e end.
Parâmetros: - start (datetime) – início do intervalo.
- end (datetime) – final do intervalo.
- plot (bool) – opcional; exibe o gráfico caso True.
Retorno: uma série temporal com o retorno acumulado do Ibovespa para o período.
Tipo de retorno: pd.series
-
turingquant.benchmark.
benchmark_sp500
(start: datetime.datetime, end: datetime.datetime, source='yahoo', plot=True)¶ Essa função produz um plot da evolução do Índice S&P500 ao longo de um dado intervalo, definido pelos parâmetros start e end.
Parâmetros: - start (datetime) – início do intervalo.
- end (datetime) – final do intervalo.
- plot (bool) – opcional; exibe o gráfico caso True.
Retorno: uma série temporal com o retorno acumulado do S&P500 para o período.
Tipo de retorno: pd.series
Módulo support¶
Módulo para coletar informações de ações do mercado financeiro.
-
turingquant.support.
daily
(key, ticker, br=True)¶ Essa função entrega a cotação dia a dia de um produto negociado em bolsa com melhor formatação de dados que a biblioteca alpha_vantage.
Parâmetros: - key (str) – recebe a chave de uso do AlphaVantage
- ticker (str) – recebe o ticker do papel que será obtido
- br (str) – se True, adiciona «.SA» ao final do ticker, necessário para papéis brasileiros
Retorno: um dataframe contendo a cotação dia a dia do ativo.
Tipo de retorno: pd.DataFrame
-
turingquant.support.
get_annual_hpr
(ticker, period=252)¶ Essa função calcula o holding period return anual de junho
-
turingquant.support.
get_balance_sheet
(ticker, br=True)¶ Obtém o Balance Sheet ou o Balanço Patrimonial para a companhia do ticker desejado por meio do Yahoo! Finance.
Parâmetros: - ticker (str) – recebe o ticker do papel que será obtido
- br (str) – se True, adiciona «.SA» ao final do ticker, necessário para papéis brasileiros
Retorno: dataframe com os dados do relatório nos últimos anos.
Tipo de retorno: pd.DataFrame
-
turingquant.support.
get_cash_flow
(ticker, br=True)¶ Obtém o Cash Flow ou o Fluxo de Caixa para a companhia do ticker desejado por meio do Yahoo! Finance.
Parâmetros: - ticker (str) – recebe o ticker do papel que será obtido
- br (str) – se True, adiciona «.SA» ao final do ticker, necessário para papéis brasileiros
Retorno: dataframe com os dados do relatório nos últimos anos.
Tipo de retorno: pd.DataFrame
-
turingquant.support.
get_financials
(url)¶ Função de suporte, base para as funções get_income_statement(), get_balance_sheet() e get_cashflow().
-
turingquant.support.
get_fundamentus
(tickers)¶ Essa função obtém os dados patrimoniais de empresas por meio do site fundamentus.com.br, voltado para companias com papeis na B3.
Parâmetros: tickers (str / list) – string com tickers separados por espaço ou lista de tickers Retorno: dataframe contendo os dados patrimoniais (linhas) para os tickers dados (colunas) Tipo de retorno: pd.DataFrame
-
turingquant.support.
get_ibov
()¶ Essa função obtém informações sobre a composição atual do Índice Bovespa por meio do site da B3.
Retorno: dataframe contendo ticker, nome, tipo, quantidade e participação das companias constituintes do índice Tipo de retorno: pd.DataFrame
-
turingquant.support.
get_income_statement
(ticker, br=True)¶ Obtém o Income Statement ou a Demonstração do Resultado do Exercício (DRE) para a companhia do ticker desejado por meio do Yahoo! Finance.
Parâmetros: - ticker (str) – recebe o ticker do papel que será obtido
- br (str) – se True, adiciona «.SA» ao final do ticker, necessário para papéis brasileiros
Retorno: dataframe com os dados do relatório nos últimos anos.
Tipo de retorno: pd.DataFrame
-
turingquant.support.
get_sp500_tickers
()¶ Essa função obtém os tickers de todas as atuais constituientes do S&P500.
Retorno: lista com todos os tickers atuais do índice. Tipo de retorno: list
-
turingquant.support.
get_tickers
(setores='Todos')¶ Essa função obtém os tickers listados no site fundamentus.com.br consoante seus setores. Observação: o “setor” no site fundamentus.com.br corresponde ao “subsetor” na B3, e o “subsetor” nesse site corresponde ao “segmento” na B3.
Parâmetros: setores (str / list) – “Todos” para considerar todos os setores ou lista com os setores desejados Retorno: lista com todos os tickers listados para os setores pedidos Tipo de retorno: list
-
turingquant.support.
intraday
(key, ticker, br=True, interval='1min')¶ Essa função entrega a cotação intraday dos últimos 5 dias de um produto negociado em bolsa com melhor formatação de dados que a biblioteca alpha_vantage.
Parâmetros: - key (str) – recebe a chave de uso do AlphaVantage
- ticker (str) – recebe o ticker do papel que será obtido
- br (bool) – se True, adiciona «.SA» ao final do ticker, necessário para papeis brasileiros.
- interval (str) – recebe o período entre cada informação (1min, 5min, 15min, 30min, 60min)
Retorno: DataFrame contendo a cotação intraday dos últimos 5 dias.
Tipo de retorno: pd.DataFrame
Módulo optimizers¶
Módulo para otimização de portfólios.
-
class
turingquant.optimizers.
Markowitz
(df_close, num_portfolios=10000, risk_free=0)¶ Otimizador baseado na Teoria Moderna do Portfólio, de Harry Markowitz. A partir dos dados de fechamento, gera portfólios com pesos aleatórios e calcula os melhores pesos utilizando o risco e retorno da carteira.
- Parâmetros:
- df_close (pd.DataFrame): DataFrame com os preços de fechamento dos ativos num_portfolios (int): números de portfólios gerados risk_free (float): taxa de risco livre utilizada para cálculo do sharpe ratio.
- Atributos:
- wallets (dict): dicionário contendo os valores “weights”, “returns”, “vol” e “sharpe_ratio”
- de todos os portfólios gerados
-
best_portfolio
(method='sharpe_ratio')¶ Retorna os pesos do melhor portfólio de acordo com o método escolhido.
Parâmetros: method (string) – Método utilizado para indicar o melhor portfólio “sharpe_ratio” - Portfólio com melhor Sharpe ratio “volatility” - Portfólio com menor volatilidade “return” - Portfólio com maior retorno Retorno: Numpy array contendo os pesos do melhor portfólio. Tipo de retorno: weights (np.array)
-
plot_efficient_frontier
(method='sharpe_ratio')¶ Plota gráfico com a fronteira eficiente dos portfólios gerados.
Parâmetros: method (string) – Método utilizado para indicar o melhor portfólio “sharpe_ratio” - Portfólio com melhor Sharpe ratio “volatility” - Portfólio com menor volatilidade “return” - Portfólio com maior retorno