dashgusbr 0.1.0__py3-none-any.whl

dashgusbr/__init__.py

@@ -0,0 +1,39 @@
+"""dashgusbr — consumo e visualização do histórico do Campeonato Brasileiro.
+
+Camada de consumo da arquitetura serverless do projeto Infra-Brasileirao:
+lê a OBT (One Big Table) publicada pelo pipeline ETL (CSV no GitHub, com
+fallback para Google Sheets) e oferece análises em Pandas e gráficos Plotly.
+
+Uso rápido::
+
+    from dashgusbr import Brasileirao
+
+    br = Brasileirao()
+    br.tabela(2023)                      # DataFrame da classificação
+    br.plot_confronto("Flamengo", "Palmeiras").show()
+
+Uso avançado (camadas puras)::
+
+    from dashgusbr import analytics, data, viz
+
+    df = data.carregar_dados()
+    tab = analytics.classificacao(df, ano=2023)
+    fig = viz.classificacao(tab)
+"""
+
+from . import analytics, config, data, schema, viz
+from .client import Brasileirao
+from .data import carregar_dados
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Brasileirao",
+    "carregar_dados",
+    "analytics",
+    "config",
+    "data",
+    "schema",
+    "viz",
+    "__version__",
+]

dashgusbr/_theme.py

@@ -0,0 +1,113 @@
+"""Tema visual da dashgusbr (template Plotly + paleta).
+
+Paleta validada para daltonismo (deutan/protan/tritan) em modo claro:
+ordem fixa dos slots categóricos — nunca ciclar nem reordenar, a ordem é o
+mecanismo de segurança para visão de cores. Sequencial = um matiz (azul),
+claro→escuro. Cinza neutro para categorias "sem lado" (empates).
+"""
+
+from __future__ import annotations
+
+import plotly.graph_objects as go
+import plotly.io as pio
+
+# Slots categóricos, em ordem fixa (identidade de séries)
+CORES_CATEGORICAS = [
+    "#2a78d6",  # 1 azul
+    "#008300",  # 2 verde
+    "#e87ba4",  # 3 magenta
+    "#eda100",  # 4 amarelo
+    "#1baf7a",  # 5 aqua
+    "#eb6834",  # 6 laranja
+    "#4a3aa7",  # 7 violeta
+    "#e34948",  # 8 vermelho
+]
+
+AZUL = CORES_CATEGORICAS[0]
+VERDE = CORES_CATEGORICAS[1]
+
+# Cinza neutro para marcas sem identidade de série (ex.: empates)
+CINZA_NEUTRO = "#898781"
+
+# Rampa sequencial (magnitude): azul claro→escuro
+RAMPA_SEQUENCIAL = [
+    "#cde2fb",
+    "#9ec5f4",
+    "#6da7ec",
+    "#3987e5",
+    "#256abf",
+    "#184f95",
+    "#0d366b",
+]
+
+# Superfície e tinta (chrome do gráfico)
+SUPERFICIE = "#fcfcfb"
+TINTA = "#0b0b0b"
+TINTA_SECUNDARIA = "#52514e"
+TINTA_MUTED = "#898781"
+GRADE = "#e1e0d9"
+EIXO = "#c3c2b7"
+
+FONTE = 'system-ui, -apple-system, "Segoe UI", sans-serif'
+
+TEMA = "dashgusbr"
+
+
+def escala_sequencial() -> list:
+    """Rampa sequencial no formato de colorscale do Plotly (0..1)."""
+    n = len(RAMPA_SEQUENCIAL) - 1
+    return [[i / n, cor] for i, cor in enumerate(RAMPA_SEQUENCIAL)]
+
+
+def registrar_tema() -> None:
+    """Registra (idempotente) o template ``dashgusbr`` no Plotly.
+
+    Não altera o template default global do usuário: cada figura da
+    biblioteca pede ``template="dashgusbr"`` explicitamente.
+    """
+    template = go.layout.Template(
+        layout=go.Layout(
+            paper_bgcolor=SUPERFICIE,
+            plot_bgcolor=SUPERFICIE,
+            colorway=CORES_CATEGORICAS,
+            font=dict(family=FONTE, color=TINTA, size=13),
+            title=dict(font=dict(size=16, color=TINTA), x=0, xanchor="left"),
+            margin=dict(l=64, r=32, t=64, b=48),
+            xaxis=dict(
+                gridcolor=GRADE,
+                linecolor=EIXO,
+                zerolinecolor=EIXO,
+                ticks="outside",
+                tickcolor=EIXO,
+                title=dict(font=dict(color=TINTA_SECUNDARIA)),
+                tickfont=dict(color=TINTA_MUTED, size=12),
+            ),
+            yaxis=dict(
+                gridcolor=GRADE,
+                linecolor=EIXO,
+                zerolinecolor=EIXO,
+                ticks="outside",
+                tickcolor=EIXO,
+                title=dict(font=dict(color=TINTA_SECUNDARIA)),
+                tickfont=dict(color=TINTA_MUTED, size=12),
+            ),
+            legend=dict(
+                orientation="h",
+                yanchor="bottom",
+                y=1.02,
+                xanchor="left",
+                x=0,
+                font=dict(color=TINTA_SECUNDARIA, size=12),
+            ),
+            hoverlabel=dict(
+                bgcolor="#ffffff",
+                bordercolor=GRADE,
+                font=dict(family=FONTE, color=TINTA, size=12),
+            ),
+            hovermode="closest",
+        )
+    )
+    pio.templates[TEMA] = template
+
+
+registrar_tema()

