Pré-processamento e tratamento de dados

Este módulo contém todas as funcionalidades relacionadas ao carregamento, pré-processamento, imputação e gerenciamento de dados para análise de séries temporais.

Leitura de dados 

Módulo para carregamento de dados de séries temporais.

Este módulo fornece funcionalidades para carregar e processar dados de séries temporais.

llm4time.core.data.loader.load_data(path: str) → DataFrame | None[código-fonte]

Carrega dados de séries temporais a partir de um arquivo.

Esta função identifica a extensão do arquivo e utiliza a função de leitura apropriada do pandas. Formatos suportados: CSV, XLSX, JSON, Parquet.

Parâmetros:: path (str) – Caminho para o arquivo a ser carregado.
Retorna:: DataFrame contendo os dados carregados ou None em caso de erro.
Tipo de retorno:: pd.DataFrame | None

Exemplos

>>> df = load_data("etth2.csv")

Pré-processamento 

Módulo para pré-processamento de dados de séries temporais.

Este módulo fornece funcionalidades essenciais para preparação e estruturação de dados de séries temporais, incluindo seleção e padronização de colunas, normalização de frequência temporal, e divisão de dados para treino e validação.

llm4time.core.data.preprocessor.standardize(df: DataFrame, date_col: str, value_col: str, duplicates: str = None) → DataFrame[código-fonte]

Padroniza um DataFrame para o formato de série temporal.

Realiza os seguintes passos:

Seleciona apenas as colunas date_col e value_col.
Renomeia date_col para “date” e value_col para “value”.
Converte a coluna “date” para datetime.
Ordena o DataFrame pela coluna “date” em ordem crescente.
Remove ou agrega duplicatas conforme o parâmetro duplicates.
Reseta os índices do DataFrame resultante.

Parâmetros:

df (pd.DataFrame) – DataFrame original contendo as colunas de interesse.
date_col (str) – Nome da coluna que contém as datas.
value_col (str) – Nome da coluna que contém os valores.
duplicates (str | None) – Como tratar dados duplicados: “first” → mantém a primeira ocorrência. “last” → mantém a última ocorrência. “sum” → soma os valores duplicados. None → não remove duplicatas.

Retorna:

DataFrame padronizado com colunas date e value, ordenado por date.

Tipo de retorno:

pd.DataFrame

Exemplos

>>> df = pd.DataFrame({
...     "col1": ["2025-01-03", "2025-01-01", "2025-01-02"],
...     "col2": [30, 10, 20],
...     "col3": ["a", "b", "c"]
... })
>>> padronize(df, date_col="col1", value_col="col2")
        date  value
0 2025-01-01     10
1 2025-01-02     20
2 2025-01-03     30

llm4time.core.data.preprocessor.normalize(ts: DataFrame, freq: str, start: str = None, end: str = None) → DataFrame[código-fonte]

Normaliza a série temporal garantindo que todas as datas dentro de um intervalo estejam presentes.

Cria um intervalo contínuo de datas, baseado nos limites fornecidos ou, se não especificados, na menor e maior data da coluna ‘date’. Datas ausentes são preenchidas com NaN.

Parâmetros:

ts (pd.DataFrame) – DataFrame contendo obrigatoriamente a coluna ‘date’.
freq (str) – Frequência da série temporal (ex.: ‘D’ = diário, ‘M’ = mensal, ‘H’ = horário).
start (str, optional) – Data inicial do intervalo (ex.: “2020-01” ou “2020-01-01”). Se None, usa data mínima em df[“date”]. Padrão: None.
end (str, optional) – Data final do intervalo (ex.: “2024-12” ou “2024-12-31”). Se None, usa data máxima em df[“date”]. Padrão: None.

Retorna:

DataFrame expandido para conter todas as datas no intervalo definido, com valores ausentes preenchidos como NaN.

Tipo de retorno:

pd.DataFrame

Exemplos

>>> ts = pd.DataFrame({"date": pd.to_datetime(["2021-01-01", "2021-01-03"]), "value": [10, 30]})
>>> normalize(ts, freq="D", start="2021-01-01", end="2021-01-05")
        date  value
0 2021-01-01   10.0
1 2021-01-02    NaN
2 2021-01-03   30.0
3 2021-01-04    NaN
4 2021-01-05    NaN

llm4time.core.data.preprocessor.split(ts: DataFrame, start_date: str, end_date: str, periods: int) → tuple[list[tuple[str, float]], list[float]][código-fonte]

Divide uma série temporal em conjunto de treino e validação com base em datas de corte.

O conjunto de treino contém as observações no intervalo entre start_date e end_date, enquanto o conjunto de validação contém as observações após end_date, limitado a periods valores.

Parâmetros:

ts (pd.DataFrame) – DataFrame com colunas obrigatórias ‘date’ e ‘value’.
start_date (str) – Data inicial do período de treino (formato “YYYY-MM-DD”).
end_date (str) – Data final do período de treino (formato “YYYY-MM-DD”).
periods (int) – Quantidade de valores a considerar no conjunto de validação.

Retorna:

Tupla contendo:

