Neste artigo, você vai aprender do absoluto zero a usar Python para calcular essas métricas para um ou mais FIIs, mesmo que você nunca tenha programado antes. Vamos usar um caminho simples: Google Colab, que roda no navegador e não exige instalação local. Se você gosta de usar Python aplicado à finanças, certamente poderá se interessar em saber como balancelar uma carteira de investimentos usando Python.

Por que calcular a rentabilidade é importante ?

Investir em FIIs (Fundos de Investimento Imobiliário) costuma ser associado a duas coisas: recebimento de proventos (dividendos) e variação do preço da cota. Quando alguém pergunta “qual foi a rentabilidade desse FII?”, a resposta correta depende do que você está medindo:

• Rentabilidade por preço: quanto a cota valorizou (ou desvalorizou).
• Rentabilidade total (total return): valorização da cota + dividendos recebidos no período.
• Dividend Yield (DY): uma medida de “quanto pagou de dividendos” em relação ao preço.

Entender como calcular cada método é importante para se ter uma clareza se os investimentos estão de acordo com o que foi plenajedo. Contudo, fazer várias contas seria muito trabalhoso e gastaria muito tempo, por esse motivo, iremos utilizar o python que é uma ferramenta muito poderosa para facilitar nossa vida.

Preparando o Ambiente

A maneira mais amigável para iniciantes é o Google Colab. Por esse motivo, iremos acessa-ló clicando aqui. Quando acessar, clique em New Notebook (ou “Novo notebook”). Em seguida, aparecerá blocos de código onde é possível executar códigos feitos em Python.

Como executar um bloco de código?

Depois que o código estiver escrito, clique no bloco e aperte Shift + Enter assim como é mostrado na imagem abaixo.

Note que na imagem acima eu só escrevi um comando print para testar se estava funcionando. Feito isso, pode excluir o comando print, não iremos precisar dele.

Instalando e importando as bibliotecas (com um comando)

Vamos usar três bibliotecas:

• pandas: para tabelas e cálculos
• yfinance: para baixar dados do Yahoo Finance
• matplotlib: para gráficos

Por padrão, o Google Colab já tem instaldo a biblioteca pandas e matplotlib. Dessa maneira, só precisamos instalar o biblioteca do yfinance e faremos isso colando comando abaixoem um bloco de código e executando-o.

    pip -q install yfinance==0.2.66

    
  

Agora iremos adicionar outro bloco de código e isso pode ser feito clicando em inserir e célula de código. Com um novo bloco de código inserido, iremos adicionar as seguintes linhas de código.

    import pandas as pd
import yfinance as yf
import matplotlib.pyplot as plt

plt.style.use("seaborn-v0_8")
    
  

No trecho acima, o que fizemos foi importar todas as bibliotecas que serão necessárias para desenvolvermos o programa. Se você nunca programou, pense em “bibliotecas” como caixas de ferramentas prontas.

Entendendo o dados: Preço e dividendos

Para buscarmos fundos imobiliários no Yahoo Finance devemos usar o sufixo .SA isso porque faz referência aos ativos listados na bolsa brasileira, a B3. Alguns exemplos de FII’s com esse sufixo são: HGLG11.SA, KNRI11.SA, MXRF11.SA. Além disso, quando queremos analisar a rentabilidade de ativos duas coisas são muito importantes, a primeira é o histórico da cotação pois permite calcular a rentabilidade de preço. A outra informação que iremos buscar é os dividendos que são pagamentos por cota ao longo do tempo para nos ajudar a calcular o dividend yield. Por fim, com essas duas informações conseguiremos calcular o total return.

Baixando preços históricos de um FII

A primeira coisa que devemos fazer é escolher algum FII. Por familiaridade, irei escolhei o HGLG11, mas sinta-se a vontade para escolher qualquer FII’s que quiser analisar, somente lembre-se que deverá usar o sufixo .SA, assim: HGHLG.SA. Escolhido o fundo imobiliário, iremos então implementar o trecho de código que busca essas informações na B3, conforme é apresentado abaixo.

    ticker = "HGLG11.SA"

precos = yf.download(ticker, start="2020-01-01", progress=False)
precos.head()

    
  

Cole esse código no bloco de código que você criou logo abaixo dos comandos de importação de biblioteca e então execute-o. Você notará que o resultado será semelhante ao apresentado na imagem a seguir.

Você notou que o código trouxe várias colunas ? No entanto, não iremos usar todas as colunas que foram apresentadas nesse print. Iremos usar somente a coluna “Close” pois significa o valor que o ativo encerrou em um determinado dia. Isso porque tende a ser melhor para séries históricas e é isso que precisamos.

