pyield 0.57.1__tar.gz → 0.58.0__tar.gz

{pyield-0.57.1 → pyield-0.58.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.57.1
+Version: 0.58.0
 Summary: Polars-powered toolkit for Brazilian fixed income analysis
 Keywords: fixed-income,brazil,finance,analysis,bonds
 Author: Carlos Carvalho
@@ -84,7 +84,7 @@ uv add pyield
 | `yd.ntnb1` | módulo | NTN-B1 (Educa+ e Renda+) | `NomeComercial`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `cotacao_curva_zero`, `taxa_curva_zero`, `pu`, `duration`, `dv01` |
 | `yd.ntnbp` | módulo | NTN-B Principal | `cotacao`, `taxa`, `pu`, `dv01` |
 | `yd.ntnc` | módulo | NTN-C | `dados`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `pu`, `taxa`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
-| `yd.ntnf` | módulo | NTN-F | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `pu`, `taxa`, `taxas_zero`, `premio`, `premio_limpo`, `premio_limpo_expr`, `rentabilidade`, `rentabilidade_expr`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
+| `yd.ntnf` | módulo | NTN-F | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `pu`, `taxa`, `taxas_zero`, `taxas_zero_forwards`, `premio`, `premio_limpo`, `premio_limpo_expr`, `rentabilidade`, `rentabilidade_expr`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
 | `yd.vna` | módulo | Valores nominais atualizados dos títulos públicos | `valor`, `historico`, `projetado`, `vigencia` |
 | `yd.copom` | módulo | Calendário automático do Copom | `calendario`, `proxima_reuniao` |
 | `yd.compromissadas(...)` | função | Leilões de operações compromissadas do BCB | `inicio`, `fim` |
@@ -102,6 +102,32 @@ documentação detalhada e as assinaturas públicas.
 
 ## Compatibilidade da API
 
+### Cotações em base 100 — 0.58.0
+
+As funções escalares de cálculo dos títulos também aceitam taxas percentuais
+explícitas, como `"5.75%"` ou `"5,75%"`, equivalentes a `0.0575`.
+Números continuam em formato decimal; strings sem `%` são rejeitadas.
+
+As funções `cotacao` de `yd.lft`, `yd.ntnb`, `yd.ntnc`, `yd.ntnbp` e
+`yd.ntnb1` passam a retornar base 100 com quatro casas decimais:
+`0.993651` passa a ser `99.3651`. As funções `pu` desses títulos recebem a
+cotação nessa mesma base e aplicam `VNA * cotacao / 100`.
+
+A coluna `valor_pagamento` de `fluxos_caixa` de NTN-B, NTN-C e NTN-B1 e o
+retorno de `ntnb1.cotacao_curva_zero` também passam para base 100. Esta última
+mantém a soma sem truncamento para calibrar a TIR equivalente.
+
+Para migrar, multiplique cotações e fluxos antigos armazenados por 100, remova
+multiplicações por 100 usadas apenas para exibir cotações e ajuste cálculos
+manuais de PU para dividir por 100. A composição `pu(vna, cotacao(...))`
+preserva a unidade e as regras de precisão do preço. Taxas continuam em formato
+decimal, e VNA e PU continuam em reais.
+
+As funções `yd.ltn.dv01` e `yd.ntnf.dv01` não recebem mais um PU de referência:
+calculam a redução do PU teórico para um aumento de 1 ponto-base na taxa.
+
+### Demais alterações
+
 Este resumo parte da API da `0.56.0`. Mudanças que já faziam parte dessa versão
 ou de versões anteriores estão no histórico das
 [releases do GitHub](https://github.com/crdcj/PYield/releases).
@@ -119,8 +145,11 @@ ou de versões anteriores estão no histórico das
 | `vna_projetado(...)` nos módulos de títulos | `yd.vna.projetado(titulo, data, vna_base, inflacao)` |
 | `vigencia(data)` nos módulos de títulos | `yd.vna.vigencia(titulo, data)` |
 
-Os módulos públicos de títulos ficam disponíveis na raiz, enquanto as
-implementações continuam organizadas internamente em `pyield/tpf/titulos/`.
+O namespace público segue a autonomia semântica do conceito que o usuário
+precisa conhecer, e não apenas a fonte dos dados ou sua relação temática com
+outro domínio. Por isso, conceitos como `yd.ltn`, `yd.ntnb`, `yd.vna` e `yd.rmd`
+ficam na raiz, enquanto as implementações podem continuar agrupadas
+internamente por domínio para manter o código coeso.
 Consulte as [releases](https://github.com/crdcj/PYield/releases) para o
 histórico completo.
 

{pyield-0.57.1 → pyield-0.58.0}/README.md

@@ -59,7 +59,7 @@ uv add pyield
 | `yd.ntnb1` | módulo | NTN-B1 (Educa+ e Renda+) | `NomeComercial`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `cotacao_curva_zero`, `taxa_curva_zero`, `pu`, `duration`, `dv01` |
 | `yd.ntnbp` | módulo | NTN-B Principal | `cotacao`, `taxa`, `pu`, `dv01` |
 | `yd.ntnc` | módulo | NTN-C | `dados`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `pu`, `taxa`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
-| `yd.ntnf` | módulo | NTN-F | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `pu`, `taxa`, `taxas_zero`, `premio`, `premio_limpo`, `premio_limpo_expr`, `rentabilidade`, `rentabilidade_expr`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
+| `yd.ntnf` | módulo | NTN-F | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `pu`, `taxa`, `taxas_zero`, `taxas_zero_forwards`, `premio`, `premio_limpo`, `premio_limpo_expr`, `rentabilidade`, `rentabilidade_expr`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
 | `yd.vna` | módulo | Valores nominais atualizados dos títulos públicos | `valor`, `historico`, `projetado`, `vigencia` |
 | `yd.copom` | módulo | Calendário automático do Copom | `calendario`, `proxima_reuniao` |
 | `yd.compromissadas(...)` | função | Leilões de operações compromissadas do BCB | `inicio`, `fim` |
@@ -77,6 +77,32 @@ documentação detalhada e as assinaturas públicas.
 
 ## Compatibilidade da API
 
+### Cotações em base 100 — 0.58.0
+
+As funções escalares de cálculo dos títulos também aceitam taxas percentuais
+explícitas, como `"5.75%"` ou `"5,75%"`, equivalentes a `0.0575`.
+Números continuam em formato decimal; strings sem `%` são rejeitadas.
+
+As funções `cotacao` de `yd.lft`, `yd.ntnb`, `yd.ntnc`, `yd.ntnbp` e
+`yd.ntnb1` passam a retornar base 100 com quatro casas decimais:
+`0.993651` passa a ser `99.3651`. As funções `pu` desses títulos recebem a
+cotação nessa mesma base e aplicam `VNA * cotacao / 100`.
+
+A coluna `valor_pagamento` de `fluxos_caixa` de NTN-B, NTN-C e NTN-B1 e o
+retorno de `ntnb1.cotacao_curva_zero` também passam para base 100. Esta última
+mantém a soma sem truncamento para calibrar a TIR equivalente.
+
+Para migrar, multiplique cotações e fluxos antigos armazenados por 100, remova
+multiplicações por 100 usadas apenas para exibir cotações e ajuste cálculos
+manuais de PU para dividir por 100. A composição `pu(vna, cotacao(...))`
+preserva a unidade e as regras de precisão do preço. Taxas continuam em formato
+decimal, e VNA e PU continuam em reais.
+
+As funções `yd.ltn.dv01` e `yd.ntnf.dv01` não recebem mais um PU de referência:
+calculam a redução do PU teórico para um aumento de 1 ponto-base na taxa.
+
+### Demais alterações
+
 Este resumo parte da API da `0.56.0`. Mudanças que já faziam parte dessa versão
 ou de versões anteriores estão no histórico das
 [releases do GitHub](https://github.com/crdcj/PYield/releases).
@@ -94,8 +120,11 @@ ou de versões anteriores estão no histórico das
 | `vna_projetado(...)` nos módulos de títulos | `yd.vna.projetado(titulo, data, vna_base, inflacao)` |
 | `vigencia(data)` nos módulos de títulos | `yd.vna.vigencia(titulo, data)` |
 
-Os módulos públicos de títulos ficam disponíveis na raiz, enquanto as
-implementações continuam organizadas internamente em `pyield/tpf/titulos/`.
+O namespace público segue a autonomia semântica do conceito que o usuário
+precisa conhecer, e não apenas a fonte dos dados ou sua relação temática com
+outro domínio. Por isso, conceitos como `yd.ltn`, `yd.ntnb`, `yd.vna` e `yd.rmd`
+ficam na raiz, enquanto as implementações podem continuar agrupadas
+internamente por domínio para manter o código coeso.
 Consulte as [releases](https://github.com/crdcj/PYield/releases) para o
 histórico completo.
 

{pyield-0.57.1 → pyield-0.58.0}/pyield/__init__.py

@@ -11,13 +11,12 @@ from pyield.futuro import di1
 # Ordem intencional: alguns módulos importam `di1` a partir de `pyield`
 # durante a inicialização do pacote.
 from pyield import cpm, copom, selic, tpf, vna
-from pyield.cpm import probabilidades as _cpm_probabilidades  # noqa: F401
 from pyield.bc.sgs import ptax, ptax_serie
 from pyield.compromissada import compromissadas
 from pyield.fwd import forward, forwards, forwards_expr
 from pyield.interpolador import Interpolador, interpolar
 from pyield.relogio import agora, hoje
-from pyield.tpf.rmd import rmd
+from pyield.rmd import rmd
 from pyield.tpf.titulos import lft, ltn, ntnb, ntnb1, ntnbp, ntnc, ntnf
 
 try:

{pyield-0.57.1 → pyield-0.58.0}/pyield/_internal/cache.py

@@ -15,6 +15,11 @@ def ttl_cache(ttl: int = _TTL_PADRAO, maxsize: int = _TAMANHO_MAXIMO):
     Args:
         ttl: Tempo de vida de cada entrada em segundos.
         maxsize: Número máximo de entradas no cache.
+
+    Notes:
+        O wrapper consome _atualizar=True para ignorar e renovar apenas a
+        entrada consultada. Erros são propagados, preservando a entrada
+        anterior até sua expiração.
     """
 
     def decorador(func):
@@ -22,9 +27,10 @@ def ttl_cache(ttl: int = _TTL_PADRAO, maxsize: int = _TAMANHO_MAXIMO):
 
         @wraps(func)
         def wrapper(*args, **kwargs):
+            atualizar = kwargs.pop("_atualizar", False)
             chave = (args, tuple(sorted(kwargs.items())))
             agora = time.monotonic()
-            if chave in _cache:
+            if not atualizar and chave in _cache:
                 resultado, expira_em = _cache[chave]
                 if agora < expira_em:
                     return resultado

{pyield-0.57.1 → pyield-0.58.0}/pyield/bc/leiloes.py

@@ -93,13 +93,13 @@ def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
         pl.when(pl.col("titulo") == "LTN")
         .then(
             ltn.dv01_expr(
-                "data_liquidacao", "data_vencimento", "taxa_media", "pu_medio"
+                "data_liquidacao", "data_vencimento", "taxa_media"
             )
         )
         .when(pl.col("titulo") == "NTN-F")
         .then(
             ntnf.dv01_expr(
-                "data_liquidacao", "data_vencimento", "taxa_media", "pu_medio"
+                "data_liquidacao", "data_vencimento", "taxa_media"
             )
         )
         .when(pl.col("titulo") == "NTN-B")

{pyield-0.57.1 → pyield-0.58.0}/pyield/cpm/__init__.py

@@ -350,3 +350,7 @@ def data(date: DateLike) -> pl.DataFrame:
         pl.col("preco_ajuste"),
         pl.col("dias_uteis"),
     ).sort("data_expiracao", "variacao_strike_bps")
+
+
+# Importado após as definições porque probabilidades utiliza este módulo.
+from pyield.cpm import probabilidades as probabilidades  # noqa: E402, PLC0414

pyield-0.58.0/pyield/cpm/probabilidades.py

@@ -0,0 +1,347 @@
+"""
+probabilidades — Probabilidades implícitas das reuniões do COPOM a partir dos
+preços das opções CPM.
+
+O contrato CPM é uma opção europeia cash-or-nothing. No apreçamento neutro ao
+risco, o preço de ajuste da B3 em pontos (0–100) representa a probabilidade
+implícita de cada cenário de alteração da Selic, descontada pela taxa DI até o
+vencimento (Manual de Apreçamento da B3, §3.5).
+
+Convenções de probabilidade
+---------------------------
+    prob_bruta = preco_ajuste * fator_desconto / 100
+
+            Probabilidade neutra ao risco direta segundo o Manual da B3 §3.5
+            (fórmula invertida):
+
+          p_n(K) = PR_n * exp(+n * r_n) / N
+
+      onde
+          PR_n  = preco_ajuste ("Preço de Referência" da B3, pontos 0–100)
+          N     = 100 (valor nocional fixo)
+          n     = dias_uteis / 252 (tempo em anos, convenção de dias úteis)
+          r_n   = ln(1 + taxa_di1) (taxa DI1 continuamente capitalizada até o
+                  vencimento)
+          taxa_di1 = taxa DI1 interpolada por flat-forward entre a data de
+                     referência e a data de expiração
+
+      O preco_ajuste de cpm.data() é o "Preço de Referência" oficial da B3,
+      obtido no endpoint CSV: o preço exibido no painel da B3 ("Probabilidades
+      da Taxa Selic Meta") e resultado da metodologia P1/P2/P3/P4 da B3. Pode
+      ser nulo para datas com mais de aproximadamente um mês, quando o
+      endpoint CSV não está disponível.
+
+      Pode não somar 1,0 por reunião devido ao spread entre oferta e demanda ou
+      ao apreçamento P1/P2 da B3. Quando dias_uteis == 0 (o próprio dia da
+      reunião), fator_desconto == 1,0 exatamente e prob_bruta se reduz a
+      preco_ajuste / 100.
+
+  prob = prob_bruta / soma(prob_bruta) no grupo de data_expiracao
+      Normalizada para que cada reunião some exatamente 1,0. Este é o ajuste de
+      apreçamento P3 da B3. Use esta coluna para análise de cenários e gráficos.
+
+  prob_acumulada = soma acumulada de prob, ordenada por
+      variacao_strike_bps em ordem crescente.
+
+Observações sobre preco_ajuste nulo
+-----------------------------------
+Às vezes os contratos CPM são listados sem preço de ajuste (não há apreçamento
+oficial da B3 para aquele strike na data, ou o endpoint CSV não está disponível
+para datas antigas). Strikes com preco_ajuste nulo são excluídos da saída de
+probabilidades porque:
+
+  1. Sua contribuição para a distribuição normalizada é indefinida.
+  2. ``group_by().agg(sum())`` do Polars retorna 0,0 (e não nulo) para grupos
+     totalmente nulos, o que quebraria a invariável ``prob.sum() == 1.0`` por
+     reunião.
+
+Como consequência, uma reunião em que TODOS os strikes listados tenham preços
+nulos (por exemplo, CPMH25 no dia da reunião do COPOM de janeiro de 2025) não
+aparecerá na saída. O ranking_reuniao é, portanto, atribuído somente entre as
+reuniões com preços e sempre forma uma sequência consecutiva [1, 2, ..., n].
+
+Observações sobre o fallback do DI1
+-----------------------------------
+Se os dados do DI1 não estiverem disponíveis para a data de referência (erro de
+rede, feriado etc.), taxa_di1 assume 0,0 e fator_desconto assume 1,0. Assim,
+prob_bruta se reduz a preco_ajuste / 100, equivalente à fórmula antiga
+(incorreta). Essa degradação é registrada como aviso, mas nunca gera uma
+exceção.
+"""
+
+import logging
+
+import polars as pl
+
+from pyield import cpm
+from pyield._internal.converters import converter_datas
+from pyield._internal.types import DateLike
+from pyield.futuro import di1
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Schema
+# ---------------------------------------------------------------------------
+
+
+def _empty_schema() -> pl.DataFrame:
+    return pl.DataFrame(
+        schema={
+            "data_referencia": pl.Date,
+            "data_fim_reuniao": pl.Date,
+            "data_expiracao": pl.Date,
+            "ranking_reuniao": pl.Int32,
+            "variacao_strike_bps": pl.Int32,
+            "dias_uteis": pl.Int32,
+            "preco_ajuste": pl.Float64,
+            "taxa_di1": pl.Float64,
+            "fator_desconto": pl.Float64,
+            "prob_bruta": pl.Float64,
+            "prob": pl.Float64,
+            "prob_acumulada": pl.Float64,
+        }
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _add_meeting_rank(df: pl.DataFrame) -> pl.DataFrame:
+    """
+    Adiciona ranking_reuniao: 1 = data_expiracao mais próxima, 2 = seguinte, etc.
+    Calculado como dense rank sobre data_expiracao.
+    """
+    return df.with_columns(
+        ranking_reuniao=pl.col("data_expiracao").rank("dense").cast(pl.Int32)
+    )
+
+
+def _add_discount_factors(df: pl.DataFrame) -> pl.DataFrame:
+    """
+    Adiciona as colunas de taxa DI1 e fator de desconto.
+
+    A função usa ``di1.interpolar_taxas()`` de forma vetorizada para buscar
+    todas as taxas DI1 em uma única chamada, com uma busca e um interpolador por
+    data_referencia única. Em seguida, calcula os fatores de desconto com
+    expressões Polars.
+
+    Método de interpolação
+    ----------------------
+    ``di1.interpolar_taxas()`` implementa o Manual da B3 §1.4.2 — Flat Forward
+    252, que interpola de forma log-linear os fatores acumulados do DI1 (valores
+    de PU):
+
+        fa_j = (1 + r_j)^(du_j/252)          # fator acumulado no vértice j
+        fa_k = (1 + r_k)^(du_k/252)          # fator acumulado no vértice k
+        ft   = (du - du_j) / (du_k - du_j)   # fração do intervalo
+        r    = (fa_j * (fa_k / fa_j)^ft)^(252/du) - 1
+
+    Isso equivale à interpolação log-linear dos preços de ajuste do DI1
+    (PU = 100_000 / (1+r)^(du/252)), daí a expressão "interpolação exponencial
+    dos preços de ajuste do DI1" no Manual de Apreçamento do CPM §3.5.
+
+    Não é o método §1.4.1 (Exponencial 252), que interpola diretamente as taxas:
+        r = (1 + r_j) * ((1 + r_k)/(1 + r_j))^ft - 1
+    Os dois métodos divergem alguns pontos-base em vencimentos intermediários
+    (por exemplo, aproximadamente 4,6 pontos-base em du=17 para taxas na faixa
+    da Selic em 2026).
+
+    Na ausência de dados do DI1, usa taxa_di1=0,0 e fator_desconto=1,0.
+    """
+    pairs = (
+        df.select("data_referencia", "data_expiracao", "dias_uteis")
+        .unique(subset=["data_referencia", "data_expiracao"])
+        .sort("data_referencia", "data_expiracao")
+    )
+
+    # Chamada vetorizada: um fetch por data_referencia única
+    try:
+        rates = di1.interpolar_taxas(
+            datas_referencia=pairs["data_referencia"],
+            datas_vencimento=pairs["data_expiracao"],
+            extrapolar=True,
+        )
+    except Exception:
+        logger.warning("Falha na busca DI1; usando fallback taxa=0.0.")
+        rates = pl.Series("taxa_interpolada", [None] * len(pairs), dtype=pl.Float64)
+
+    discount_df = (
+        pairs.with_columns(
+            taxa_di1=rates.fill_null(0.0).fill_nan(0.0),
+        )
+        .with_columns(
+            fator_desconto=(
+                (pl.col("dias_uteis") / 252 * (1 + pl.col("taxa_di1")).log()).exp()
+            ),
+        )
+        .select("data_referencia", "data_expiracao", "taxa_di1", "fator_desconto")
+    )
+
+    return df.join(discount_df, on=["data_referencia", "data_expiracao"], how="left")
+
+
+def _add_probabilities(df: pl.DataFrame) -> pl.DataFrame:
+    """
+    Adiciona as colunas prob_bruta, prob e prob_acumulada conforme o Manual da
+    B3 §3.5.
+
+    Assume que o DataFrame já foi filtrado para um tipo de opção e para linhas
+    com preco_ajuste não nulo, e que ``_add_discount_factors`` já foi chamada
+    para adicionar taxa_di1 e fator_desconto.
+
+    prob_bruta = preco_ajuste * fator_desconto / 100
+    prob = prob_bruta / soma(prob_bruta) no grupo de data_expiracao
+    prob_acumulada = soma acumulada de prob, ordenada por
+        variacao_strike_bps em ordem crescente.
+    """
+    df = _add_discount_factors(df)
+
+    return (
+        df.sort("data_expiracao", "variacao_strike_bps")
+        .with_columns(
+            prob_bruta=(pl.col("preco_ajuste") * pl.col("fator_desconto") / 100),
+        )
+        .with_columns(
+            prob=(
+                pl.col("prob_bruta") / pl.col("prob_bruta").sum().over("data_expiracao")
+            ),
+        )
+        .with_columns(prob_acumulada=pl.col("prob").cum_sum().over("data_expiracao"))
+    )
+
+
+# ---------------------------------------------------------------------------
+# API pública
+# ---------------------------------------------------------------------------
+
+
+def all_meetings(
+    date: DateLike,
+    option_type: str = "call",
+) -> pl.DataFrame:
+    """
+    Calcula as probabilidades implícitas de todas as reuniões do COPOM com
+    contratos CPM negociados na data informada em `date`.
+
+    Somente strikes com `preco_ajuste` não nulo são incluídos. Reuniões em que
+    todos os strikes listados têm preço nulo são excluídas integralmente (ver
+    as observações no nível do módulo).
+
+    Args:
+        date: Data de referência da consulta; aceita os formatos de `DateLike`.
+        option_type: Tipo de opção, `"call"` ou `"put"`. O padrão é `"call"`,
+            que na prática é o lado mais líquido.
+
+    Returns:
+        `polars.DataFrame` ordenado por `ranking_reuniao` e
+        `variacao_strike_bps`. Em caso de ausência de dados, retorna um
+        DataFrame vazio com o schema correto.
+
+    Output Columns:
+        - data_referencia (Date): Data de negociação.
+        - data_fim_reuniao (Date): Último dia da reunião do COPOM.
+        - data_expiracao (Date): Data de expiração do contrato CPM.
+        - ranking_reuniao (Int32): 1 para a reunião mais próxima com preços.
+        - variacao_strike_bps (Int32): Variação do strike em pontos-base,
+            crescente dentro de cada reunião.
+        - dias_uteis (Int32): Dias úteis até a expiração.
+        - preco_ajuste (Float64): Preço de Referência da B3 em pontos (0–100).
+        - taxa_di1 (Float64): Taxa DI1 interpolada até a expiração.
+        - fator_desconto (Float64): Fator aplicado na inversão da fórmula da B3,
+            calculado como `exp(dias_uteis / 252 * ln(1 + taxa_di1))`.
+        - prob_bruta (Float64): Probabilidade antes da normalização,
+            calculada como `preco_ajuste * fator_desconto / 100`.
+        - prob (Float64): Probabilidade normalizada, calculada como
+            `prob_bruta / soma(prob_bruta)` por `data_expiracao`, com soma
+            1,0 por reunião.
+        - prob_acumulada (Float64): Probabilidade acumulada em ordem
+            crescente de strike.
+
+    Examples:
+        >>> import pyield as yd
+        >>> import polars as pl
+        >>> df = yd.cpm.probabilidades.all_meetings("29-01-2025")  # doctest: +SKIP
+        >>> df.is_empty() or df["ranking_reuniao"].min() == 1  # doctest: +SKIP
+        True
+        >>> sums = df.group_by("data_expiracao").agg(
+        ...     pl.col("prob").sum()
+        ... )  # doctest: +SKIP
+        >>> df.is_empty() or (sums["prob"] - 1.0).abs().max() < 1e-9  # doctest: +SKIP
+        True
+    """
+    raw = cpm.data(date)
+    if raw.is_empty():
+        return _empty_schema()
+
+    df = (
+        raw.filter(pl.col("tipo_opcao") == option_type)
+        # Excluir strikes sem preço de ajuste — ver docstring do módulo.
+        .filter(pl.col("preco_ajuste").is_not_null())
+        .pipe(_add_meeting_rank)
+        .pipe(_add_probabilities)
+        .select(
+            "data_referencia",
+            "data_fim_reuniao",
+            "data_expiracao",
+            "ranking_reuniao",
+            "variacao_strike_bps",
+            "dias_uteis",
+            "preco_ajuste",
+            "taxa_di1",
+            "fator_desconto",
+            "prob_bruta",
+            "prob",
+            "prob_acumulada",
+        )
+        .sort("ranking_reuniao", "variacao_strike_bps")
+    )
+
+    return df if not df.is_empty() else _empty_schema()
+
+
+def meeting(
+    date: DateLike,
+    expiration: DateLike | None = None,
+    option_type: str = "call",
+) -> pl.DataFrame:
+    """
+    Calcula as probabilidades implícitas de uma única reunião do COPOM.
+
+    Args:
+        date: Data de referência da consulta.
+        expiration: Data de expiração do contrato CPM da reunião desejada, ou
+            `None` para selecionar a reunião mais próxima com preços. A expiração
+            corresponde ao primeiro dia útil após o término da reunião.
+        option_type: Tipo de opção, `"call"` ou `"put"`. O padrão é `"call"`.
+
+    Returns:
+        `polars.DataFrame` com o mesmo schema de `all_meetings()`, filtrado
+        para uma única reunião. `ranking_reuniao` é sempre 1 nesta saída,
+        relativo à reunião selecionada, e não ao conjunto de reuniões.
+
+    Examples:
+        >>> import pyield as yd
+        >>> df = yd.cpm.probabilidades.meeting("29-01-2025")  # doctest: +SKIP
+        >>> df.is_empty() or abs(df["prob"].sum() - 1.0) < 1e-9  # doctest: +SKIP
+        True
+        >>> df.is_empty() or df["prob_acumulada"].tail(
+        ...     1
+        ... ).item() == 1.0  # doctest: +SKIP
+        True
+    """
+    df = all_meetings(date, option_type=option_type)
+    if df.is_empty():
+        return _empty_schema()
+
+    if expiration is None:
+        target_expiry = df.filter(pl.col("ranking_reuniao") == 1)["data_expiracao"][0]
+    else:
+        target_expiry = converter_datas(expiration)
+
+    return df.filter(pl.col("data_expiracao") == target_expiry).with_columns(
+        ranking_reuniao=pl.lit(1, dtype=pl.Int32)
+    )

{pyield-0.57.1 → pyield-0.58.0}/pyield/fwd.py

@@ -20,15 +20,9 @@ def forwards_expr(
     DI1), onde ``agrupar_por`` define janelas independentes de cálculo sem que
     seja necessário extrair colunas, calcular fora e juntar de volta.
 
-    A fórmula da taxa a termo entre os vértices ``j`` (anterior) e ``k``
-    (atual) é:
-
-    \[
-    fwd_k = \left( \frac{f_k^{au_k}}{f_j^{au_j}} \right)^{\frac{1}{au_k - au_j}} - 1
-    \]
-
-    Onde ``fₓ = 1 + txₓ`` e ``auₓ = duₓ/252``. A primeira linha de cada grupo
-    (menor ``dias_uteis``) é tratada como spot: ``fwd = tx``.
+    A taxa a termo entre os vértices ``j`` (anterior) e ``k`` (atual) segue a
+    fórmula documentada em :func:`forward`. A primeira linha de cada grupo
+    (menor ``dias_uteis``) é tratada como spot: ``f = tx``.
 
     Ordenação cronológica:
         A expressão usa ``shift(1).over(agrupar_por, order_by=dias_uteis)``,
@@ -161,14 +155,13 @@ def forwards_expr(
     tx_j = tx_k.shift(1).over(grupo, order_by=du_k)
     au_j = au_k.shift(1).over(grupo, order_by=du_k)
 
-    # fwdₖ = (fₖ^auₖ / fⱼ^auⱼ) ^ (1/(auₖ - auⱼ)) - 1, com fₓ = 1 + txₓ
-    fk = 1 + tx_k
-    fj = 1 + tx_j
-    taxa_forward = (fk**au_k / fj**au_j) ** (1 / (au_k - au_j)) - 1
+    ft_k = 1 + tx_k
+    ft_j = 1 + tx_j
+    f_k = (ft_k**au_k / ft_j**au_j) ** (1 / (au_k - au_j)) - 1
 
     # Primeira linha de cada grupo (menor dias_uteis) é a taxa spot
     eh_primeira = du_k == du_k.min().over(grupo)
-    return pl.when(eh_primeira).then(tx_k).otherwise(taxa_forward)
+    return pl.when(eh_primeira).then(tx_k).otherwise(f_k)
 
 
 def forwards(
@@ -179,36 +172,10 @@ def forwards(
     r"""
     Calcula taxas a termo a partir de taxas zero.
 
-    A taxa a termo no vértice 'n' é definida como:
-
-        fwdₖ = fwdⱼ→ₖ (a taxa a termo de j para k)
-
-    Definindo o fator de capitalização no vértice k como:
-
-        fₖ = 1 + txₖ
-
-    A fórmula utilizada é:
-
-        fwdₖ = (fₖ^(duₖ/252) / fⱼ^(duⱼ/252))^(252/(duₖ - duⱼ)) - 1
-
-    Como au = du/252 (tempo em anos úteis), a fórmula pode ser simplificada para:
-
-        fwdₖ = (fₖ^auₖ / fⱼ^auⱼ)^(1/(auₖ - auⱼ)) - 1
-
-    Em LaTeX, a fórmula é representada como:
-
-    \[
-    fwd_k = \left( \frac{f_k^{au_k}}{f_j^{au_j}} \right)^{\frac{1}{au_k - au_j}} - 1
-    \]
-
-    Onde:
-    - fⱼ é o fator de capitalização no vértice anterior (fⱼ = 1 + txⱼ).
-    - fₖ é o fator de capitalização no vértice atual (fₖ = 1 + txₖ).
-    - txⱼ é a taxa zero para o vértice anterior.
-    - txₖ é a taxa zero para o vértice atual.
-    - auⱼ é o prazo em anos úteis no vértice anterior (auⱼ = duⱼ/252).
-    - auₖ é o prazo em anos úteis no vértice atual (auₖ = duₖ/252).
-    - A constante 252 representa o número de dias úteis no ano.
+    A taxa a termo em cada vértice é calculada aplicando sucessivamente a
+    fórmula documentada em :func:`forward` aos vértices consecutivos. A
+    primeira taxa de cada grupo é a taxa zero do primeiro vértice, pois não há
+    um vértice anterior para calcular a taxa a termo.
 
     A função preserva a ordem original dos dados de entrada. Nulos em
     ``dias_uteis`` ou ``taxas`` produzem nulo na linha correspondente; NaN
@@ -394,29 +361,16 @@ def forward(
     r"""
     Calcula a taxa a termo entre dois prazos (dias úteis).
 
-    Utiliza a fórmula:
-
-        f₁→₂ = (f₂^(du₂/252) / f₁^(du₁/252))^(252/(du₂ - du₁)) - 1
-
-    Onde:
-        - f₁ é o fator de capitalização do primeiro prazo (f₁ = 1 + tx₁).
-        - f₂ é o fator de capitalização do segundo prazo (f₂ = 1 + tx₂).
-        - tx₁ é a taxa zero para o primeiro prazo (du₁).
-        - tx₂ é a taxa zero para o segundo prazo (du₂).
-        - du₁ é o número de dias úteis até a primeira data.
-        - du₂ é o número de dias úteis até a segunda data.
-        - A constante 252 representa o número de dias úteis no ano.
-
-    Como au = du/252 (tempo em anos úteis), a fórmula pode ser simplificada para:
-
-        f₁→₂ = (f₂^au₂ / f₁^au₁)^(1/(au₂ - au₁)) - 1
-
-    Que em latex fica:
+    Definindo \(F_i = 1 + tx_i\) e \(t_i = du_i/252\), onde 252 é o
+    número de dias úteis no ano, a fórmula é:
 
     \[
-    f_{1 \rightarrow 2} = \left( \frac{f_2^{au_2}}{f_1^{au_1}} \right)^{\frac{1}{au_2 - au_1}} - 1
+    f_{1 \rightarrow 2} = \left( \frac{F_2^{t_2}}{F_1^{t_1}} \right)^{\frac{1}{t_2 - t_1}} - 1
     \]
 
+    Aqui, ``F₁`` e ``F₂`` são os fatores de capitalização dos prazos ``du1``
+    e ``du2``, e ``tx1`` e ``tx2`` são as respectivas taxas zero.
+
     Args:
         du1 (int): Número de dias úteis do primeiro ponto (prazo menor).
         du2 (int): Número de dias úteis do segundo ponto (prazo maior).
@@ -453,9 +407,7 @@ def forward(
     au2 = du2 / 252
 
     # Definição dos fatores de capitalização:
-    # f₁ = 1 + tx₁ e f₂ = 1 + tx₂
-    f1 = 1 + taxa1
-    f2 = 1 + taxa2
+    ft1 = 1 + taxa1
+    ft2 = 1 + taxa2
 
-    # f₁→₂ = (f₂^au₂ / f₁^au₁)^(1/(au₂ - au₁)) - 1
-    return (f2**au2 / f1**au1) ** (1 / (au2 - au1)) - 1
+    return (ft2**au2 / ft1**au1) ** (1 / (au2 - au1)) - 1