train: Lista de tuplas (date, value) representando o conjunto de treino
y_val: Lista de valores (float) do conjunto de validação, limitado a periods

Tipo de retorno:

tuple[list[tuple[str, float]], list[float]]

Exemplos

>>> ts = pd.DataFrame({
...     "date": ["2025-01-01", "2025-01-02", "2025-01-03", "2025-01-04"],
...     "value": [10.123, 20.456, 30.789, 40.321]
... })
>>> split(ts, start_date="2025-01-01", end_date="2025-01-02", periods=2)
([('2025-01-01', 10.123), ('2025-01-02', 20.456)], [30.789, 40.321])

Métodos de imputação 

Módulo para imputação de valores ausentes em séries temporais.

Este módulo fornece diversas estratégias para tratamento de valores NaN em dados de séries temporais, incluindo métodos estatísticos, de preenchimento e interpolação.

llm4time.core.data.imputation.mean(ts: Series | DataFrame, decimals: int = 4) → Series | DataFrame[código-fonte]

Imputa valores ausentes usando a média da coluna ‘value’.

Substitui todos os valores NaN na coluna ‘value’ pela média dos valores não nulos, arredondada para o número de casas decimais definido.

Parâmetros:

ts (Union[pd.Series, pd.DataFrame]) – Dados contendo uma coluna ‘value’ com possíveis valores ausentes.
decimals (int, opcional) – Número de casas decimais para arredondamento. Padrão: 4.

Retorna:

Dados com valores ausentes imputados pela média.

Tipo de retorno:

Union[pd.Series, pd.DataFrame]

Exemplos

>>> ts = pd.DataFrame({'value': [1.0, np.nan, 3.0, np.nan, 5.0]})
>>> mean(ts, decimals=2)
[1.0, 3.0, 3.0, 3.0, 5.0]

llm4time.core.data.imputation.median(ts: Series | DataFrame, decimals: int = 4) → Series | DataFrame[código-fonte]

Imputa valores ausentes usando a mediana da coluna ‘value’.

Substitui todos os valores NaN na coluna ‘value’ pela mediana dos valores não nulos, arredondada para o número de casas decimais definido.

Parâmetros:

ts (Union[pd.Series, pd.DataFrame]) – Dados contendo uma coluna ‘value’ com possíveis valores ausentes.
decimals (int, opcional) – Número de casas decimais para arredondamento. Padrão: 4.

Retorna:

Dados com valores ausentes imputados pela mediana.

Tipo de retorno:

Union[pd.Series, pd.DataFrame]

Exemplos

>>> ts = pd.DataFrame({'value': [1.0, np.nan, 100.0, np.nan, 5.0]})
>>> median(ts, decimals=2)
[1.0, 5.0, 100.0, 5.0, 5.0]

llm4time.core.data.imputation.ffill(ts: Series | DataFrame) → Series | DataFrame[código-fonte]

Imputa valores ausentes usando forward fill seguido de backward fill.

Preenche valores NaN propagando o último valor válido para frente, e depois preenche valores restantes propagando para trás. Preserva a continuidade temporal dos dados.

Parâmetros:: ts (Union[pd.Series, pd.DataFrame]) – Dados contendo uma coluna ‘value’ com possíveis valores ausentes.
Retorna:: Dados com valores ausentes imputados por propagação temporal.
Tipo de retorno:: Union[pd.Series, pd.DataFrame]

Exemplos

>>> ts = pd.DataFrame({'value': [np.nan, 2.0, np.nan, 4.0, np.nan]})
>>> ffill(ts)
[2.0, 2.0, 2.0, 4.0, 4.0]

llm4time.core.data.imputation.bfill(ts: Series | DataFrame) → Series | DataFrame[código-fonte]

Imputa valores ausentes usando backward fill seguido de forward fill.

Preenche valores NaN propagando o próximo valor válido para trás, e depois preenche valores restantes propagando para frente.

Parâmetros:: ts (Union[pd.Series, pd.DataFrame]) – Dados contendo uma coluna ‘value’ com possíveis valores ausentes.
Retorna:: Dados com valores ausentes imputados por propagação temporal reversa.
Tipo de retorno:: Union[pd.Series, pd.DataFrame]

Exemplos

>>> ts = pd.DataFrame({'value': [np.nan, 2.0, np.nan, 4.0, np.nan]})
>>> bfill(ts)
[2.0, 2.0, 4.0, 4.0, 4.0]

llm4time.core.data.imputation.sma(ts: Series | DataFrame, window: int, min_periods: int = 1) → Series | DataFrame[código-fonte]

Imputa valores ausentes usando média móvel simples.

Calcula a média móvel dos valores não nulos e usa para imputar valores ausentes, seguido de forward/backward fill para garantir cobertura completa.

Parâmetros:

ts (Union[pd.Series, pd.DataFrame]) – Dados contendo uma coluna ‘value’ com possíveis valores ausentes.
window (int) – Tamanho da janela para cálculo da média móvel.
min_periods (int, optional) – Número mínimo de observações na janela. Padrão: 1.

Retorna:

Dados com valores ausentes imputados por média móvel.

Tipo de retorno:

Union[pd.Series, pd.DataFrame]

Exemplos

>>> ts = pd.DataFrame({'value': [1.0, np.nan, 3.0, np.nan, 5.0]})
>>> sma(ts, window=3)

llm4time.core.data.imputation.ema(ts: Series | DataFrame, span: int, adjust: bool = False) → Series | DataFrame[código-fonte]

Imputa valores ausentes usando média móvel exponencial.

Aplica média móvel exponencial que dá maior peso aos valores recentes para imputar valores ausentes, seguido de forward/backward fill.

Parâmetros:

ts (Union[pd.Series, pd.DataFrame]) – Dados contendo uma coluna ‘value’ com possíveis valores ausentes.
span (int) – Span para o cálculo da média móvel exponencial.
adjust (bool, optional) – Se True, divide por fator de decaimento em expansão. Padrão: False.

Retorna:

Dados com valores ausentes imputados por média móvel exponencial.

Tipo de retorno:

Union[pd.Series, pd.DataFrame]

Exemplos

>>> ts = pd.DataFrame({'value': [1.0, np.nan, 3.0, np.nan, 5.0]})
>>> ema(ts, span=3)

llm4time.core.data.imputation.linear_interpolation(ts: Series | DataFrame) → Series | DataFrame[código-fonte]

Imputa valores ausentes usando interpolação linear.

Usa interpolação linear entre pontos conhecidos para estimar valores ausentes, seguido de forward/backward fill para extremos.

Parâmetros:: ts (Union[pd.Series, pd.DataFrame]) – Dados contendo uma coluna ‘value’ com possíveis valores ausentes.
Retorna:: Dados com valores ausentes imputados por interpolação linear.
Tipo de retorno:: Union[pd.Series, pd.DataFrame]

Exemplos

>>> ts = pd.DataFrame({'value': [1.0, np.nan, np.nan, 4.0]})
>>> linear_interpolation(ts)
[1.0, 2.0, 3.0, 4.0]

llm4time.core.data.imputation.spline_interpolation(ts: Series | DataFrame, order: int = 2) → Series | DataFrame[código-fonte]

Imputa valores ausentes usando interpolação spline.

Aplica interpolação spline de ordem especificada para suavizar a estimação de valores ausentes. Em caso de falha, recorre à interpolação linear.

Parâmetros:

ts (Union[pd.Series, pd.DataFrame]) – Dados contendo uma coluna ‘value’ com possíveis valores ausentes.
order (int, optional) – Ordem do polinômio spline. Padrão: 2.

Retorna:

Dados com valores ausentes imputados por interpolação spline ou linear (fallback).

Tipo de retorno:

Union[pd.Series, pd.DataFrame]

Exemplos

>>> ts = pd.DataFrame({'value': [1.0, np.nan, np.nan, 4.0, np.nan, 6.0]})
>>> spline_interpolation(ts, order=3)

llm4time.core.data.imputation.zero(ts: Series | DataFrame) → Series | DataFrame[código-fonte]

Imputa valores ausentes com zero.

Substitui todos os valores NaN na coluna ‘value’ por 0. Útil quando valores ausentes representam ausência de eventos ou medições.

Parâmetros:: ts (Union[pd.Series, pd.DataFrame]) – Dados contendo uma coluna ‘value’ com possíveis valores ausentes.
Retorna:: Dados com valores ausentes imputados com zero.
Tipo de retorno:: Union[pd.Series, pd.DataFrame]

Exemplos

>>> ts = pd.DataFrame({'value': [1.0, np.nan, 3.0, np.nan, 5.0]})
>>> zero(ts)
[1.0, 0.0, 3.0, 0.0, 5.0]

Gerenciamento de dados 

Módulo para gerenciamento de dados de séries temporais.

Este módulo fornece funcionalidades para salvar DataFrames processados em diferentes formatos, facilitando a persistência de dados após o processamento e análise de séries temporais.

llm4time.core.data.manager.save(df: DataFrame, path: str) → None[código-fonte]

Salva um DataFrame em arquivo, identificando automaticamente o formato.

Suporta os seguintes formatos: CSV, XLSX, JSON, Parquet.

Parâmetros:

df (pd.DataFrame) – DataFrame contendo os dados a serem salvos.
path (str) – Caminho completo incluindo nome e extensão do arquivo.

Exemplos

>>> df = pd.DataFrame({'date': ['2023-01-01', '2023-01-02'],
...                    'value': [10.5, 12.3]})
>>> save(df, "etth2.csv")
# Arquivo salvo em etth2.csv

Prompts e formatações

Este módulo contém todas as funcionalidades relacionadas à criação, formatação e gerenciamento de prompts para modelos de linguagem aplicados a análise de séries temporais.

Tipos de prompts 

class llm4time.core.prompts.PromptType(value)[código-fonte]

ZERO_SHOT = 'ZERO_SHOT'

FEW_SHOT = 'FEW_SHOT'

COT = 'COT'

COT_FEW = 'COT_FEW'

CUSTOM = 'CUSTOM'