dashgusbr/analytics.py

@@ -0,0 +1,363 @@
+"""Agregações analíticas sobre a OBT do Brasileirão.
+
+Funções puras: recebem o DataFrame no schema canônico e devolvem DataFrames
+(ou dicts) prontos para consumo ou visualização. Nenhuma função acessa rede
+ou estado global — a carga é responsabilidade de :mod:`dashgusbr.data`.
+
+Nota sobre pontuação: as colunas ``pontos_mandante``/``pontos_visitante`` já
+vêm calculadas pelo ETL respeitando a regra da época (vitória valia 2 pontos
+até 1994 e 3 pontos a partir de 1995). Por isso as agregações SOMAM esses
+pontos em vez de recalcular 3-1-0, e o aproveitamento é normalizado pelo
+valor da vitória vigente em cada temporada.
+"""
+
+from __future__ import annotations
+
+import difflib
+from typing import Optional
+
+import pandas as pd
+
+from .schema import TIPO_FASE_PONTOS_CORRIDOS
+
+# ---------------------------------------------------------------------------
+# Helpers internos
+# ---------------------------------------------------------------------------
+
+
+def _validar_ano(df: pd.DataFrame, ano: int) -> None:
+    anos = df["ano_campeonato"].dropna().unique()
+    if ano not in anos:
+        raise ValueError(
+            f"Temporada {ano} não encontrada. Dados disponíveis de "
+            f"{int(anos.min())} a {int(anos.max())}."
+        )
+
+
+def _validar_time(df: pd.DataFrame, time: str) -> None:
+    times = pd.unique(pd.concat([df["mandante"], df["visitante"]]).dropna())
+    if time not in times:
+        sugestoes = difflib.get_close_matches(time, list(times), n=3)
+        dica = f" Você quis dizer: {', '.join(sugestoes)}?" if sugestoes else ""
+        raise ValueError(f"Time {time!r} não encontrado na base.{dica}")
+
+
+def _pontos_corridos(df: pd.DataFrame) -> pd.DataFrame:
+    """Mantém apenas jogos que contam para a tabela (fase de pontos corridos)."""
+    return df[df["tipo_fase"] == TIPO_FASE_PONTOS_CORRIDOS]
+
+
+def _com_placar(df: pd.DataFrame) -> pd.DataFrame:
+    return df.dropna(subset=["gols_mandante", "gols_visitante"])
+
+
+def _formato_longo(df: pd.DataFrame) -> pd.DataFrame:
+    """Uma linha por (partida, time): a partida vista da perspectiva de cada lado."""
+    mandante = pd.DataFrame(
+        {
+            "id_partida": df["id_partida"],
+            "ano_campeonato": df["ano_campeonato"],
+            "data": df["data"],
+            "time": df["mandante"],
+            "adversario": df["visitante"],
+            "local": "mandante",
+            "gols_pro": df["gols_mandante"],
+            "gols_contra": df["gols_visitante"],
+            "resultado": df["resultado_mandante"],
+            "pontos": df["pontos_mandante"],
+        }
+    )
+    visitante = pd.DataFrame(
+        {
+            "id_partida": df["id_partida"],
+            "ano_campeonato": df["ano_campeonato"],
+            "data": df["data"],
+            "time": df["visitante"],
+            "adversario": df["mandante"],
+            "local": "visitante",
+            "gols_pro": df["gols_visitante"],
+            "gols_contra": df["gols_mandante"],
+            "resultado": df["resultado_visitante"],
+            "pontos": df["pontos_visitante"],
+        }
+    )
+    return pd.concat([mandante, visitante], ignore_index=True)
+
+
+def _valor_vitoria(df_temporada: pd.DataFrame) -> int:
+    """Quantos pontos valia a vitória na temporada (2 até 1994, 3 depois)."""
+    pontos = pd.concat(
+        [df_temporada["pontos_mandante"], df_temporada["pontos_visitante"]]
+    ).dropna()
+    if pontos.empty:
+        return 3
+    return int(pontos.max())
+
+
+# ---------------------------------------------------------------------------
+# Classificação
+# ---------------------------------------------------------------------------
+
+
+def classificacao(df: pd.DataFrame, ano: int) -> pd.DataFrame:
+    """Tabela de classificação da fase de pontos corridos de uma temporada.
+
+    Colunas: posicao, time, pontos, jogos, vitorias, empates, derrotas,
+    gols_pro, gols_contra, saldo, aproveitamento (%). Desempate no critério
+    CBF: pontos, vitórias, saldo de gols, gols pró.
+    """
+    _validar_ano(df, ano)
+    temporada = _com_placar(_pontos_corridos(df[df["ano_campeonato"] == ano]))
+    longo = _formato_longo(temporada)
+
+    tabela = (
+        longo.groupby("time")
+        .agg(
+            pontos=("pontos", "sum"),
+            jogos=("id_partida", "count"),
+            vitorias=("resultado", lambda r: int((r == "V").sum())),
+            empates=("resultado", lambda r: int((r == "E").sum())),
+            derrotas=("resultado", lambda r: int((r == "D").sum())),
+            gols_pro=("gols_pro", "sum"),
+            gols_contra=("gols_contra", "sum"),
+        )
+        .reset_index()
+    )
+    tabela["saldo"] = tabela["gols_pro"] - tabela["gols_contra"]
+
+    valor_vitoria = _valor_vitoria(temporada)
+    tabela["aproveitamento"] = (
+        100 * tabela["pontos"] / (tabela["jogos"] * valor_vitoria)
+    ).astype(float).round(1)
+
+    tabela = tabela.sort_values(
+        by=["pontos", "vitorias", "saldo", "gols_pro", "time"],
+        ascending=[False, False, False, False, True],
+        ignore_index=True,
+    )
+    tabela.insert(0, "posicao", tabela.index + 1)
+    return tabela
+
+
+# ---------------------------------------------------------------------------
+# Evolução e histórico de um time
+# ---------------------------------------------------------------------------
+
+
+def evolucao_pontos(df: pd.DataFrame, time: str, ano: int) -> pd.DataFrame:
+    """Pontuação acumulada de um time, jogo a jogo, dentro de uma temporada.
+
+    A OBT não publica número de rodada, então a linha do tempo é ordenada
+    pela data da partida (coluna ``jogo`` = 1º, 2º, 3º... jogo do time).
+    """
+    _validar_ano(df, ano)
+    _validar_time(df, time)
+    temporada = _com_placar(_pontos_corridos(df[df["ano_campeonato"] == ano]))
+    longo = _formato_longo(temporada)
+    jogos = (
+        longo[longo["time"] == time]
+        .sort_values(["data", "id_partida"])
+        .reset_index(drop=True)
+    )
+    if jogos.empty:
+        raise ValueError(f"{time!r} não disputou pontos corridos em {ano}.")
+    jogos.insert(0, "jogo", jogos.index + 1)
+    jogos["pontos_acumulados"] = jogos["pontos"].cumsum().astype("Int64")
+    return jogos[
+        [
+            "jogo",
+            "data",
+            "time",
+            "adversario",
+            "local",
+            "gols_pro",
+            "gols_contra",
+            "resultado",
+            "pontos",
+            "pontos_acumulados",
+        ]
+    ]
+
+
+def historico_time(df: pd.DataFrame, time: str) -> pd.DataFrame:
+    """Desempenho de um time temporada a temporada (posição, pontos, aproveitamento).
+
+    O aproveitamento é comparável entre eras (normalizado pelo valor da
+    vitória de cada temporada); a posição vem da classificação completa
+    da fase de pontos corridos de cada ano.
+    """
+    _validar_time(df, time)
+    pontos_corridos = _pontos_corridos(df)
+    anos = sorted(
+        pontos_corridos[
+            (pontos_corridos["mandante"] == time)
+            | (pontos_corridos["visitante"] == time)
+        ]["ano_campeonato"].dropna().unique()
+    )
+    linhas = []
+    for ano in anos:
+        tabela = classificacao(df, int(ano))
+        linha = tabela[tabela["time"] == time]
+        if linha.empty:
+            continue
+        registro = linha.iloc[0].to_dict()
+        registro["ano_campeonato"] = int(ano)
+        linhas.append(registro)
+    if not linhas:
+        raise ValueError(f"{time!r} nunca disputou fases de pontos corridos na base.")
+    historico = pd.DataFrame(linhas)
+    colunas = ["ano_campeonato"] + [c for c in historico.columns if c != "ano_campeonato"]
+    return historico[colunas].reset_index(drop=True)
+
+
+# ---------------------------------------------------------------------------
+# Confronto direto
+# ---------------------------------------------------------------------------
+
+
+def confronto(df: pd.DataFrame, time_a: str, time_b: str) -> dict:
+    """Histórico do confronto direto entre dois times (todas as fases).
+
+    Retorna um dict com o resumo (jogos, vitórias de cada lado, empates,
+    gols) e o DataFrame ``partidas`` com todos os jogos, do mais antigo ao
+    mais recente.
+    """
+    _validar_time(df, time_a)
+    _validar_time(df, time_b)
+    if time_a == time_b:
+        raise ValueError("Informe dois times diferentes para o confronto.")
+
+    partidas = _com_placar(
+        df[
+            ((df["mandante"] == time_a) & (df["visitante"] == time_b))
+            | ((df["mandante"] == time_b) & (df["visitante"] == time_a))
+        ]
+    ).sort_values(["data", "id_partida"]).reset_index(drop=True)
+
+    a_mandante = partidas["mandante"] == time_a
+    vitorias_a = (
+        (a_mandante & (partidas["resultado_mandante"] == "V"))
+        | (~a_mandante & (partidas["resultado_visitante"] == "V"))
+    ).sum()
+    vitorias_b = (
+        (~a_mandante & (partidas["resultado_mandante"] == "V"))
+        | (a_mandante & (partidas["resultado_visitante"] == "V"))
+    ).sum()
+    empates = (partidas["resultado_mandante"] == "E").sum()
+    gols_a = (
+        partidas.loc[a_mandante, "gols_mandante"].sum()
+        + partidas.loc[~a_mandante, "gols_visitante"].sum()
+    )
+    gols_b = (
+        partidas.loc[~a_mandante, "gols_mandante"].sum()
+        + partidas.loc[a_mandante, "gols_visitante"].sum()
+    )
+
+    return {
+        "time_a": time_a,
+        "time_b": time_b,
+        "jogos": int(len(partidas)),
+        "vitorias_a": int(vitorias_a),
+        "empates": int(empates),
+        "vitorias_b": int(vitorias_b),
+        "gols_a": int(gols_a),
+        "gols_b": int(gols_b),
+        "partidas": partidas,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Estatísticas agregadas do campeonato
+# ---------------------------------------------------------------------------
+
+
+def estatisticas_temporada(df: pd.DataFrame) -> pd.DataFrame:
+    """Indicadores por temporada: jogos, gols, média de gols e mando de campo.
+
+    ``pct_vitorias_mandante``/``pct_empates``/``pct_vitorias_visitante`` medem
+    o peso do fator casa ao longo da história (somam 100% por temporada).
+    """
+    jogos = _com_placar(_pontos_corridos(df)).copy()
+    jogos["_gols_partida"] = jogos["gols_mandante"] + jogos["gols_visitante"]
+    stats = (
+        jogos.groupby("ano_campeonato")
+        .agg(
+            jogos=("id_partida", "count"),
+            gols=("_gols_partida", "sum"),
+            pct_vitorias_mandante=(
+                "resultado_mandante",
+                lambda r: round(100 * (r == "V").mean(), 1),
+            ),
+            pct_empates=(
+                "resultado_mandante",
+                lambda r: round(100 * (r == "E").mean(), 1),
+            ),
+            pct_vitorias_visitante=(
+                "resultado_mandante",
+                lambda r: round(100 * (r == "D").mean(), 1),
+            ),
+        )
+        .reset_index()
+    )
+    stats["media_gols"] = (stats["gols"] / stats["jogos"]).astype(float).round(2)
+    return stats[
+        [
+            "ano_campeonato",
+            "jogos",
+            "gols",
+            "media_gols",
+            "pct_vitorias_mandante",
+            "pct_empates",
+            "pct_vitorias_visitante",
+        ]
+    ]
+
+
+def distribuicao_placares(
+    df: pd.DataFrame, ano: Optional[int] = None, max_gols: int = 6
+) -> pd.DataFrame:
+    """Matriz de frequência de placares (gols do mandante × gols do visitante).
+
+    Placares com mais de ``max_gols`` de um dos lados são agrupados no último
+    bin para a matriz não explodir por causa de goleadas raras. Índice =
+    gols do mandante, colunas = gols do visitante, valores = nº de jogos.
+    """
+    jogos = _com_placar(df if ano is None else df[df["ano_campeonato"] == ano])
+    if ano is not None:
+        _validar_ano(df, ano)
+    gm = jogos["gols_mandante"].clip(upper=max_gols).astype(int)
+    gv = jogos["gols_visitante"].clip(upper=max_gols).astype(int)
+    matriz = pd.crosstab(gm, gv)
+    eixo = range(0, max_gols + 1)
+    matriz = matriz.reindex(index=eixo, columns=eixo, fill_value=0)
+    matriz.index.name = "gols_mandante"
+    matriz.columns.name = "gols_visitante"
+    return matriz
+
+
+def maiores_goleadas(df: pd.DataFrame, n: int = 10) -> pd.DataFrame:
+    """As ``n`` maiores goleadas da história (maior diferença de gols)."""
+    jogos = _com_placar(df).copy()
+    jogos["diferenca"] = (jogos["gols_mandante"] - jogos["gols_visitante"]).abs()
+    jogos["_gols_partida"] = jogos["gols_mandante"] + jogos["gols_visitante"]
+    jogos["placar"] = (
+        jogos["gols_mandante"].astype(int).astype(str)
+        + " x "
+        + jogos["gols_visitante"].astype(int).astype(str)
+    )
+    return (
+        jogos.sort_values(
+            ["diferenca", "_gols_partida", "data"], ascending=[False, False, True]
+        )
+        .head(n)[
+            [
+                "ano_campeonato",
+                "data",
+                "mandante",
+                "placar",
+                "visitante",
+                "diferenca",
+            ]
+        ]
+        .reset_index(drop=True)
+    )

dashgusbr/client.py

@@ -0,0 +1,183 @@
+"""Fachada pública da dashgusbr: a classe :class:`Brasileirao`.
+
+Orquestra as camadas puras (``data`` → ``analytics`` → ``viz``) com um
+DataFrame cacheado por instância. Usuários avançados podem importar as
+camadas diretamente (``from dashgusbr import analytics, viz``).
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional, Union
+
+import pandas as pd
+import plotly.graph_objects as go
+
+from . import analytics, data, viz
+
+
+class Brasileirao:
+    """Ponto de entrada da biblioteca.
+
+    Carrega a OBT sob demanda (no primeiro uso, não no construtor) e a mantém
+    em memória; todos os métodos de análise e plot operam sobre essa cópia.
+
+    Examples
+    --------
+    >>> from dashgusbr import Brasileirao
+    >>> br = Brasileirao()
+    >>> br.tabela(2023).head()
+    >>> br.plot_confronto("Flamengo", "Palmeiras").show()
+    """
+
+    def __init__(
+        self,
+        fonte: str = "auto",
+        github_url: Optional[str] = None,
+        sheets_url: Optional[str] = None,
+        cache: bool = True,
+    ) -> None:
+        self._fonte = fonte
+        self._github_url = github_url
+        self._sheets_url = sheets_url
+        self._cache = cache
+        self._df: Optional[pd.DataFrame] = None
+
+    # -- dados -------------------------------------------------------------
+
+    @property
+    def df(self) -> pd.DataFrame:
+        """A OBT completa (carga preguiçosa; não modifique in-place)."""
+        if self._df is None:
+            self._df = data.carregar_dados(
+                fonte=self._fonte,
+                github_url=self._github_url,
+                sheets_url=self._sheets_url,
+                cache=self._cache,
+            )
+        return self._df
+
+    def recarregar(self) -> "Brasileirao":
+        """Força novo download da fonte, ignorando os caches."""
+        self._df = data.carregar_dados(
+            fonte=self._fonte,
+            github_url=self._github_url,
+            sheets_url=self._sheets_url,
+            cache=self._cache,
+            forcar_download=True,
+        )
+        return self
+
+    def partidas(
+        self, ano: Optional[int] = None, time: Optional[str] = None
+    ) -> pd.DataFrame:
+        """Partidas da base, opcionalmente filtradas por temporada e/ou time."""
+        partidas = self.df
+        if ano is not None:
+            partidas = partidas[partidas["ano_campeonato"] == ano]
+        if time is not None:
+            partidas = partidas[
+                (partidas["mandante"] == time) | (partidas["visitante"] == time)
+            ]
+        return partidas.reset_index(drop=True).copy()
+
+    def anos(self) -> "list[int]":
+        """Temporadas disponíveis na base, em ordem crescente."""
+        return sorted(int(a) for a in self.df["ano_campeonato"].dropna().unique())
+
+    def times(self, ano: Optional[int] = None) -> "list[str]":
+        """Times presentes na base (ou apenas em uma temporada), em ordem alfabética."""
+        partidas = self.partidas(ano=ano)
+        return sorted(
+            pd.unique(pd.concat([partidas["mandante"], partidas["visitante"]]).dropna())
+        )
+
+    # -- classificação -----------------------------------------------------
+
+    def tabela(self, ano: int) -> pd.DataFrame:
+        """Classificação da fase de pontos corridos da temporada."""
+        return analytics.classificacao(self.df, ano)
+
+    def plot_tabela(self, ano: int) -> go.Figure:
+        """Gráfico de barras da classificação da temporada."""
+        return viz.classificacao(
+            self.tabela(ano), titulo=f"Brasileirão {ano} — Classificação"
+        )
+
+    # -- evolução e histórico ----------------------------------------------
+
+    def evolucao(self, time: str, ano: int) -> pd.DataFrame:
+        """Pontos acumulados do time, jogo a jogo, na temporada."""
+        return analytics.evolucao_pontos(self.df, time, ano)
+
+    def plot_evolucao(
+        self, times: Union[str, Iterable[str]], ano: int
+    ) -> go.Figure:
+        """Linha(s) de pontos acumulados de um ou mais times na temporada."""
+        if isinstance(times, str):
+            times = [times]
+        evolucoes = pd.concat(
+            [analytics.evolucao_pontos(self.df, t, ano) for t in times],
+            ignore_index=True,
+        )
+        return viz.evolucao(
+            evolucoes, titulo=f"Brasileirão {ano} — Evolução de pontos"
+        )
+
+    def historico(self, time: str) -> pd.DataFrame:
+        """Desempenho do time temporada a temporada (posição, pontos, aproveitamento)."""
+        return analytics.historico_time(self.df, time)
+
+    def plot_historico(
+        self, time: str, metrica: str = "aproveitamento"
+    ) -> go.Figure:
+        """Linha do desempenho histórico do time (aproveitamento por padrão)."""
+        return viz.historico(self.historico(time), metrica=metrica)
+
+    # -- confronto direto ----------------------------------------------------
+
+    def confronto(self, time_a: str, time_b: str) -> dict:
+        """Resumo do confronto direto (inclui o DataFrame ``partidas``)."""
+        return analytics.confronto(self.df, time_a, time_b)
+
+    def plot_confronto(self, time_a: str, time_b: str) -> go.Figure:
+        """Barras de vitórias/empates do confronto direto."""
+        return viz.confronto(self.confronto(time_a, time_b))
+
+    # -- estatísticas do campeonato ------------------------------------------
+
+    def estatisticas(self) -> pd.DataFrame:
+        """Indicadores por temporada: jogos, gols, média de gols, fator casa."""
+        return analytics.estatisticas_temporada(self.df)
+
+    def plot_gols_por_temporada(self) -> go.Figure:
+        """Linha da média de gols por jogo em cada temporada."""
+        return viz.gols_por_temporada(self.estatisticas())
+
+    def plot_mandante_visitante(self) -> go.Figure:
+        """Linhas do fator casa (% vitórias mandante/empates/visitante)."""
+        return viz.mandante_visitante(self.estatisticas())
+
+    def placares(self, ano: Optional[int] = None, max_gols: int = 6) -> pd.DataFrame:
+        """Matriz de frequência de placares (mandante × visitante)."""
+        return analytics.distribuicao_placares(self.df, ano=ano, max_gols=max_gols)
+
+    def plot_placares(
+        self, ano: Optional[int] = None, max_gols: int = 6
+    ) -> go.Figure:
+        """Heatmap da distribuição de placares."""
+        titulo = (
+            f"Brasileirão {ano} — Distribuição de placares"
+            if ano is not None
+            else "Distribuição de placares (1971–hoje)"
+        )
+        return viz.distribuicao_placares(
+            self.placares(ano=ano, max_gols=max_gols), titulo=titulo
+        )
+
+    def goleadas(self, n: int = 10) -> pd.DataFrame:
+        """As ``n`` maiores goleadas da história do campeonato."""
+        return analytics.maiores_goleadas(self.df, n=n)
+
+    def __repr__(self) -> str:
+        estado = "não carregado" if self._df is None else f"{len(self._df)} partidas"
+        return f"Brasileirao(fonte={self._fonte!r}, dados: {estado})"