Dessa maneira, iremos complementar esse código pegando o preço ajustado e plotando um gráfico mostrando como oscilou o preço desse ativo durante desde do ano de 2020 até o presente(2026).

    precos["Close"].plot(figsize=(12,4), title=f"Preço ajustado - {ticker}")
plt.xlabel("Data")
plt.ylabel("Preço (R$)")
plt.show()

    
  

Quando executarmos, será apresentando o seguinte gráfico abaixo.

Baixando dividendos históricos do FII

Para pegar os valores dos dividendos de um determinado fundo imobiliário precisamos adicionar um trecho de código ao bloco que escrevemos anteriormente. Adicionaremos três linhas responsáveis por definir o fundo imobiliário, o método que faz busca e o tratamento desses dados após a busca. Abaixo é apresentado o trecho de código.

    ativo = yf.Ticker(ticker)
dividendos = ativo.dividends
dividendos.head(), dividendos.tail()
    
  

Isso irá retornar Isso retorna uma tabela com o valor do dividendo por cota e a data do pagamento (ou data registrada na base).

No entanto, para visualizarmos essas informações plotaremos um gráfico para facilitar a visualização. Tal gráfico pode ser feito adicionando as linhas abaixo.

    dividendos.plot(kind="bar", figsize=(12,4), title=f"Dividendos - {ticker}")
plt.xlabel("Data")
plt.ylabel("R$ por cota")
plt.show()
    
  

O gráfico apresentado após executar esses dois trechos de códigos que adicionamos será semelhante ao apresentado abaixo.

Veja que, o HGLG11 históricamente paga aproximadamente R$ 1,10 para seus acionistas.

Importante: Dependendo do ticker e da fonte, os dividendos podem vir incompletos. Se isso acontecer, você ainda pode seguir com os cálculos usando o que estiver disponível, mas trate como aproximação.

Calculando rentabilidade por preço

Para calcular a rentabilidade por preço de um fundo imobiliário devemos aplicar a seguinte fórmula matemática:

Considerando essa equação, iremos aplica-lá ao Python pegando o preço de fechamento na data fina e inicial e então fazer a divisão e subtração mostrada na equação. Logo abaixo ainda no bloco que estamos escrevendo, colcaremos o seguinte código:

    preco_inicial = precos["Close"].iloc[0]
preco_final = precos["Close"].iloc[-1]

rent_preco = (preco_final / preco_inicial) - 1
print(f"Rentabilidade por preço: {rent_preco.item():.2%}")
    
  

Veremos que o resultado será um texto. Para o HGLG11 obtive a seguinte mensagem: Rentabilidade por preço: 6.32%. É um dado que faz sentido uma vez que na imagem gráfica que apresenta os dados de preço do ativo, seu preço atual não está tão diferente quando comparado ao início.

Calculando Dividend Yield (DY) dos últimos 12 meses

Para calcular o dividend yield de um ativo precisamos também recorrer a matemática, a fórmula que fornece o dividend yield é dada por:

Transcrevendo essa fórmula para o Python, temos o seguinte trecho de código.

    # 1. Normaliza os índices para garantir que são datas
precos.index = pd.to_datetime(precos.index)
dividendos.index = pd.to_datetime(dividendos.index)

# 2. Remove o fuso horário (tz-localize(None)) caso exista
if precos.index.tz is not None:
    precos.index = precos.index.tz_localize(None)

if dividendos.index.tz is not None:
    dividendos.index = dividendos.index.tz_localize(None)

data_fim = precos.index.max()
data_inicio_12m = data_fim - pd.DateOffset(months=12)

div_12m = dividendos[dividendos.index >= data_inicio_12m].sum()
preco_atual = precos["Close"].iloc[-1]

dy_12m = div_12m / preco_atual

print(f"Dividendos (12m): R$ {div_12m:.2f} por cota")
print(f"Preço atual: R$ {preco_atual.item():.2f}")
print(f"DY (12m): {dy_12m.item():.2%}")
   
  

Note que nesse código, para além de realizar o cálculo, antes de tudo foi feito um tratamento das datas. Isso porque é possível que as datas conflitem por conta do fuso horário. Por padrão o Python proíbe comparar uma data que “sabe onde está” com uma que não sabe.

O resultado dessa execução é apresentado logo abaixo.

Rentabilidade total 

Para calcularmos a rentabilidade total, devemos utilizar uma fórmula matemática dada por:

É importante lembrar que essa questão é aproximada pois não considera o reinvestimentos dos dividendos recebidos.

Aplicando essa equação ao bloco de código que estamos escrevendo, temos o seguinte trecho:

    data_inicio = precos.index.min()
data_fim = precos.index.max()

div_periodo = dividendos[(dividendos.index >= data_inicio) & (dividendos.index <= data_fim)].sum()

rent_total = ((preco_final + div_periodo) / preco_inicial) - 1