Estratégias de amostragem 

class llm4time.core.data.Sampling(value)[código-fonte]

FRONTEND = 'FRONTEND'

BACKEND = 'BACKEND'

RANDOM = 'RANDOM'

UNIFORM = 'UNIFORM'

Formatos de série temporal 

class llm4time.core.formatting.parsers.TSFormat(value)[código-fonte]

ARRAY = 'ARRAY'

TSV = 'TSV'

PLAIN = 'PLAIN'

JSON = 'JSON'

MARKDOWN = 'MARKDOWN'

CONTEXT = 'CONTEXT'

SYMBOL = 'SYMBOL'

CSV = 'CSV'

CUSTOM = 'CUSTOM'

Tipos de série temporal 

class llm4time.core.formatting.encoders.decoders.TSType(value)[código-fonte]

NUMERIC = 'NUMERIC'

TEXTUAL = 'TEXTUAL'

Geração de prompts 

Módulo para geração e carregamento de prompts de previsão em séries temporais.

llm4time.core.prompt.load_prompt(path: str, **kwargs) → str[código-fonte]

Carrega um template de prompt de um arquivo e realiza substituições de variáveis.

Lê o conteúdo do arquivo especificado por path e formata a string com os argumentos fornecidos em kwargs. É útil para reutilizar prompts de previsão de séries temporais com placeholders dinâmicos.

Parâmetros:

path (str) – Caminho para o arquivo de texto contendo o template do prompt.
**kwargs – Argumentos para substituição de placeholders no template.

Retorna:

Conteúdo do arquivo formatado com os argumentos fornecidos.

Tipo de retorno:

str

Levanta:

FileNotFoundError – Se o arquivo não for encontrado.
IOError – Se houver erro ao ler o arquivo.
KeyError – Se algum placeholder no template não tiver correspondência em kwargs.

Exemplos

>>> load_prompt("templates/zero_shot.txt", train_data="...", periods=7)

llm4time.core.prompt.generate(train: list[tuple], periods: int, prompt_type: PromptType, ts_format: TSFormat, ts_type: TSType, sampling: Sampling = None, num_examples: int = 0, template: str = None, **kwargs) → str[código-fonte]

Gera um prompt de previsão de séries temporais de acordo com o tipo especificado.

A função prepara os dados de treino no formato e tipo desejados, constrói exemplos de acordo com a estratégia de amostragem especificada e insere essas informações em diferentes templates.

Parâmetros:

train (list[tuple]) – Série temporal de treino no formato [(date, value), …].
periods (int) – Número de períodos a serem previstos.
prompt_type (PromptType) – Tipo de prompt a ser gerado: - ZERO_SHOT: Sem exemplos. - FEW_SHOT: Com exemplos de previsões passadas. - COT: Com raciocínio passo a passo (Chain of Thought). - COT_FEW: Combinação de exemplos e raciocínio passo a passo. - CUSTOM: Se desejar utilizar um prompt customizado.
ts_format (TSFormat) – Formato de serialização da série temporal (ex.: CSV, JSON, Markdown).
ts_type (TSType) – Tipo de codificação dos valores (ex.: NUMERIC, TEXTUAL).
sampling (Sampling, opcional) – Estratégia de amostragem dos dados de exemplo. Padrão: Sampling.FRONTEND.
num_examples (int, opcional) – Quantidade de exemplos a serem gerados. Padrão: 0.
template (str, opcional) – Prompt customizado se prompt_type for CUSTOM. Padrão: None.
**kwargs – Se desejar inserir chaves adicionais ao prompt ou substituir as chaves padrão.

Retorna:

Prompt formatado pronto para ser usado em um modelo de linguagem.

Tipo de retorno:

str

Levanta:

ValueError –

Se prompt_type for inválido. - Se prompt_type for CUSTOM e template for None. - Se num_examples for maior que 0 e não houver períodos suficientes para os exemplos solicitados.

Exemplos

>>> generate(
...     train=[("2025-01-01", 100), ("2025-01-02", 200)],
...     periods=7,
...     prompt_type=PromptType.ZERO_SHOT,
...     ts_format=TSFormat.CSV,
...     ts_type=TSType.NUMERIC
... )

Formatação de dados 

Módulo para formatação e parsing de séries temporais.

llm4time.core.formatter.format(data: list, ts_format: TSFormat, ts_type: TSType) → str[código-fonte]

Formata uma série temporal de acordo com o tipo e o formato especificados.

Parâmetros:

data (list) – Série temporal, como lista de valores ou tuplas (data, valor).
ts_format (TSFormat) – Tipo de formatação desejada (ex.: CSV, JSON, Markdown, etc.).
ts_type (TSType) – Tipo de codificação dos valores (ex.: numeric, textual).

Retorna:

Série temporal formatada como string de acordo com ts_format e ts_type.

Tipo de retorno:

str

Levanta:

ValueError – Se ts_format ou ts_type forem desconhecidos.

Exemplos

>>> format([("2025-01-01", 100), ("2025-01-02", 200)],
...        ts_format=TSFormat.CSV, ts_type=TSType.NUMERIC)
'Date,Value\n2025-01-01,100\n2025-01-02,200'

