# TimesFM

## Visão geral

TimesFM (Time Series Foundation Model) é um modelo de fundação pré-treinado para séries temporais proposto em [A decoder-only foundation model for time-series forecasting](https://huggingface.co/papers/2310.10688) por Abhimanyu Das, Weihao Kong, Rajat Sen e Yichen Zhou. Trata-se de um modelo somente de decodificador que utiliza patches não sobrepostos de dados de séries temporais como entrada e gera previsões de comprimento de patch de saída de forma autoregressiva.

O resumo do artigo é o seguinte:

*Inspirados pelos avanços recentes em modelos de linguagem de grande escala para Processamento de Linguagem Natural (NLP), projetamos um modelo de fundação para séries temporais voltado à previsão, cujo desempenho zero-shot, pronto para uso, em uma variedade de conjuntos de dados públicos se aproxima da precisão dos modelos de previsão supervisionados de estado da arte para cada conjunto de dados individual. Nosso modelo é baseado no pré-treinamento de um modelo de atenção no estilo patched-decoder em um grande corpus de séries temporais e pode funcionar bem em diferentes comprimentos de histórico de previsão, comprimentos de previsão e granularidades temporais.*

Este modelo foi contribuído por [kashif](https://huggingface.co/kashif). O código original pode ser encontrado [aqui](https://github.com/google-research/timesfm).

Para usar o modelo:

```python
import numpy as np
import torch

from transformers import TimesFmModelForPrediction

model = TimesFmModelForPrediction.from_pretrained(
    "google/timesfm-2.0-500m-pytorch",
    attn_implementation="sdpa",
    device_map="auto"
)

 # Create dummy inputs
forecast_input = [
    np.sin(np.linspace(0, 20, 100)),
    np.sin(np.linspace(0, 20, 200)),
    np.sin(np.linspace(0, 20, 400)),
]
frequency_input = [0, 1, 2]

# Convert inputs to sequence of tensors
forecast_input_tensor = [
    torch.tensor(ts).to(model.device)
    for ts in forecast_input
]
frequency_input_tensor = torch.tensor(frequency_input, dtype=torch.long).to(model.device)

# Get predictions from the pre-trained model
with torch.no_grad():
    outputs = model(past_values=forecast_input_tensor, freq=frequency_input_tensor, return_dict=True)
    point_forecast_conv = outputs.mean_predictions.float().cpu().numpy()
    quantile_forecast_conv = outputs.full_predictions.float().cpu().numpy()
```

## TimesFmConfig[[transformers.TimesFmConfig]]

#### transformers.TimesFmConfig[[transformers.TimesFmConfig]]

```python
transformers.TimesFmConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, patch_length: int = 32, context_length: int = 512, horizon_length: int = 128, freq_size: int = 3, num_hidden_layers: int = 50, hidden_size: int = 1280, intermediate_size: int = 1280, head_dim: int = 80, num_attention_heads: int = 16, tolerance: float = 1e-06, rms_norm_eps: float = 1e-06, quantiles: list[float] | tuple[float, ...] = (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9), pad_val: float = 1123581321.0, attention_dropout: float | int = 0.0, use_positional_embedding: bool = False, initializer_range: float = 0.02, min_timescale: int = 1, max_timescale: int = 10000)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timesfm/configuration_timesfm.py#L24)

**Parâmetros:**

patch_length (`int`, *opcional*, padrão 32) : O comprimento de um patch na sequência de entrada.

context_length (`int`, *opcional*, padrão 512) : O comprimento do contexto de entrada.

horizon_length (`int`, *opcional*, padrão 128) : O comprimento do horizonte de previsão.

freq_size (`int`, *opcional*, padrão 3) : O número de incorporações de frequência.

num_hidden_layers (`int`, *opcional*, padrão `50`) : Número de camadas ocultas no decodificador do Transformer.

hidden_size (`int`, *opcional*, padrão `1280`) : Dimensão das representações ocultas.

intermediate_size (`int`, *opcional*, padrão `1280`) : Dimensão das representações do MLP.

head_dim (`int`, *opcional*, padrão `80`) : A dimensão da cabeça de atenção. Se for None, o padrão será hidden_size // num_attention_heads

num_attention_heads (`int`, *opcional*, padrão `16`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.

tolerance (`float`, *opcional*, padrão 1e-06) : A tolerância para a perda de quantil.

rms_norm_eps (`float`, *opcional*, padrão `1e-06`) : O epsilon usado pelas camadas de normalização rms.

quantiles (`list[float]`, *opcional*, padrão `[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]`) : Os quantis a prever.

pad_val (`float`, *opcional*, padrão 1123581321.0) : O valor usado para preencher as previsões.

attention_dropout (`float`, *opcional*, padrão 0.0) : A probabilidade de dropout para as pontuações de atenção.

use_positional_embedding (`bool`, *opcional*, padrão `False`) : Se deve adicionar embeddings posicionais.

initializer_range (`float`, *opcional*, padrão `0.02`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

min_timescale (`int`, *opcional*, padrão 1) : O início do índice posicional geométrico. Determina a periodicidade do sinal adicionado.

max_timescale (`int`, *opcional*, padrão 10000) : O final do índice posicional geométrico. Determina a frequência do sinal adicionado.

Esta é a classe de configuração para armazenar a configuração de um TimesFmModel. Ela é usada para instanciar um modelo Timesfm de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [google/timesfm-2.0-500m-pytorch](https://huggingface.co/google/timesfm-2.0-500m-pytorch)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

## TimesFmModel[[transformers.TimesFmModel]]

#### transformers.TimesFmModel[[transformers.TimesFmModel]]

```python
transformers.TimesFmModel(config: TimesFmConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timesfm/modeling_timesfm.py#L332)

**Parâmetros:**

config ([TimesFmConfig](/docs/transformers/main/pt/model_doc/timesfm#transformers.TimesFmConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo Timesfm puro, que gera os hidden-states brutos sem nenhum head específico no topo.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

#### forward[[transformers.TimesFmModel.forward]]

```python
forward(past_values: Tensor, past_values_padding: LongTensor, freq: Tensor, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timesfm/modeling_timesfm.py#L365)

**Parâmetros:**

past_values (`torch.Tensor` de forma `(batch_size, sequence_length)`) : Valores passados da série temporal que servem como entrada para o modelo.

past_values_padding (`torch.LongTensor` de forma `(batch_size, sequence_length)`) : O indicador de preenchimento da série temporal.

freq (`torch.LongTensor` de forma `(batch_size,)`) : Índices de frequência para os dados da série temporal.

**Retorna:** `TimesFmOutput` ou `tuple(torch.Tensor)`

Um `TimesFmOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([TimesFmConfig](/docs/transformers/main/pt/model_doc/timesfm#transformers.TimesFmConfig)) e das entradas.

O método forward do [TimesFmModel](/docs/transformers/main/pt/model_doc/timesfm#transformers.TimesFmModel) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do modelo.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **loc** (`torch.Tensor` de forma `(batch_size, )`) -- A média das entradas da série temporal.
- **scale** (`torch.Tensor` de forma `(batch_size,)`) -- A escala das entradas da série temporal.

## TimesFmModelForPrediction[[transformers.TimesFmModelForPrediction]]

#### transformers.TimesFmModelForPrediction[[transformers.TimesFmModelForPrediction]]

```python
transformers.TimesFmModelForPrediction(config: TimesFmConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timesfm/modeling_timesfm.py#L566)

Modelo TimesFM para previsão de quantis e média.

#### forward[[transformers.TimesFmModelForPrediction.forward]]

```python
forward(past_values: Sequence, freq: collections.abc.Sequence[typing.Union[torch.Tensor, int]] | None = None, window_size: int | None = None, future_values: typing.Optional[torch.Tensor] = None, forecast_context_len: int | None = None, return_forecast_on_context: bool = False, truncate_negative: bool = False, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/timesfm/modeling_timesfm.py#L648)

**Parâmetros:**

past_values (`torch.Tensor` de forma `(batch_size, sequence_length)`) : Valores passados da série temporal que servem como entrada para o modelo.

freq (`torch.LongTensor` de forma `(batch_size,)`) : Índices de frequência para os dados da série temporal.

window_size (`int`, *opcional*) : Tamanho da janela da decomposição em tendência + resíduo. Se for None, não realizamos a decomposição.

future_values (`torch.Tensor`, *opcional*) : Valores futuros opcionais da série temporal a serem usados para o cálculo da perda.

forecast_context_len (`int`, *opcional*) : Comprimento máximo opcional do contexto.

return_forecast_on_context (`bool`, *opcional*) : True para retornar a previsão no contexto quando disponível, ou seja, após o primeiro patch de entrada.

truncate_negative (`bool`, *opcional*) : Trunca para apenas valores não negativos se algum dos contextos tiver valores não negativos; caso contrário, não faz nada.

**Retorna:** `TimesFmOutputForPrediction` ou `tuple(torch.Tensor)`

Um `TimesFmOutputForPrediction` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([TimesFmConfig](/docs/transformers/main/pt/model_doc/timesfm#transformers.TimesFmConfig)) e das entradas.

O método forward do [TimesFmModelForPrediction](/docs/transformers/main/pt/model_doc/timesfm#transformers.TimesFmModelForPrediction) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do modelo.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **mean_predictions** (`torch.Tensor` de forma `(batch_size, sequence_length)`) -- As previsões médias da série temporal.
- **full_predictions** (`torch.Tensor` de forma `(batch_size, sequence_length)`) -- As previsões completas da série temporal, incluindo a média e os quantis.
- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `future_values` é fornecido) -- A perda do modelo TimesFM.

Exemplo:

```python
>>> from transformers import TimesFmModelForPrediction

>>> model = TimesFmModelForPrediction.from_pretrained("google/timesfm-2.0-500m-pytorch")

>>> forecast_input = [torch.linspace(0, 20, 100).sin(), torch.linspace(0, 20, 200).sin(), torch.linspace(0, 20, 400).sin()]
>>> frequency_input = torch.tensor([0, 1, 2], dtype=torch.long)

>>> # Generate
>>> with torch.no_grad():
>>>     outputs = model(past_values=forecast_input, freq=frequency_input, return_dict=True)
>>>     point_forecast_conv = outputs.mean_predictions
>>>     quantile_forecast_conv = outputs.full_predictions
```