print(f"Dividendos no período: R$ {div_periodo:.2f} por cota")
print(f"Rentabilidade total (preço + dividendos): {rent_total.item():.2%}")
   
  

O resultado apresentado é:

Isso significa que durante todo o período definido pela data_inicio e data_fim se eu comprasse 1 cota do fundo imobiliário HGLG11 na data final eu teria uma rentabilidade de 43,71%. É importante ressaltar que não é a rentabilidade anualizada, mas de todo período.

Por que isso é uma aproximação?

Porque essa conta presume que você comprou exatamente no primeiro dia do histórico e não reinvestiu dividendos e manteve 1 cota o tempo todo. Ela é ótima para iniciantes e já dá um retrato bem mais fiel do que olhar apenas a cotação. Para adaptar a sua realidade, considere definir pelo tempo que você já tem o ativo e considere o reinvestimento.

Rentabilidade anualizada (CAGR)

CAGR significa Compound Annual Growth Rate, que em português é Taxa de Crescimento Anual Composta. O CAGR é a taxa média de crescimento de um investimento, receita ou qualquer indicador ao longo de um período, considerando o efeito de juros compostos, isto é, considerar que você irá reinvestir os proventos que receber. Ele mostra qual teria sido a taxa de crescimento constante ao ano para que um valor inicial chegasse ao valor final em determinado período.

Sabendo a fórmula e transcrevendo para o python temos o seguinte trecho de código.

    dias = (precos.index.max() - precos.index.min()).days
anos = dias / 365.25


valor_final_total = preco_final + div_periodo
cagr_total = (valor_final_total / preco_inicial) ** (1/anos) - 1
print(f"CAGR (total aproximado): {cagr_total.item():.2%} ao ano")

   
  

Quando colamos esse trecho de código no bloco de execução, temos o seguitne resultado.

Um valor adequado considerando que o HGLG11 é um fundo logístico.

Calculando rentabilidade para vários FIIs e comparando

Sabendo de todas essas informações, agora podemos aplicar em um exemplo prático: Como eu posso comparar vários ativos e analisar seus números com base nos cálculos que aprendemos anteriormente ? Isso é fácil ! O que precisamos fazer agora é definir quais são os ativos que queremos analisar e qual o período. Feito, isso usando uma estrutura de repetição do python calcularemos e trataremos os dados de cada ativo parqa que, no final possamos apresentar uma tabela com todoas essas informações. O código abaixo mostra detalhadamente como isso é feito.

    tickers = ["HGLG11.SA", "KNRI11.SA", "MXRF11.SA"]

inicio = "2022-01-01"
fim = None 

resultados = []

for t in tickers:

    precos_t = yf.download(t, start=inicio, end=fim, progress=False, auto_adjust=False)
    
    if precos_t.empty:
        continue
    
    ativo_t = yf.Ticker(t)
    div_t = ativo_t.dividends
    
    if isinstance(precos_t.columns, pd.MultiIndex):
        series_close = precos_t["Close"][t] 
    else:
        series_close = precos_t["Close"]
        
    series_close.index = series_close.index.tz_localize(None)
    div_t.index = div_t.index.tz_localize(None)

    preco_ini = float(series_close.iloc[0]) 
    preco_fim = float(series_close.iloc[-1])
    
    data_ini = series_close.index.min()
    data_fim = series_close.index.max()
    

    div_periodo_t = div_t[(div_t.index >= data_ini) & (div_t.index <= data_fim)].sum()
    

    rent_preco_t = (preco_fim / preco_ini) - 1
    

    rent_total_t = ((preco_fim + div_periodo_t) / preco_ini) - 1
    
    dias_t = (data_fim - data_ini).days
    anos_t = dias_t / 365.25
    
    cagr_total_t = ( (preco_fim + div_periodo_t) / preco_ini ) ** (1/anos_t) - 1 if anos_t > 0 else None
    
    resultados.append({
        "Ticker": t.replace(".SA",""),
        "Preço inicial (R$)": round(preco_ini, 2),
        "Preço final (R$)": round(preco_fim, 2),
        "Dividendos no período (R$)": round(div_periodo_t, 2),
        "Rentab. preço": rent_preco_t,
        "Rentab. total": rent_total_t,
        "CAGR total (a.a.)": cagr_total_t
    })

tabela = pd.DataFrame(resultados)

tabela_formatada = tabela.copy()
for col in ["Rentab. preço", "Rentab. total", "CAGR total (a.a.)"]:
    tabela_formatada[col] = tabela_formatada[col].map(lambda x: f"{x:.2%}" if pd.notnull(x) else "-")

tabela_formatada


   
  

Depois de executar esse código teremos como resultado uma tabela que é apresentada abaixo.