>>> format([("2025-01-01", 100), ("2025-01-02", 200)],
...        ts_format=TSFormat.CSV, ts_type=TSType.TEXTUAL)
'Date,Value\n2025-01-01,1 0 0\n2025-01-02,2 0 0'

llm4time.core.formatter.parse(data: str, ts_format: TSFormat, ts_type: TSType) → list[código-fonte]

Converte uma string representando uma série temporal em uma lista de valores ou tuplas (date, value), de acordo com o formato e o tipo especificados.

Caso ocorra falha durante o parsing, a função tenta uma alternativa de fallback, assumindo formato ARRAY e tipo NUMERIC.

Parâmetros:

ts (str) – String contendo a série temporal (ex.: CSV, JSON, Markdown, etc.).
ts_format (TSFormat) – Formato de entrada (ex.: ‘csv’, ‘json’, ‘markdown’).
ts_type (TSType) – Tipo de codificação esperado (‘numeric’ ou ‘textual’).

Retorna:

Série temporal como lista de valores ou tuplas (date, value).

Tipo de retorno:

list

Levanta:

ValueError – Se ts_format ou ts_type forem desconhecidos.

Exemplos

>>> parse("Date,Value\n2025-01-01,100\n2025-01-02,200",
...       ts_format=TSFormat.CSV, ts_type=TSType.NUMERIC)
[('2025-01-01', 100), ('2025-01-02', 200)]

>>> parse("Date,Value\n2025-01-01,1 0 0\n2025-01-02,2 0 0",
...       ts_format=TSFormat.CSV, ts_type=TSType.TEXTUAL)
[('2025-01-01', 100), ('2025-01-02', 200)]

Previsão com LLMs

Este módulo contém todas as funcionalidades relacionadas à utilização de modelos de linguagem de grande escala (LLMs) para previsão e análise de séries temporais, incluindo diferentes provedores de API e configurações de modelos.

Modelos 

class llm4time.core.models.Provider(value)[código-fonte]

LM_STUDIO = 'LM_STUDIO'

OPENAI = 'OPENAI'

AZURE = 'AZURE'

classmethod enum(name: str)[código-fonte]

Módulo para integração com modelos OpenAI em séries temporais.

class llm4time.core.models.openai.OpenAI(model: str, api_key: str, base_url: str)[código-fonte]

Classe para integração com modelos OpenAI para previsão de séries temporais.

model

Nome do modelo OpenAI.

Type:: str

api_key

Chave de API para autenticação.

Type:: str

base_url

URL base do endpoint OpenAI.

Type:: str

__init__(model: str, api_key: str, base_url: str) → None[código-fonte]

Inicializa a classe OpenAI com configurações de conexão.

Parâmetros:

model (str) – Nome do modelo OpenAI.
api_key (str) – Chave de API para autenticação.
base_url (str) – URL base do endpoint OpenAI.

predict(content: str, temperature: float = 0.7, **kwargs) → tuple[str, int, int, float][código-fonte]

Envia uma requisição de chat para um modelo OpenAI e retorna a resposta com métricas.

Parâmetros:

content (str) – Conteúdo da mensagem do usuário a ser enviada.
temperature (float, optional) – Grau de aleatoriedade da resposta. Padrão: 0.7.
**kwargs – Argumentos adicionais passados para client.chat.completions.create.

Retorna:

Tupla contendo:

response: Resposta do modelo.
prompt_tokens: Número de tokens usados no prompt.
response_tokens: Número de tokens usados na resposta.
response_time: Tempo total da requisição em segundos.

Tipo de retorno:

tuple[str, int, int, float]

Exemplos

>>> response, prompt_tokens, response_tokens, time_sec = model.predict(
...     content="Série temporal: [199.99, 190.10, 180.01, 178.45, 160.33]. Preveja próximos 3 valores.",
...     temperature=0.5
... )
>>> print(response)
'[149.25, 140.10, 128.50]'

Módulo para integração com modelos Azure OpenAI em séries temporais.

class llm4time.core.models.azure.AzureOpenAI(model: str, api_key: str, azure_endpoint: str, api_version: str)[código-fonte]

Classe para integração com modelos Azure OpenAI para previsão de séries temporais.

model

Nome do modelo Azure OpenAI.

Type:: str

api_key

Chave de API para autenticação.

Type:: str

azure_endpoint

URL do endpoint Azure OpenAI.

Type:: str

api_version

Versão da API Azure OpenAI.

Type:: str

__init__(model: str, api_key: str, azure_endpoint: str, api_version: str) → None[código-fonte]

Inicializa a classe AzureOpenAI com configurações de conexão.

Parâmetros:

model (str) – Nome do modelo Azure OpenAI.
api_key (str) – Chave de API para autenticação.
azure_endpoint (str) – URL do endpoint Azure OpenAI.
api_version (str) – Versão da API Azure OpenAI.

predict(content: str, temperature: float = 0.7, **kwargs) → tuple[str, int, int, float][código-fonte]

Envia uma requisição de chat para um modelo OpenAI Azure e retorna a resposta com métricas.

Parâmetros:

content (str) – Conteúdo da mensagem do usuário a ser enviada.
temperature (float, optional) – Grau de aleatoriedade da resposta. Padrão: 0.7.
**kwargs – Argumentos adicionais passados para client.chat.completions.create.

Retorna:

Tupla contendo:

response: Resposta do modelo.
prompt_tokens: Número de tokens usados no prompt.
response_tokens: Número de tokens usados na resposta.
response_time: Tempo total da requisição em segundos.

Tipo de retorno:

tuple[str, int, int, float]

Exemplos

>>> response, prompt_tokens, response_tokens, time_sec = model.predict(
...     content="Série temporal: [199.99, 190.10, 180.01, 178.45, 160.33]. Preveja próximos 3 valores.",
...     temperature=0.5
... )
>>> print(response)
'[149.25, 140.10, 128.50]'

Módulo para integração com modelos LM Studio em séries temporais.

class llm4time.core.models.lmstudio.LMStudio(model: str)[código-fonte]

Classe para integração com modelos LM Studio para previsão de séries temporais.

model

Nome ou caminho do modelo LM Studio.

Type:: str

__init__(model: str) → None[código-fonte]

Inicializa a classe LMStudio com o modelo especificado.

Parâmetros:: model (str) – Nome ou caminho do modelo LM Studio.

predict(content: str, temperature: float = 0.7, **kwargs) → tuple[str, int, int, float][código-fonte]

Envia uma requisição para o modelo LM Studio e retorna a resposta com métricas.

Parâmetros:

content (str) – Conteúdo da mensagem do usuário a ser enviada.
temperature (float, optional) – Grau de aleatoriedade da resposta. Padrão: 0.7.
**kwargs – Argumentos adicionais passados para client.respond.

Retorna:

Tupla contendo:

response: Resposta do modelo.
prompt_tokens: Número de tokens usados no prompt.
response_tokens: Número de tokens usados na resposta.
response_time: Tempo total da requisição em segundos.

Tipo de retorno:

tuple[str, int, int, float]

Exemplos

>>> response, prompt_tokens, response_tokens, time_sec = model.predict(
...     content="Série temporal: [199.99, 190.10, 180.01, 178.45, 160.33]. Preveja próximos 3 valores.",
...     temperature=0.5
... )
>>> print(response)
'[149.25, 140.10, 128.50]'

Métricas de avaliação

Este módulo contém todas as funcionalidades relacionadas à avaliação de performance de modelos de previsão, incluindo métricas de erro, análises estatísticas e indicadores específicos para séries temporais.

Métricas de erro 

Módulo para avaliação de modelos de séries temporais.

Este módulo fornece uma classe para calcular métricas de performance comumente utilizadas na avaliação de previsões de séries temporais.

class llm4time.core.evaluate.metrics.Metrics(y_val: list[float], y_pred: list[float])[código-fonte]

Classe para calcular métricas de avaliação de previsões de séries temporais.

Esta classe calcula diversas métricas de erro entre valores observados e preditos, removendo automaticamente valores NaN antes dos cálculos para garantir robustez.

Parâmetros:

y_val (list[float]) – Lista de valores observados (reais) da série temporal.
y_pred (list[float]) – Lista de valores preditos pelo modelo.

y_val

Array numpy com valores observados sem NaN.

Type:: np.array

y_pred

Array numpy com valores preditos sem NaN.

Type:: np.array

Exemplos

>>> metrics = Metrics([10, 20, 30], [12, 18, 32])
>>> print(metrics.mae)
2.0
>>> print(metrics.rmse)
2.31
>>> print(metrics.smape)
6.67
>>> print(Metrics.sem([2, -2, 2]))
1.1547

__init__(y_val: list[float], y_pred: list[float]) → None[código-fonte]

property smape: float

SMAPE — Erro Percentual Absoluto Médio Simétrico.

Retorna a métrica em percentual, útil para avaliar a acurácia de previsões em diferentes escalas.

Retorna:: Valor do SMAPE em percentual (duas casas decimais).
Tipo de retorno:: float

property mae: float

MAE — Erro Absoluto Médio.

Mede a média dos erros absolutos entre valores observados e preditos.

Retorna:: Valor do MAE (duas casas decimais).
Tipo de retorno:: float

property rmse: float

RMSE — Raiz do Erro Quadrático Médio.

Penaliza mais fortemente erros grandes, sendo útil quando grandes desvios são indesejáveis.

Retorna:: Valor do RMSE (duas casas decimais).
Tipo de retorno:: float

static sem(errors: list[float]) → float[código-fonte]

SEM — Erro Padrão da Média.

Mede a variabilidade da média dos erros, útil para estimar intervalos de confiança.

Parâmetros:: errors (list[float]) – Lista de erros individuais.
Retorna:: Valor do SEM (quatro casas decimais).
Tipo de retorno:: float

Estatísticas 

Módulo para análise estatística de séries temporais.

Este módulo fornece uma classe para calcular estatísticas descritivas e análises avançadas de séries temporais, incluindo decomposição de tendência e sazonalidade usando STL.

class llm4time.core.evaluate.statistics.Statistics(data: list[float])[código-fonte]

Classe para calcular estatísticas descritivas de séries temporais.

Esta classe fornece propriedades para calcular medidas estatísticas robustas de séries temporais, tratando automaticamente valores ausentes e fornecendo análises de tendência e sazonalidade.

Parâmetros:: data (list[float]) – Lista de valores numéricos da série temporal.

data

Array numpy com todos os dados originais.

Type:: np.array

valid_data

Array numpy apenas com dados válidos (sem NaN).

Type:: np.array

Exemplos

>>> data = [10.5, 12.0, np.nan, 15.2, 13.8, 11.1]
>>> stats = Statistics(data)
>>> stats.mean
12.52
>>> stats.missing_count
1

__init__(data: list[float]) → None[código-fonte]

Inicializa a classe Statistics com dados da série temporal.

Parâmetros:: data (list[float]) – Lista de valores numéricos.

property mean: float

Calcula a média dos valores válidos.

Retorna:: Média arredondada para 4 casas decimais.
Tipo de retorno:: float

property median: float

Calcula a mediana dos valores válidos.

Retorna:: Mediana arredondada para 4 casas decimais.
Tipo de retorno:: float

property first_quartile: float

Calcula o primeiro quartil (percentil 25) dos valores válidos.

Retorna:: Primeiro quartil arredondado para 4 casas decimais.
Tipo de retorno:: float

property third_quartile: float

Calcula o terceiro quartil (percentil 75) dos valores válidos.

Retorna:: Terceiro quartil arredondado para 4 casas decimais.
Tipo de retorno:: float

property std: float

Calcula o desvio padrão amostral dos valores válidos.

Usa ddof=1 para calcular o desvio padrão amostral (divisão por n-1).

Retorna:: Desvio padrão arredondado para 4 casas decimais.
Tipo de retorno:: float

property min: float

Encontra o valor mínimo dos valores válidos.

Retorna:: Valor mínimo arredondado para 4 casas decimais.
Tipo de retorno:: float

property max: float

Encontra o valor máximo dos valores válidos.

Retorna:: Valor máximo arredondado para 4 casas decimais.
Tipo de retorno:: float

property missing_count: int

Conta o número de valores ausentes (NaN) nos dados.

Retorna:: Quantidade de valores NaN.
Tipo de retorno:: int

property missing_percentage: float

Calcula a porcentagem de valores ausentes nos dados.

Retorna:: Percentual de valores NaN arredondado para 4 casas decimais.
Tipo de retorno:: float

static trend_seasonality(df: DataFrame, period: int = None, freq: str = None) → tuple[Series, Series, Series, float, float][código-fonte]

Decompõe uma série temporal em tendência, sazonalidade e resíduo usando STL.

Aplica decomposição STL (Seasonal and Trend decomposition using Loess) e calcula a força da tendência e da sazonalidade baseada na variância dos componentes.

Parâmetros:

df (pd.DataFrame) – DataFrame contendo colunas “date” e “value”.
period (int, optional) – Período sazonal para STL. Se None, STL infere automaticamente. Defaults to None.
freq (str, optional) – Frequência da série temporal (ex.: “D”, “M”, “Q”). Se fornecida, será aplicada via asfreq. Defaults to None.

Retorna:

Tupla contendo:

trend: Componente de tendência estimada
seasonal: Componente sazonal estimado
resid: Resíduo após remoção de tendência e sazonalidade
trend_strength: Força da tendência (0 = fraca, 1 = forte)
seasonality_strength: Força da sazonalidade (0 = fraca, 1 = forte)

Tipo de retorno:

tuple[pd.Series, pd.Series, pd.Series, float, float]

Exemplos

>>> data = pd.DataFrame({
...     "date": pd.date_range("2020-01-01", periods=24, freq="M"),
...     "value": [i + (i % 12) * 2 for i in range(24)]
... })
>>> trend, seasonal, resid, t_str, s_str = Statistics.trend_seasonality(data, period=12)
>>> # Retorna componentes decompostos e forças calculadas

Avaliação de performance de previsões de séries temporais 

llm4time.core.metrics.evaluate(y_val: list[float], y_pred: list[float]) → tuple[Metrics, Statistics, Statistics][código-fonte]

Avalia previsões de séries temporais e calcula estatísticas descritivas.

Esta função cria instâncias das classes Metrics e Statistics para fornecer uma análise completa das previsões de séries temporais, incluindo métricas de erro e estatísticas descritivas tanto dos valores observados quanto dos valores preditos.

Parâmetros:

y_val (list[float]) – Lista de valores observados (reais).
y_pred (list[float]) – Lista de valores preditos pelo modelo.

Retorna:

metrics (Metrics): Instância contendo métricas de erro.
stats_val (Statistics): Instância com estatísticas da série observada.
stats_pred (Statistics): Instância com estatísticas da série predita.

Tipo de retorno:

tuple[Metrics, Statistics, Statistics]

Exemplos

>>> y_val = [10, 20, 30, 40]
>>> y_pred = [12, 18, 29, 41]
>>> metrics, val_stats, pred_stats = evaluate(y_val, y_pred)
>>> print(metrics.mae, metrics.rmse, metrics.smape)
1.5 1.58 5.0
>>> print(val_stats.mean, pred_stats.mean)
25.0 25.0
>>> print(val_stats.missing_count, pred_stats.missing_count)
0 0

Visualização

Este módulo contém todas as funcionalidades relacionadas à criação de visualizações e gráficos para análise de séries temporais.

Gráficos interativos 

Módulo para criação de gráficos.

Este módulo fornece funções especializadas para visualização de dados de séries temporais, incluindo plotagem de dados históricos, previsões, estatísticas comparativas e decomposição de séries temporais.

llm4time.visualization.plots.plot_time_series(title: str, ts: DataFrame, **kwargs)[código-fonte]

Cria um gráfico de linha para uma série temporal com datas.

Parâmetros:

title (str) – Título do gráfico.
ts (pd.DataFrame) – DataFrame contendo colunas ‘date’ e ‘value’ com os dados da série temporal.
**kwargs – Argumentos adicionais passados para fig.update_layout().

Retorna:

Objeto Figure do Plotly com o gráfico da série temporal.

Tipo de retorno:

go.Figure

Exemplos

>>> ts = pd.DataFrame({
...     'date': pd.date_range('2020-01-01', periods=100),
...     'value': np.random.randn(100).cumsum()
... })
>>> fig = plot_time_series("Vendas Mensais", ts)
>>> fig.show()

llm4time.visualization.plots.plot_period_series(title: str, values: list, **kwargs)[código-fonte]

Cria um gráfico de linha para uma série temporal indexada por períodos.

Parâmetros:

title (str) – Título do gráfico.
values (list) – Lista de valores numéricos da série temporal.
**kwargs – Argumentos adicionais passados para fig.update_layout().

Retorna:

Objeto Figure do Plotly com o gráfico da série temporal.

Tipo de retorno:

go.Figure

Exemplos

>>> values = [10, 15, 12, 18, 20, 16, 14]
>>> fig = plot_period_series("Série por Períodos", values)
>>> fig.show()

llm4time.visualization.plots.plot_forecast(title: str, y_val: list, y_pred: list, **kwargs)[código-fonte]

Cria um gráfico comparativo entre valores reais e previstos.

Plota duas linhas sobrepostas para comparar visualmente os valores reais com as previsões do modelo.

Parâmetros:

title (str) – Título do gráfico.
y_val (list) – Lista com valores reais da série temporal.
y_pred (list) – Lista com valores previstos pelo modelo.
**kwargs – Argumentos adicionais passados para fig.update_layout().

Retorna:

Objeto Figure do Plotly com gráfico de comparação.

Tipo de retorno:

go.Figure

Exemplos

>>> y_real = [10, 12, 15, 18, 20]
>>> y_previsto = [9, 13, 14, 19, 21]
>>> fig = plot_forecast("Previsão vs Reality", y_real, y_previsto)
>>> fig.show()

llm4time.visualization.plots.plot_forecast_statistics(title: str, y_val: list, y_pred: list, **kwargs)[código-fonte]

Cria um gráfico de barras comparando estatísticas descritivas.

Compara métricas estatísticas (média, mediana, desvio padrão, máximo, mínimo) entre valores reais e previstos usando gráfico de barras agrupadas.

Parâmetros:

title (str) – Título do gráfico.
y_val (list) – Lista com valores reais da série temporal.
y_pred (list) – Lista com valores previstos pelo modelo.
**kwargs – Argumentos adicionais passados para fig.update_layout().

Retorna:

Objeto Figure do Plotly com gráfico de barras comparativo.

Tipo de retorno:

go.Figure

Exemplos

>>> y_real = [10, 12, 15, 18, 20, 8, 25]
>>> y_previsto = [9, 13, 14, 19, 21, 7, 24]
>>> fig = plot_forecast_statistics("Estatísticas Comparativas", y_real, y_previsto)
>>> fig.show()

llm4time.visualization.plots.plot_decomposition(title: str, trend: Series, seasonal: Series, resid: Series, **kwargs)[código-fonte]

Cria um gráfico de decomposição de série temporal em subplots.

Exibe a decomposição da série temporal em três componentes: tendência, sazonalidade e resíduos, cada um em um subplot separado.

Parâmetros:

title (str) – Título principal do gráfico.
trend (pd.Series) – Série com o componente de tendência.
seasonal (pd.Series) – Série com o componente sazonal.
resid (pd.Series) – Série com os resíduos.
**kwargs – Argumentos adicionais passados para fig.update_layout().

Retorna:

Objeto Figure do Plotly com subplots da decomposição.

Tipo de retorno:

go.Figure

Exemplos

>>> # Assumindo decomposição já realizada
>>> fig = plot_decomposition(
...     "Decomposição da Série",
...     trend_series,
...     seasonal_series,
...     residual_series
... )
>>> fig.show()