Skip to content

GitLab

"vscode:/vscode.git/clone" did not exist on "b2fb53d4bb568ddfd05c6ce705ee11a623686086"
Commit f42429f6 authored by bailuo's avatar bailuo
Browse files

readme

parents
Hide whitespace changes
Inline Side-by-side
Showing with 2363 additions and 0 deletions
timegpt-docs/introduction/about_timegpt.mdx 0 → 100644
View file @ f42429f6
---
title: "About TimeGPT"
description: "Learn about TimeGPT - the foundation model for time series."
icon: "brain"
---
<br />
<Info>
TimeGPT is a production-ready generative pretrained transformer model specifically designed for time series forecasting. It accurately forecasts domains such as retail, electricity, finance, and IoT with minimal code. Below you'll find a high-level overview of its features, architecture, and practical examples.
</Info>
<br />
<Steps>
<Step title="1. Start Now">
<CardGroup>
<Card title="Activate Free Trial" href="https://dashboard.nixtla.io/freetrial" description="Begin exploring TimeGPT right away with a free trial." />
<Card title="Quickstart Guide" href="/forecasting/timegpt_quickstart" description="Follow step-by-step instructions to get TimeGPT running quickly." />
</CardGroup>
</Step>
<Step title="2. Choose Your Interface">
You can access TimeGPT through:
- Self-hosted deployment on your infrastructure (recommended): [book a call](https://meetings.hubspot.com/cristian-challu/enterprise-contact-us?uuid=dc037f5a-d93b-4%5B…%5D90b-a611dd9460af&utm_source=github&utm_medium=pricing_page) for more information
- Hosted APIs: start your [free trial](https://dashboard.nixtla.io/sign_in)
- Azure Studio (TimeGEN-1)
</Step>
<Step title="3. Forecast or Detect Anomalies">
Perform zero-shot inference out-of-the-box to forecast future values or detect anomalies. Fine-tune the model if you need more targeted performance.
</Step>
</Steps>
<Check>
For detailed instructions and advanced configurations, visit our
[Quickstart Guide](/forecasting/timegpt_quickstart) and additional tutorials.
</Check>
## Features and Capabilities
<AccordionGroup>
<Accordion title="Zero-shot Inference">
**[Zero-shot Inference](/forecasting/timegpt_quickstart)**:
Generate forecasts and detect anomalies immediately without prior training. Quickly gain insights from your data.
</Accordion>
<Accordion title="Fine-tuning">
**[Fine-tuning](/forecasting/fine-tuning/steps)**:
Enhance prediction accuracy by training TimeGPT on your own datasets, tailoring it to your unique scenario.
</Accordion>
<Accordion title="API Access">
**[API Access](https://dashboard.nixtla.io/sign_in)**:
Integrate forecasts into applications via a robust API. Easily obtain keys at the
[Dashboard](https://dashboard.nixtla.io/sign_in).
Easily deploy TimeGPT in your own infrastructure or with any cloud provider using [Docker](/setup/docker) or our Python [wheel file](/setup/python_wheel).
Also accessible in [Azure Studio](/setup/azureai) or through private deployment.
</Accordion>
<Accordion title="Add Exogenous Variables">
**[Add Exogenous Variables](/forecasting/exogenous-variables/numeric_features)**:
Incorporate external variables (e.g., events, prices) to improve forecast accuracy.
</Accordion>
<Accordion title="Multiple Series Forecasting">
**[Multiple Series Forecasting](/forecasting/timegpt_quickstart)**:
Predict multiple time series at once, improving workflow efficiency.
</Accordion>
<Accordion title="Specific Loss Function">
**[Specific Loss Function](/forecasting/fine-tuning/custom_loss)**:
Customize training with loss functions that match your performance objectives.
</Accordion>
<Accordion title="Cross-validation">
**[Cross-validation](/forecasting/evaluation/cross_validation)**:
Evaluate model reliability and generalization with built-in cross-validation.
</Accordion>
<Accordion title="Prediction Intervals">
**[Prediction Intervals](/forecasting/probabilistic/prediction_intervals)**:
Generate intervals to capture forecast uncertainty.
</Accordion>
<Accordion title="Irregular Timestamps">
**[Irregular Timestamps](/forecasting/special-topics/irregular_timestamps)**:
Process data with non-uniform timestamps directly, with no extra preprocessing.
</Accordion>
<Accordion title="Anomaly Detection">
**[Anomaly Detection](/anomaly_detection/real-time/introduction)**:
Identify anomalies automatically, integrating external features for improved precision.
</Accordion>
</AccordionGroup>
<Info>
Get started quickly with the
[Quickstart guide](/forecasting/timegpt_quickstart). Explore in-depth tutorials on TimeGPT capabilities and real-world applications.
</Info>
## Architecture
<Frame caption="TimeGPT Architecture Overview">
![TimeGPT Architecture Overview](https://github.com/Nixtla/nixtla/blob/main/nbs/img/timegpt_archi.png?raw=true)
</Frame>
TimeGPT's architecture builds on the self-attention mechanism introduced in the original ["Attention is All You Need"](https://arxiv.org/abs/1706.03762) paper. Unlike typical large language models (LLMs), TimeGPT is independently trained on extensive time series datasets to minimize forecasting errors.
<Info>
TimeGPT employs an encoder-decoder structure with residual connections, layer normalization, and a linear output layer to match the decoder outputs to forecast dimensions. The attention-based mechanisms help the model capture diverse historical patterns to create accurate future predictions.
</Info>
The model processes input sequences from left to right, similar to how humans read sentences, and predicts future values (*"tokens"*) based on historical windows of time series data.
## Explore Examples and Use Cases
<AccordionGroup>
<Accordion title="Quickstart & Setup">
Quickly set up your workflow using our
[Quickstart Guide](/forecasting/timegpt_quickstart)
or learn to use the API by
[setting up your API key](/setup/setting_up_your_api_key).
</Accordion>
<Accordion title="Practical Topics">
- [Anomaly Detection](/anomaly_detection/real-time/introduction)
-
Fine-tuning with
[custom loss functions](/forecasting/fine-tuning/custom_loss)
-
Scaling workflows using
[Spark](/forecasting/forecasting-at-scale/spark),
[Dask](/forecasting/forecasting-at-scale/dask), or
[Ray](/forecasting/forecasting-at-scale/ray)
-
Integrating
[exogenous variables](/forecasting/exogenous-variables/numeric_features),
validation with
[cross-validation](/forecasting/evaluation/cross_validation),
and estimating uncertainty via
[quantile forecasts](/forecasting/probabilistic/quantiles)
or
[prediction intervals](/forecasting/probabilistic/prediction_intervals).
</Accordion>
<Accordion title="Real-world Applications">
- [Web Traffic Forecasting](/use_cases/forecasting_web_traffic)
- [Bitcoin Price Prediction](/use_cases/bitcoin_price_prediction)
</Accordion>
</AccordionGroup>
<Check>
With TimeGPT, you can rapidly iterate from initial exploration to high-accuracy forecasting. Dive deeper into the comprehensive tutorials for more sophisticated workflows.
</Check>
timegpt-docs/introduction/faq.mdx 0 → 100644
View file @ f42429f6
---
title: "TimeGPT FAQ"
description: "Frequently asked questions about TimeGPT"
icon: "question"
---
<CardGroup cols={3}>
<Card
title="Quick Start"
icon="rocket"
href="/forecasting/timegpt_quickstart"
>
Get started with TimeGPT in minutes
</Card>
<Card
title="SDK Installation"
icon="box"
href="/setup/setting_up_your_api_key"
>
Set up the Python SDK for TimeGPT
</Card>
<Card
title="Pricing"
icon="credit-card"
href="/introduction/timegpt_subscription_plans"
>
Review subscription plans and pricing
</Card>
</CardGroup>
## Commonly asked questions
<Tabs>
<Tab title="TimeGPT" icon="chart-line">
<Accordion title="What is TimeGPT?">
TimeGPT is the first foundation model for time series forecasting. It produces accurate forecasts for new time series across diverse domains using only historical values as inputs. The model reads time series data sequentially from left to right, similar to how humans read a sentence. It examines windows of past data as "tokens" and predicts what comes next based on identified patterns that extrapolate into the future. Beyond forecasting, TimeGPT supports other time series tasks, including what-if scenarios and anomaly detection.
</Accordion>
<Accordion title="Is TimeGPT based on a Large Language Model (LLM)?">
<Check>
TimeGPT is specifically designed for time series data, not text.
</Check>
No, TimeGPT is not based on any large language model. While it follows the principle of training a large transformer model on a vast dataset, its architecture specifically handles time series data and minimizes forecasting errors.
</Accordion>
<Accordion title="How do I get started with TimeGPT?">
To get started with TimeGPT, register for an account at [dashboard.nixtla.io](https://dashboard.nixtla.io/). After confirming your signup via email, you can access your dashboard with account details.
<Steps>
<Step title="Sign up" icon="plus">
Create an account at [dashboard.nixtla.io](https://dashboard.nixtla.io/)
</Step>
<Step title="Confirm email" icon="envelope">
Click the confirmation link in your email
</Step>
<Step title="Get API key" icon="key">
Find your API key in the dashboard under "API Keys"
</Step>
<Step title="Install SDK" icon="download">
Run `pip install nixtla` to install the Python SDK
</Step>
</Steps>
</Accordion>
<Accordion title="How accessible is TimeGPT and what are the usage costs?">
For a deeper understanding of TimeGPT, refer to the [research paper](https://arxiv.org/pdf/2310.03589.pdf). While some aspects of the model architecture remain confidential, registration for TimeGPT is open to everyone.
</Accordion>
<Accordion title="How can I use TimeGPT?">
You can use TimeGPT through the Python SDK or the REST API.
<Tabs>
<Tab title="Python SDK" icon="code">
```python Python SDK Forecast Example
from nixtla import NixtlaClient
# Initialize client with your API key
client = NixtlaClient(api_key="your_api_key")
# Make a forecast
forecast = client.forecast(df, h=7)
```
</Tab>
<Tab title="REST API" icon="server">
```bash REST API Forecast Example
curl -X POST "https://api.nixtla.io/timegpt" \
-H "accept: application/json" \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"df": [{"ds": "2023-01-01", "y": 100}, ...], "h": 7}'
```
</Tab>
</Tabs>
Both methods require an API key, obtained upon registration and available in your dashboard under "API Keys".
</Accordion>
</Tab>
<Tab title="API Key" icon="key">
<Accordion title="What is an API key?">
An API key is a unique string of characters that authenticates your requests when using the Nixtla SDK, ensuring only authorized users can make requests.
<Warning>
Your API key is personal and should not be shared with anyone or exposed in client-side code.
</Warning>
</Accordion>
<Accordion title="Where can I get an API key?">
Upon registration, you receive an API key available in your [dashboard](https://dashboard.nixtla.io/) under "API Keys". Keep your API key confidential.
</Accordion>
<Accordion title="How do I use my API key?">
To integrate your API key into your development workflow, refer to the [Setting Up Your API Key](/setup/setting_up_your_api_key) tutorial.
<CodeGroup>
<CodeBlock title="Python API Key Usage" icon="code">
```python Python API Key Example
from nixtla import NixtlaClient
client = NixtlaClient(api_key="your_api_key")
```
</CodeBlock>
<CodeBlock title="REST API Key Usage" icon="server">
```bash REST API Key Example
curl -X POST "https://api.nixtla.io/timegpt" \
-H "accept: application/json" \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"df": [{"ds": "2023-01-01", "y": 100}, ...], "h": 7}'
```
</CodeBlock>
</CodeGroup>
</Accordion>
<Accordion title="How can I check the status of my API key?">
Check your API key status with the [`validate_api_key` method](https://nixtlaverse.nixtla.io/nixtla/nixtla_client.html#nixtlaclient-validate-api-key) of the `NixtlaClient` class.
```python Validate API Key Example
from nixtla import NixtlaClient
nixtla_client = NixtlaClient(api_key='my_api_key_provided_by_nixtla')
nixtla_client.validate_api_key()
```
```bash Log Output
INFO:nixtla.nixtla_client:Happy Forecasting! :), If you have questions or need support, please email support@nixtla.io
True
```
</Accordion>
<Accordion title="What if my API key isn't validating?">
When you validate your API key and it returns `False`:
* If you are targeting an Azure endpoint, getting `False` from the `NixtlaClient.validate_api_key` method is expected. You can skip this step when targeting an Azure endpoint and proceed diretly to forecasting instead.
* If you are not taregting an Azure endpoint, then you should check the following:
* Make sure you are using the latest version of the SDK (Python or R).
* Check that your API key is active in your dashboard by visiting https://dashboard.nixtla.io/.
* Consider any firewalls your organization might have. There may be restricted access. If so, you can whitelist our endpoint https://api.nixtla.io/.
* To use Nixtla's API, you need to let your system know that our endpoint is ok, so it will let you access it. Whitelisting the endpoint isn't something that Nixtla can do on our side. It's something that needs to be done on the user's system. This is a bit of an [overview on whitelisting](https://www.csoonline.com/article/569493/whitelisting-explained-how-it-works-and-where-it-fits-in-a-security-program.html).
* If you work in an organization, please work with an IT team. They're likely the ones setting the security and you can talk with them to get it addressed. If you run your own systems, then it's something you should be able to update, depending on the system you're using.
</Accordion>
</Tab>
<Tab title="Privacy & Security" icon="shield-check">
<Accordion title="How do you ensure the privacy and security of my data?">
At Nixtla, we take privacy and security very seriously. To ensure you understand our data policies, refer to these documents:
<CardGroup cols={3}>
<Card title="Privacy Notice" icon="shield-check" href="/about/privacy-notice">
Our data privacy policies
</Card>
<Card title="License Agreement" icon="file" href="https://github.com/Nixtla/nixtla/blob/main/LICENSE">
Python SDK license
</Card>
<Card title="Terms and Conditions" icon="scale-balanced" href="/about/terms-and-conditions">
TimeGPT service terms
</Card>
</CardGroup>
<Info>
We offer a self-hosted version of TimeGPT, allowing you complete control over your data - your data never leaves your premises. You can either use [Docker](/setup/docker) or a [Python wheel file](/setup/python_wheel). If interested in these option, contact us at `support@nixtla.io`.
</Info>
</Accordion>
</Tab>
<Tab title="Troubleshooting" icon="wrench">
<h3 className="text-lg font-semibold mb-3">Common errors and warnings</h3>
<Accordion title="Error message: Invalid API key">
```python Invalid API Key Error
ApiError: status_code: 401, body: {'data': None, 'message': 'Invalid API key', 'details': 'Key not found', 'code': 'A12', 'requestID': 'E7F2BBTB2P', 'support': 'If you have questions or need support, please email support@nixtla.io'}
```
<Note>
This error occurs when your TimeGPT API key is invalid or not set up correctly. Use the `validate_api_key` method to verify it or check that you copied it correctly from the "API Keys" section of your [dashboard](https://dashboard.nixtla.io/).
</Note>
</Accordion>
<Accordion title="Error message: Too many requests">
```python Too Many Requests Error
ApiError: status_code: 429, body: {'data': None, 'message': 'Too many requests', 'details': 'You need to add a payment method to continue using the API, do so from https://dashboard.nixtla.io', 'code': 'A21', 'requestID': 'NCJDK7KSJ6', 'support': 'If you have questions or need support, please email support@nixtla.io'}
```
<Note>
This error occurs when you have exhausted your free credits and need to add a payment method to continue using TimeGPT. Add a payment method in the "Billing" section of your [dashboard](https://dashboard.nixtla.io/).
</Note>
</Accordion>
<Accordion title="Error message: WriteTimeout">
<Note>
A `WriteTimeout` error indicates the request exceeded allowable processing time. This commonly happens with large datasets. To fix this, increase the `num_partitions` parameter in the [`forecast` method](https://nixtlaverse.nixtla.io/nixtla/nixtla_client.html#nixtlaclient-forecast) of the `NixtlaClient` class, or use a distributed backend.
</Note>
</Accordion>
</Tab>
<Tab title="Support" icon="headphones">
Get Help with TimeGPT
For more questions or support, reach out through one of our channels:
<CardGroup cols={3}>
<Card
title="GitHub Issues"
icon="bug"
href="https://github.com/Nixtla/nixtla/issues"
>
For technical questions or bugs
</Card>
<Card title="Email Support" icon="envelope" href="mailto:support@nixtla.io">
For general inquiries or support
</Card>
<Card
title="Slack Community"
icon="comments"
href="https://join.slack.com/t/nixtlacommunity/shared_invite/zt-2ebtgjbip-QMSnvm6ED1NF5vi4xj_13Q"
>
Connect with our team and community
</Card>
</CardGroup>
<Tip className="mt-6">
When reporting issues, include your API key status, SDK version, and sample code to help us assist you more quickly.
</Tip>
</Tab>
</Tabs>
## Features & Capabilities
<Tabs>
<Tab title="Input Data" icon="database">
<Accordion title="What is the input to TimeGPT?">
TimeGPT accepts pandas dataframes in [long format](https://www.theanalysisfactor.com/wide-and-long-data/#comments) with these necessary columns:
<ParamField name="ds" type="timestamp" required>
Timestamp in format `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`
</ParamField>
<ParamField name="y" type="numeric" required>
The target variable to forecast
</ParamField>
<Tip>
You can also pass a DataFrame with a DatetimeIndex without the `ds` column.
</Tip>
<CodeGroup>
<CodeBlock title="Example Input DataFrame" icon="table">
```python Example Input DataFrame
import pandas as pd
# Create sample data
data = {
'ds': ['2023-01-01', '2023-01-02', '2023-01-03'],
'y': [10, 12, 15]
}
df = pd.DataFrame(data)
df['ds'] = pd.to_datetime(df['ds'])
print(df)
```
</CodeBlock>
<CodeBlock title="Printed DataFrame Output" icon="clipboard">
```
ds y
0 2023-01-01 10
1 2023-01-02 12
2 2023-01-03 15
```
</CodeBlock>
</CodeGroup>
TimeGPT also works with [distributed dataframes](/forecasting/forecasting-at-scale/computing_at_scale) like `dask`, `spark`, and `ray`.
</Accordion>
<Accordion title="Can TimeGPT handle multiple time series?">
<Check>
Yes, TimeGPT can forecast multiple time series simultaneously.
</Check>
For guidance on forecasting multiple time series at once, consult the [Multiple Series](/forecasting/timegpt_quickstart) tutorial.
<CodeGroup>
<CodeBlock title="Multiple Series Forecasting Example" icon="chart-bar">
```python Multiple Series Forecasting
# Example of forecasting multiple series
from nixtla import NixtlaClient
# Initialize client
client = NixtlaClient(api_key="your_api_key")
# Group identifier for multiple series
df['unique_id'] = df['store_id'] + '_' + df['item_id']
# Forecast multiple series at once
forecast = client.forecast(df, h=7, level=[80, 90])
```
</CodeBlock>
</CodeGroup>
</Accordion>
</Tab>
<Tab title="Forecasting" icon="chart-bar">
<Accordion title="Does TimeGPT support forecasting with exogenous variables?">
<Check>
Yes, TimeGPT can incorporate external variables into forecasts.
</Check>
For instructions on incorporating exogenous variables to TimeGPT, see the [Exogenous Variables](/forecasting/exogenous-variables/numeric_features) tutorial. For incorporating calendar dates, the [Holidays and Special Dates](https://docs.nixtla.io/docs/tutorials-holidays_and_special_dates) tutorial might help. For categorical variables, refer to the [Categorical Variables](https://docs.nixtla.io/docs/tutorials-categorical_variables) tutorial.
<CodeGroup>
<CodeBlock title="Exogenous Variables Forecast Example" icon="code-branch">
```python Exogenous Variables Forecast
# Forecasting with exogenous variables
forecast = client.forecast(
df,
h=7,
X_df=exog_df # DataFrame with exogenous variables
)
```
</CodeBlock>
</CodeGroup>
</Accordion>
<Accordion title="Can TimeGPT be used to forecast historical data?">
Yes. To forecast historical data using TimeGPT, use cross-validation. See the full tutorial on [cross-validation](/forecasting/evaluation/cross_validation).
<CodeGroup>
<CodeBlock title="Historical Forecast Example" icon="clock">
```python Historical Forecast
# Get in-sample predictions
historical_forecast = client.cross_validation(
df,
h=12,
n_windows=11 # Set as many windows as you want
)
```
</CodeBlock>
</CodeGroup>
</Accordion>
<Accordion title="What is the maximum forecast horizon allowed by TimeGPT?">
TimeGPT has no maximum forecast horizon, but performance decreases as the horizon increases. When the forecast horizon exceeds the data's seasonal length (for example, more than 12 months for monthly data), you will receive this message:
<Info>
`WARNING:nixtla.nixtla_client:The specified horizon "h" exceeds the model horizon. This may lead to less accurate forecasts. Please consider using a smaller horizon`
</Info>
For details, refer to the [Long Horizon in Time Series](/forecasting/model-version/longhorizon_model) tutorial.
<Tip>
For best results, keep your forecast horizon within the seasonal pattern of your data.
</Tip>
</Accordion>
</Tab>
<Tab title="Advanced Features" icon="gear">
<Accordion title="Can TimeGPT be used for anomaly detection?">
<Check>
Yes, TimeGPT includes anomaly detection capabilities.
</Check>
To learn how to use TimeGPT for anomaly detection, refer to the [Anomaly Detection](/anomaly_detection/real-time/introduction) tutorial.
<CodeGroup>
<CodeBlock title="Anomaly Detection Example" icon="bug">
```python Anomaly Detection Example
# Detect anomalies in time series
anomalies = client.detect_anomalies(df)
```
</CodeBlock>
</CodeGroup>
</Accordion>
<Accordion title="Does TimeGPT support cross-validation?">
Yes. To learn how to use TimeGPT for cross-validation, refer to the [Cross-Validation](/forecasting/evaluation/cross_validation) tutorial.
<CodeGroup>
<CodeBlock title="Cross-Validation Example" icon="check">
```python Cross-Validation Example
# Perform cross-validation
cv_results = client.cross_validation(
df,
h=7,
k=3, # Number of folds
test_size=7 # Size of each test fold
)
```
</CodeBlock>
</CodeGroup>
</Accordion>
<Accordion title="Can TimeGPT be used for uncertainty quantification?">
Yes. For more information, explore the [Prediction Intervals](/forecasting/probabilistic/prediction_intervals) and [Quantile Forecasts](/forecasting/probabilistic/quantiles) tutorials.
<CodeGroup>
<CodeBlock title="Prediction Intervals Example" icon="chart-bar">
```python Prediction Intervals Example
# Generate prediction intervals
forecast_with_intervals = client.forecast(
df,
h=7,
level=[80, 90, 95] # Confidence levels
)
```
</CodeBlock>
</CodeGroup>
</Accordion>
</Tab>
<Tab title="Data Requirements" icon="clipboard-check">
<Accordion title="Can TimeGPT handle large datasets?">
<Check>
Yes, TimeGPT works with distributed computing frameworks for large datasets.
</Check>
For large datasets with hundreds of thousands or millions of time series, we recommend using a distributed backend. TimeGPT works with several [distributed computing frameworks](/forecasting/forecasting-at-scale/computing_at_scale), including [Spark](/forecasting/forecasting-at-scale/spark), [Ray](/forecasting/forecasting-at-scale/ray), and [Dask](/forecasting/forecasting-at-scale/dask).
<CodeGroup>
<CodeBlock title="Using Dask for Large Datasets" icon="desktop">
```python Using Dask Example
import dask.dataframe as dd
# Convert to Dask DataFrame
dask_df = dd.from_pandas(df, npartitions=4)
# Forecast using Dask backend
forecast = client.forecast(dask_df, h=7)
```
</CodeBlock>
</CodeGroup>
</Accordion>
<Accordion title="Can TimeGPT be used with limited/short data?">
TimeGPT supports any amount of data for generating point forecasts and can produce results with just one observation per series. When using arguments such as `level`, `finetune_steps`, `X_df` (exogenous variables), or `add_history`, additional data points are necessary depending on data frequency. For more details, refer to the [Data Requirements](/data_requirements/data_requirements) tutorial.
<Info>
While TimeGPT can work with minimal data, more historical data typically produces better forecasts.
</Info>
</Accordion>
<Accordion title="Can TimeGPT handle missing values?">
<Warning>
TimeGPT cannot handle missing values or series with irregular timestamps.
</Warning>
For more information, see the [Forecasting Time Series with Irregular Timestamps](/forecasting/special-topics/irregular_timestamps) and [Dealing with Missing Values](/data_requirements/missing_values) tutorials.
</Accordion>
</Tab>
<Tab title="Visualization" icon="chart-bar">
<Accordion title="How can I plot the TimeGPT forecast?">
The `NixtlaClient` class has a [`plot` method](/reference/sdk_reference#nixtlaclient-plot) for visualizing forecasts. This method works only in interactive environments such as Jupyter notebooks, not in Python scripts.
<CodeGroup>
<CodeBlock title="Plotting Forecast Example" icon="image">
```python Plotting Forecast Example
# Plot forecast
client.plot(
historical_data=df,
forecast_data=forecast,
level=[80, 95] # Optional: show prediction intervals
)
```
</CodeBlock>
</CodeGroup>
</Accordion>
<Accordion title="Does TimeGPT support polars?">
Currently, TimeGPT does not support polars.
</Accordion>
<Accordion title="Does TimeGPT produce stable predictions?">
<Check>
Yes, TimeGPT produces consistent results for identical inputs.
</Check>
TimeGPT is engineered for stability, ensuring consistent results for identical input data. Given the same dataset, the model will produce the same forecasts.
</Accordion>
<Accordion title="Can TimeGPT forecast data with simple pattern such as a straight line or sine wave?">
While not the primary use case for TimeGPT, it can generate solid results on simple data patterns like straight lines. Zero-shot predictions might not always meet expectations, but fine-tuning allows TimeGPT to quickly grasp trends and produce accurate forecasts. For more details, refer to the [Improve Forecast Accuracy with TimeGPT](/forecasting/improve_accuracy) tutorial.
</Accordion>
</Tab>
<Tab title="Fine-tuning" icon="sliders">
<Accordion title="What is fine-tuning?">
<Check>
Fine-tuning improves TimeGPT's performance for your specific data patterns.
</Check>
TimeGPT was trained on the largest publicly available time series dataset, covering domains including finance, retail, healthcare, and more. This comprehensive training enables TimeGPT to produce accurate forecasts for new time series without additional training (zero-shot learning).
While the zero-shot model provides a solid baseline, TimeGPT performance often improves through fine-tuning. During this process, the TimeGPT model undergoes additional training using your specific dataset, starting from the pre-trained parameters.
<CodeGroup>
<CodeBlock title="Fine-tuning Usage Example" icon="wrench">
```python Fine-tuning Example
# Fine-tune with 100 steps
forecast = client.forecast(
df,
h=7,
finetune_steps=100,
finetune_loss="mse" # Mean Squared Error
)
```
</CodeBlock>
</CodeGroup>
For a comprehensive guide on fine-tuning, refer to the [fine-tuning](/forecasting/fine-tuning/steps) and [fine-tuning with a specific loss function](/forecasting/fine-tuning/custom_loss) tutorials.
</Accordion>
<Accordion title="Do I have to fine-tune every series?">
No, you do not need to fine-tune every series individually. When using the `finetune_steps` parameter, the model fine-tunes across all series in your dataset simultaneously. This cross-learning approach allows the model to learn from multiple series at once, which can improve individual forecasts.
<Info>
Selecting the right number of fine-tuning steps may require experimentation. As fine-tuning steps increase, the model becomes more specialized to your dataset but takes longer to train and may become more prone to overfitting.
</Info>
</Accordion>
<Accordion title="Can I save fine-tuned parameters?">
<Check>
Yes, you can save and reuse fine-tuned models.
</Check>
You can fine-tune the TimeGPT model, save it, and reuse it later. For detailed instructions, see our guide on [Re-using Fine-tuned Models](/forecasting/fine-tuning/save_reuse_delete_finetuned_models).
<Tabs>
<Tab title="Save Model" icon="save">
```python Save Fine-tuned Model
# Fine-tune and save the model
fine_tuned_parameters = client.forecast(
df,
h=7,
finetune_steps=100,
return_model=True # Return the fine-tuned parameters
)
# Save to file
import pickle
with open("fine_tuned_model.pkl", "wb") as f:
pickle.dump(fine_tuned_parameters, f)
```
</Tab>
<Tab title="Load Model" icon="folder-open">
```python Load Fine-tuned Model
# Load the fine-tuned parameters
import pickle
with open("fine_tuned_model.pkl", "rb") as f:
fine_tuned_parameters = pickle.load(f)
# Use the fine-tuned model
forecast = client.forecast(
new_df,
h=7,
model=fine_tuned_parameters
)
```
</Tab>
</Tabs>
</Accordion>
</Tab>
</Tabs>
<Note>
Need more help? Contact our [support team](mailto:support@nixtla.io).
</Note>
timegpt-docs/introduction/introduction.mdx 0 → 100644
View file @ f42429f6
---
title: "Introduction"
description: "Welcome to TimeGPT - The foundational model for time series forecasting and anomaly detection"
icon: "bolt"
---
## Power your time series analysis with TimeGPT
TimeGPT is the first foundation model for time series, providing state-of-the-art forecasting and anomaly detection capabilities to help you make better decisions with your time series data.
<CardGroup cols={2}>
<Card
title="Quick Start Guide"
icon="rocket"
href="/forecasting/timegpt_quickstart"
>
Get started with TimeGPT in minutes with our simple Python interface
</Card>
<Card
title="Set Up Your API Key"
icon="key"
href="/setup/setting_up_your_api_key"
>
Set up your environment to start using TimeGPT right away
</Card>
</CardGroup>
## Core Capabilities
Explore the powerful features that TimeGPT offers for your time series needs.
<CardGroup cols={3}>
<Card
title="Forecasting"
icon="chart-bar"
href="/forecasting/timegpt_quickstart"
>
Generate accurate predictions for your time series data
</Card>
<Card
title="Anomaly Detection"
icon="circle-exclamation"
href="/anomaly_detection/historical_anomaly_detection"
>
Identify unusual patterns in historical data
</Card>
<Card
title="Real-Time Monitoring"
icon="gauge-high"
href="/anomaly_detection/real-time/introduction"
>
Detect anomalies as they happen with online detection
</Card>
</CardGroup>
## Learn & Explore
Enhance your skills with our comprehensive tutorials and use cases.
<CardGroup cols={2}>
<Card
title="Tutorials"
icon="book-open"
href="/forecasting/timegpt_quickstart"
>
Practical guides to get the most out of TimeGPT
</Card>
<Card
title="Real-World Use Cases"
icon="building"
href="/use_cases/forecasting_web_traffic"
>
See how TimeGPT solves real business problems
</Card>
<Card
title="Computing at Scale"
icon="server"
href="/forecasting/forecasting-at-scale/computing_at_scale"
>
Learn how to use TimeGPT with big data frameworks
</Card>
<Card
title="Advanced Features"
icon="wand-magic-sparkles"
href="/forecasting/fine-tuning/steps"
>
Take your models further with fine-tuning and specialized techniques
</Card>
</CardGroup>
## Resources
Find additional resources to help you succeed with TimeGPT.
<CardGroup cols={2}>
<Card
title="SDK Reference"
icon="code"
href="/reference/sdk_reference"
>
Detailed SDK documentation for developers
</Card>
<Card
title="FAQ"
icon="circle-info"
href="/introduction/faq"
>
Get answers to commonly asked questions
</Card>
</CardGroup>
\ No newline at end of file
timegpt-docs/introduction/timegpt_subscription_plans.mdx 0 → 100644
View file @ f42429f6
---
title: "TimeGPT Subscription Plans"
description: "Overview of TimeGPT's Enterprise subscription plans with deployment options, support, and trial details."
icon: "briefcase"
---
## Overview
<Info>
TimeGPT provides multiple Enterprise subscription plans that can be tailored
to meet your specific forecasting requirements. This includes customization of
API call limits, user seats, and varying levels of support.
</Info>
<AccordionGroup>
<Accordion title="Core Features">
- Scalable API calls to match your organization’s growth
- Flexible user access management
- High-level support options (email, chat, phone, or dedicated support)
</Accordion>
<Accordion title="Usage Options">
We offer three main options to use TimeGPT:
<Tabs>
<Tab title="API">
The easiest option, you don't need to worry about any infrastructure just make calls directly to TimeGPT using any of our SDKs or plugins.
</Tab>
<Tab title="Cloud Deployment on Azure">
Host TimeGPT on Azure, managed by Nixtla.\
• Quick setup with minimal maintenance requirements.\
• Automatic updates and patches.\
• Ideal for teams wanting a fully managed solution.
</Tab>
<Tab title="Self-Hosted Deployment">
Host TimeGPT in your own infrastructure.\
• Greater control over data and security.\
• Customizable configurations for specific compliance needs.\
• Ideal for organizations requiring on-premise or private cloud solutions.
</Tab>
</Tabs>
</Accordion>
</AccordionGroup>
## Get in Touch
If you'd like to explore custom plan options—for instance, adjusting the number of API calls, user limits, or support level—reach out to us at [support@nixtla.io](mailto:support@nixtla.io).\
You can also schedule a demo through this [link](https://meetings.hubspot.com/cristian-challu/enterprise-contact-us?uuid=dc037f5a-d93b-4%5B…%5D90b-a611dd9460af&utm_source=github&utm_medium=pricing_page) to see TimeGPT in action and discuss your needs in more detail.
<Check>
**Free Trial Available\!**\\
When you [**create your account**](https://dashboard.nixtla.io), you receive a 30-day free trial with no credit card required. Your access expires after 30 days unless you upgrade to a paid plan. If you need more time to evaluate or want to continue using TimeGPT, please **contact us** for flexible plan options.
</Check>
<Steps>
<Step title="Step 1 – Create Your Account">
Visit [our dashboard](https://dashboard.nixtla.io) and sign up for a new
account.
</Step>
<Step title="Step 2 – Explore the Dashboard">
Log in and explore the TimeGPT interface to set up forecasting tasks,
configure APIs, and invite team members.
</Step>
<Step title="Step 3 – Upgrade or Contact Us">
Before the trial ends, decide if you’d like to upgrade to an Enterprise plan
or contact us for a custom plan.
</Step>
</Steps>
<Info>
**Pricing and Billing Information**\\
Additional pricing details and frequently asked questions can be found on our [FAQ page](introduction/faq).
</Info>
<CardGroup cols={2}>
<Card
title="Next Steps"
icon="calendar"
href="https://meetings.hubspot.com/cristian-challu/enterprise-contact-us"
cta="Learn More"
>
Ready to see TimeGPT in action? Schedule a personalized demo to learn how
TimeGPT can enhance your forecasting capabilities.
</Card>
<Card
title="Contact Us"
icon="envelope"
href="mailto:support@nixtla.io"
cta="Email Support"
>
Have questions, need custom requirements, or want more info on our plans and
deployments? Contact us any time.
</Card>
</CardGroup>
timegpt-docs/introduction/why_timegpt.mdx 0 → 100644
View file @ f42429f6
---
title: "Why TimeGPT?"
description: "Understand the benefits of using TimeGPT for time series analysis."
icon: "lightbulb"
---
<Info>
Before running this notebook, please visit our [dashboard](https://dashboard.nixtla.io) to obtain your TimeGPT `api_key`.
</Info>
## Why TimeGPT?
TimeGPT is a powerful, general-purpose time series forecasting solution. Throughout this notebook, we compare TimeGPT's performance against three popular forecasting approaches:
- Classical model (ARIMA)
- Machine learning model (LightGBM)
- Deep learning model (N-HiTS)
<iframe width="800" height="800" src="https://marimo.io/p/@max/notebook-e185w7?show-code=false" title="Graph"> </iframe>
Below are three core benefits that our users value the most:
<CardGroup cols={3}>
<Card title="Accuracy" icon="chart-line">
TimeGPT consistently outperforms traditional models by accurately capturing complex patterns.
</Card>
<Card title="Speed" icon="bolt">
Quickly generates forecasts with minimal training and tuning requirements per series.
</Card>
<Card title="Ease of Use" icon="rocket">
Minimal setup and no complex preprocessing make TimeGPT immediately accessible for use.
</Card>
</CardGroup>
## TimeGPT Advantage
TimeGPT delivers **superior results with minimal effort** compared to traditional approaches. In head-to-head testing against ARIMA, LightGBM, and N-HiTS models on M5 competition data, TimeGPT consistently achieves better accuracy metrics (**lowest RMSE at 592.6** and **SMAPE at 4.94%**).
Unlike other models which require:
- _Extensive preprocessing_
- _Parameter tuning_
- _Significant computational resources_
TimeGPT provides **powerful forecasting capabilities** with a simple API interface, making advanced time series analysis **accessible to users of all technical backgrounds**.
<Steps>
<Step title="1. Data Introduction">
This notebook uses an aggregated subset from the M5 Forecasting Accuracy competition. The dataset:
- Consists of **7 daily time series**
- Has **1,941 observations** per series
- Reserves the last **28 observations** for evaluation on unseen data
```python Data Loading and Stats Preview
import os
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
from nixtla import NixtlaClient
from utilsforecast.plotting import plot_series
from utilsforecast.losses import mae, rmse, smape
from utilsforecast.evaluation import evaluate
nixtla_client = NixtlaClient(
# api_key='my_api_key_provided_by_nixtla'
)
df = pd.read_csv(
'https://datasets-nixtla.s3.amazonaws.com/demand_example.csv',
parse_dates=['ds']
)
# Display aggregated statistics per time series
df.groupby('unique_id').agg({
"ds": ["min", "max", "count"],
"y": ["min", "mean", "median", "max"]
})
```
<Info>
Below is a preview of the aggregated statistics for each of the 7 time series.
</Info>
| unique_id | min date | max date | count | min y | mean y | median y | max y |
| --------- | ---------- | ---------- | ----- | ----- | -------- | -------- | ------ |
| FOODS_1 | 2011-01-29 | 2016-05-22 | 1941 | 0.0 | 2674.086 | 2665.0 | 5493.0 |
| FOODS_2 | 2011-01-29 | 2016-05-22 | 1941 | 0.0 | 4015.984 | 3894.0 | 9069.0 |
| ... | ... | ... | ... | ... | ... | ... | ... |
Next, we split our dataset into training and test sets. Here, we use data up to "2016-04-24" for training and the remaining data for testing.
```python Train-Test Split Example
df_train = df.query('ds <= "2016-04-24"')
df_test = df.query('ds > "2016-04-24"')
print(df_train.shape, df_test.shape)
# (13391, 3) (196, 3)
```
</Step>
<Step title="2. Model Fitting (TimeGPT, ARIMA, LightGBM, N-HiTS)">
TimeGPT is compared against four different modeling approaches. Each approach forecasts the final 28 days of our dataset and we compare results across Root Mean Squared Error (RMSE) and Symmetric Mean Absolute Percentage Error (SMAPE).
<AccordionGroup>
<Accordion title="2.1 TimeGPT">
<Info>
TimeGPT offers a streamlined solution for time series forecasting with minimal setup.
</Info>
```python TimeGPT Forecasting with NixtlaClient
fcst_timegpt = nixtla_client.forecast(
df=df_train,
target_col='y',
h=28,
model='timegpt-1-long-horizon',
finetune_steps=10,
level=[90]
)
evaluation_timegpt.groupby(['metric'])['TimeGPT'].mean()
# metric
# rmse 592.607378
# smape 0.049403
# Name: TimeGPT, dtype: float64
```
</Accordion>
<Accordion title="2.2 Classical Models (ARIMA)">
<Info>
ARIMA is a common baseline for time series, though it often requires more data preprocessing and does not handle multiple series as efficiently.
</Info>
```python ARIMA Forecasting Using StatsForecast
from statsforecast import StatsForecast
from statsforecast.models import AutoARIMA
sf = StatsForecast(models=[AutoARIMA()], freq='D')
fcst_arima = sf.forecast(h=28, df=df_train)
# Evaluation methods omitted here for brevity
```
</Accordion>
<Accordion title="2.3 Machine Learning Models (LightGBM)">
<Info>
LightGBM is a popular gradient-boosted tree approach. However, careful feature engineering is typically required for optimal results.
</Info>
```python LightGBM Modeling with AutoMLForecast
import optuna
from mlforecast.auto import AutoMLForecast, AutoLightGBM
mlf = AutoMLForecast(models=[AutoLightGBM()], freq='D')
mlf.fit(df_train)
fcst_lgbm = mlf.predict(28)
# Evaluation methods omitted here for brevity
```
</Accordion>
<Accordion title="2.4 N-HiTS">
<Info>
N-HiTS is a deep learning architecture for time series. While powerful, it often requires GPU resources and more hyperparameter tuning.
</Info>
```python N-HiTS Deep Learning Forecast
from neuralforecast.core import NeuralForecast
from neuralforecast.models import NHITS
nf = NeuralForecast(models=[NHITS()], freq='D')
nf.fit(df=df_train)
fcst_nhits = nf.predict()
# Evaluation methods omitted here for brevity
```
</Accordion>
</AccordionGroup>
</Step>
<Step title="3. Performance Comparison and Results">
Below is a summary of the performance metrics (RMSE and SMAPE) on the test dataset. TimeGPT consistently delivers superior forecasting accuracy:
| Model | RMSE | SMAPE |
| -------- | ----- | ----- |
| ARIMA | 724.9 | 5.50% |
| LightGBM | 687.8 | 5.14% |
| N-HiTS | 605.0 | 5.34% |
| TimeGPT | 592.6 | 4.94% |
<Frame caption="Comparative Performance Visualization">
![Performance Chart](https://raw.githubusercontent.com/Nixtla/nixtla/readme_docs/nbs/_docs/docs/getting-started/7_why_timegpt_files/figure-markdown_strict/cell-27-output-1.png)
</Frame>
<Frame caption="Benchmark Results">
![Benchmarking Results](https://github.com/Nixtla/nixtla/blob/main/nbs/img/timeseries_model_arena.png?raw=true)
</Frame>
</Step>
<Step title="4. Conclusion">
TimeGPT stands out with its accuracy, speed, and ease of use. Get started today by visiting the
[Nixtla dashboard](https://dashboard.nixtla.io) to generate your
`api_key` and access advanced forecasting with minimal overhead.
</Step>
</Steps>
\ No newline at end of file
timegpt-docs/logo/dark.svg 0 → 100644
View file @ f42429f6
<svg width="318" height="46" viewBox="0 0 318 46" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M136.055 0V45.2992H125.334L106.681 11.0379H105.159V45.2992H97.9268V0H108.647L127.3 34.2613H128.822V0H136.055Z" fill="white"/><path d="M151.968 0V45.2992H144.353V0H151.968Z" fill="white"/><path d="M178.866 25.694H176.709L166.05 45.2992H157.8L170.808 21.4449L159.644 0H167.637L176.774 17.322H178.931L188.256 0H196.188L184.833 21.1925L197.841 45.3033H189.277L178.874 25.698L178.866 25.694Z" fill="white"/><path d="M235.522 6.72365H221.057V45.2992H213.442V6.72365H198.912V0H235.518V6.72365H235.522Z" fill="white"/><path d="M271.878 38.1319V45.3033H239.587V0H247.202V38.1319H271.882H271.878Z" fill="white"/><path d="M306.01 32.2914H287.422L283.3 45.2992H275.685L290.719 0H302.901L318 45.2992H310.198L306.01 32.2914ZM289.58 25.5027H303.792L298.017 7.41963H295.29L289.58 25.5027Z" fill="white"/><path d="M6.03786 44.3543L38.2275 12.1646C38.5287 11.8634 39.0171 11.8634 39.3142 12.1646L54.7396 27.7202C55.0408 28.0214 55.5251 28.0214 55.8263 27.7202L77.2589 6.28752C77.5601 5.98634 77.5601 5.50201 77.2589 5.20083L72.5906 0.532526C72.2895 0.231345 71.8051 0.231345 71.5039 0.532526L55.9524 16.084C55.6513 16.3852 55.1669 16.3852 54.8657 16.084L39.3142 0.540666C39.0131 0.239486 38.5287 0.239486 38.2275 0.540666L22.6761 16.0922C22.3749 16.3933 21.8905 16.3933 21.5894 16.0922L6.03786 0.540666C5.73668 0.239486 5.25235 0.239486 4.95116 0.540666L0.225885 5.26595C-0.0752952 5.56713 -0.0752952 6.05146 0.225885 6.35264L15.7774 21.9041C16.0786 22.2053 16.0786 22.6897 15.7774 22.9908L0.225885 38.5423C-0.0752952 38.8435 -0.0752952 39.3279 0.225885 39.629L4.95116 44.3543C5.25235 44.6555 5.73668 44.6555 6.03786 44.3543Z" fill="white"/><path d="M6.03786 44.3543L38.2275 12.1646C38.5287 11.8634 39.0171 11.8634 39.3142 12.1646L54.7396 27.7202C55.0408 28.0214 55.5251 28.0214 55.8263 27.7202L77.2589 6.28752C77.5601 5.98634 77.5601 5.50201 77.2589 5.20083L72.5906 0.532526C72.2895 0.231345 71.8051 0.231345 71.5039 0.532526L55.9524 16.084C55.6513 16.3852 55.1669 16.3852 54.8657 16.084L39.3142 0.540666C39.0131 0.239486 38.5287 0.239486 38.2275 0.540666L22.6761 16.0922C22.3749 16.3933 21.8905 16.3933 21.5894 16.0922L6.03786 0.540666C5.73668 0.239486 5.25235 0.239486 4.95116 0.540666L0.225885 5.26595C-0.0752952 5.56713 -0.0752952 6.05146 0.225885 6.35264L15.7774 21.9041C16.0786 22.2053 16.0786 22.6897 15.7774 22.9908L0.225885 38.5423C-0.0752952 38.8435 -0.0752952 39.3279 0.225885 39.629L4.95116 44.3543C5.25235 44.6555 5.73668 44.6555 6.03786 44.3543Z" fill="white"/><path d="M52.371 31.1805L52.489 31.0624L47.2794 25.8528C46.9782 25.5517 46.4939 25.5517 46.1927 25.8528L39.3144 32.7312C39.0132 33.0323 38.5289 33.0323 38.2277 32.7312L31.3494 25.8528C31.0482 25.5517 30.5639 25.5517 30.2627 25.8528L25.5374 30.5781C25.2362 30.8793 25.2362 31.3636 25.5374 31.6648L38.2277 44.3551C38.5289 44.6563 39.0132 44.6563 39.3144 44.3551L52.432 31.2375L52.375 31.1805H52.371Z" fill="white"/><path d="M63.4121 25.7236L58.6894 30.4463C58.389 30.7467 58.389 31.2338 58.6894 31.5342L71.5049 44.3496C71.8053 44.65 72.2923 44.65 72.5927 44.3496L77.3154 39.6269C77.6158 39.3265 77.6158 38.8394 77.3154 38.539L64.5 25.7236C64.1996 25.4232 63.7125 25.4232 63.4121 25.7236Z" fill="white"/></svg>
\ No newline at end of file
timegpt-docs/logo/light.svg 0 → 100644
View file @ f42429f6
<svg width="450" height="64" viewBox="0 0 450 64" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M192.204 -0.00012207V63.9941H177.06L150.709 15.5931H148.558V63.9941H138.341V-0.00012207H153.486L179.837 48.4009H181.987V-0.00012207H192.204Z" fill="black"/>
<path d="M214.685 -0.00012207V63.9941H203.927V-0.00012207H214.685Z" fill="black"/>
<path d="M252.684 36.2978H249.637L234.578 63.9941H222.924L241.3 30.2951L225.528 -0.00012207H236.821L249.729 24.4706H252.776L265.949 -0.00012207H277.155L261.113 29.9386L279.489 63.9999H267.392L252.696 36.3035L252.684 36.2978Z" fill="black"/>
<path d="M332.722 9.49839H312.287V63.9941H301.53V9.49839H281.003V-0.00012207H332.716V9.49839H332.722Z" fill="black"/>
<path d="M384.083 53.8689V63.9999H338.464V-0.00012207H349.222V53.8689H384.088H384.083Z" fill="black"/>
<path d="M432.301 45.6181H406.042L400.217 63.9941H389.46L410.699 -0.00012207H427.908L449.239 63.9941H438.217L432.301 45.6181ZM409.089 36.0275H429.167L421.008 10.4816H417.156L409.089 36.0275Z" fill="black"/>
<path d="M8.52962 62.6593L54.004 17.1848C54.4295 16.7593 55.1195 16.7593 55.5392 17.1848L77.3306 39.1602C77.7561 39.5857 78.4403 39.5857 78.8657 39.1602L109.144 8.88224C109.569 8.45676 109.569 7.77255 109.144 7.34707L102.549 0.752153C102.123 0.326675 101.439 0.326675 101.014 0.752153L79.044 22.7218C78.6185 23.1473 77.9343 23.1473 77.5088 22.7218L55.5392 0.763653C55.1137 0.338174 54.4295 0.338174 54.004 0.763653L32.0344 22.7333C31.6089 23.1588 30.9247 23.1588 30.4992 22.7333L8.52962 0.763653C8.10415 0.338174 7.41993 0.338174 6.99445 0.763653L0.319047 7.43906C-0.106431 7.86454 -0.106431 8.54876 0.319047 8.97424L22.2887 30.9439C22.7141 31.3693 22.7141 32.0536 22.2887 32.479L0.319047 54.4487C-0.106431 54.8742 -0.106431 55.5584 0.319047 55.9838L6.99445 62.6593C7.41993 63.0847 8.10415 63.0847 8.52962 62.6593Z" fill="black"/>
<path d="M8.52962 62.6593L54.004 17.1848C54.4295 16.7593 55.1195 16.7593 55.5392 17.1848L77.3306 39.1602C77.7561 39.5857 78.4403 39.5857 78.8657 39.1602L109.144 8.88224C109.569 8.45676 109.569 7.77255 109.144 7.34707L102.549 0.752153C102.123 0.326675 101.439 0.326675 101.014 0.752153L79.044 22.7218C78.6185 23.1473 77.9343 23.1473 77.5088 22.7218L55.5392 0.763653C55.1137 0.338174 54.4295 0.338174 54.004 0.763653L32.0344 22.7333C31.6089 23.1588 30.9247 23.1588 30.4992 22.7333L8.52962 0.763653C8.10415 0.338174 7.41993 0.338174 6.99445 0.763653L0.319047 7.43906C-0.106431 7.86454 -0.106431 8.54876 0.319047 8.97424L22.2887 30.9439C22.7141 31.3693 22.7141 32.0536 22.2887 32.479L0.319047 54.4487C-0.106431 54.8742 -0.106431 55.5584 0.319047 55.9838L6.99445 62.6593C7.41993 63.0847 8.10415 63.0847 8.52962 62.6593Z" fill="black"/>
<path d="M73.9845 44.0486L74.1512 43.8819L66.7916 36.5222C66.3661 36.0968 65.6819 36.0968 65.2564 36.5222L55.5394 46.2392C55.1139 46.6647 54.4297 46.6647 54.0043 46.2392L44.2873 36.5222C43.8618 36.0968 43.1776 36.0968 42.7521 36.5222L36.0767 43.1976C35.6512 43.6231 35.6512 44.3073 36.0767 44.7328L54.0043 62.6604C54.4297 63.0859 55.1139 63.0859 55.5394 62.6604L74.0707 44.1291L73.9902 44.0486H73.9845Z" fill="black"/>
<path d="M89.5823 36.3397L82.9106 43.0114C82.4862 43.4358 82.4862 44.1239 82.9106 44.5483L101.015 62.6526C101.439 63.077 102.127 63.077 102.552 62.6526L109.223 55.9809C109.648 55.5565 109.648 54.8684 109.223 54.4441L91.1191 36.3397C90.6947 35.9153 90.0067 35.9153 89.5823 36.3397Z" fill="black"/>
</svg>
timegpt-docs/openapi.json 0 → 100644
View file @ f42429f6
This source diff could not be displayed because it is too large. You can view the blob instead.
timegpt-docs/pending_content/capabilities-forecast-add_categorical_variables.mdx 0 → 100644
View file @ f42429f6
---
title: "Add categorical variables"
description: "Learn how to create and use custom categorical variables with SpecialDates in TimeGPT forecasting."
icon: "tags"
---
<Info>
TimeGPT supports categorical variables to enhance your forecasts. This document shows you how to create and use custom categorical variables with `SpecialDates`.
</Info>
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Nixtla/nixtla/blob/main/nbs/docs/capabilities/forecast/04_categorical_variables.ipynb)
<CardGroup cols={2}>
<Card title="Key Concept: Categorical Variables">
Categorical variables are non-numeric data points that help distinguish different groups or conditions in your dataset.
For example, holiday labels or season markers can be treated as categorical variables in time series forecasting.
</Card>
<Card title="Key Concept: SpecialDates">
`SpecialDates` is a utility in Nixtla that allows you to define specific date-based labels (e.g., holiday periods, special events).
These labels can then be merged into your main dataset as additional columns for forecasting.
</Card>
</CardGroup>
<Steps>
<Step title="Step 1: Import the Libraries">
```python Import Libraries
import pandas as pd
import datetime
from nixtla import NixtlaClient
from nixtla.date_features import SpecialDates
```
</Step>
<Step title="Step 2: Set Up the Nixtla Client">
You can either use the default endpoint or an Azure AI endpoint. Select the appropriate tab below:
<Tabs>
<Tab title="Default Endpoint">
```python Nixtla Client Default Endpoint
nixtla_client = NixtlaClient(
# defaults to os.environ.get("NIXTLA_API_KEY")
api_key='my_api_key_provided_by_nixtla'
)
```
</Tab>
<Tab title="Azure AI Endpoint">
<Check>
**Use an Azure AI endpoint**<br />
When using an Azure AI endpoint, set the `base_url` argument as shown below.
</Check>
```python Nixtla Client Azure AI Endpoint
nixtla_client = NixtlaClient(
base_url="your azure ai endpoint",
api_key="your api_key"
)
```
</Tab>
</Tabs>
</Step>
<Step title="Step 3: Read the Data">
```python Load Dataset
# Read the data
df = pd.read_csv(
"https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv"
)
```
</Step>
<Step title="Step 4: Create Categorical Variables">
Use `SpecialDates` to define holiday or seasonal periods you want to label in your time series.
```python Define and Merge Categorical Variables
# Create categorical variables for Christmas and summer vacations
categories_dates = SpecialDates(
special_dates={
'christmas_vacations': [
datetime.date(year, 12, 1) for year in range(1949, 1960 + 1)
],
'summer_vacations': [
datetime.date(year, month, 1)
for year in range(1949, 1960 + 1)
for month in (6, 7)
]
}
)
dates = pd.date_range('1949-01-01', '1960-12-01', freq='MS')
categories_df = categories_dates(dates).reset_index(drop=True)
# Merge with the dataset
cat_df = pd.concat([df, categories_df], axis=1)
```
</Step>
<Step title="Step 5: Forecast with Categorical Variables">
```python Forecast with Categorical Variables
# Forecast
forecast_df = nixtla_client.forecast(
df=cat_df,
h=24,
target_col='value',
time_col='timestamp'
)
```
</Step>
</Steps>
<Warning>
Below is an example of the forecast process logs.
These messages show up when you run the forecast, including any warnings about exogenous variables or horizon lengths.
</Warning>
<Accordion title="Forecast Process Log">
```bash Forecast Logs
INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: MS
WARNING:nixtla.nixtla_client:You did not provide X_df. Exogenous variables in df are ignored. To suppress this warning, please add X_df with exogenous variables: christmas_vacations, summer_vacations
WARNING:nixtla.nixtla_client:The specified horizon "h" exceeds the model horizon. This may lead to less accurate forecasts. Please consider using a smaller horizon.
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
```
</Accordion>
<Info>
**Available models in Azure AI**<br />
If you use an Azure AI endpoint, set `model="azureai"` explicitly:
<br /><br />
```python Azure AI Model Parameter
nixtla_client.forecast(
...,
model="azureai"
)
```
<br />
The public API supports two models: `timegpt-1` and `timegpt-1-long-horizon`.
By default, `timegpt-1` is used. See [this tutorial](https://docs.nixtla.io/docs/tutorials-long_horizon_forecasting) for more details on using the `timegpt-1-long-horizon` model.
</Info>
<AccordionGroup>
<Accordion title="Additional Resource: Categorical Variables Tutorial">
For a more in-depth guide on forecasting with categorical variables,
see the tutorial here: [Categorical variables](https://docs.nixtla.io/docs/tutorials-categorical_variables).
</Accordion>
</AccordionGroup>
\ No newline at end of file
timegpt-docs/pending_content/capabilities-forecast-add_exogenous_variables.mdx 0 → 100644
View file @ f42429f6
---
title: "Add Exogenous Variables to Forecasts"
description: "Learn how to incorporate external factors to improve forecast accuracy."
icon: "table-list"
---
# Adding Exogenous Variables to Your Forecasts
<Info>
Exogenous variables are additional features external to your target time series. They can significantly improve forecasting accuracy when historical and/or future values are available.
</Info>
<Steps>
<Step title="1. Set up your environment">
Install and import the required libraries:
```python Setup Environment
import pandas as pd
from nixtla import NixtlaClient
nixtla_client = NixtlaClient(
api_key='my_api_key_provided_by_nixtla'
)
```
</Step>
<Step title="2. (Optional) Configure Azure AI endpoint">
<Info>
Use an Azure AI endpoint by setting the **base_url** argument:
</Info>
```python Azure AI Endpoint Configuration
nixtla_client = NixtlaClient(
base_url="your azure ai endpoint",
api_key="your api_key"
)
```
</Step>
<Step title="3. Choose your exogenous variable approach">
Depending on your use case, you can include only historical variables, only future variables, or both.
</Step>
</Steps>
<CardGroup cols={3}>
<Card title="Historical Exogenous">
Use past exogenous data for your forecast by including it in `df`.
</Card>
<Card title="Future Exogenous">
Supply future values of exogenous variables to the `X_df` parameter to forecast beyond the historical period.
</Card>
<Card title="Historical + Future">
Combine both historical and future exogenous data for maximum flexibility and accuracy.
</Card>
</CardGroup>
<AccordionGroup>
<Accordion title="1. Historical Exogenous Variables">
Include historical exogenous variables in the same DataFrame you pass to `forecast`:
```python Historical Exogenous Variables Example
# Read data
df = pd.read_csv(
'https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short-with-ex-vars.csv'
)
# Forecast using historical exogenous variables
forecast_df = nixtla_client.forecast(
df=df,
h=24,
id_col='unique_id',
target_col='y',
time_col='ds',
hist_exog_list=[
'Exogenous1',
'Exogenous2',
'day_0',
'day_1',
'day_2',
'day_3',
'day_4',
'day_5',
'day_6'
]
)
```
</Accordion>
<Accordion title="2. Future Exogenous Variables">
Provide future exogenous values via the `X_df` parameter:
```python Future Exogenous Variables Example
import numpy as np
# Read historical data
df = pd.read_csv(
'https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short-with-ex-vars.csv'
)
# Load future exogenous variable data
future_ex_vars_df = pd.read_csv(
'https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short-future-ex-vars.csv'
)
# Forecast using future exogenous variables
forecast_df = nixtla_client.forecast(
df=df,
X_df=future_ex_vars_df,
h=24,
id_col='unique_id',
target_col='y',
time_col='ds'
)
```
</Accordion>
<Accordion title="3. Historical and Future Exogenous Variables">
Combine both historical and future exogenous variables for a more comprehensive model:
```python Historical and Future Exogenous Variables Example
# Read historical data
df = pd.read_csv(
'https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short-with-ex-vars.csv'
)
# Load future exogenous variable data
future_ex_vars_df = pd.read_csv(
'https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short-future-ex-vars.csv'
)
# Select specific exogenous variable columns from future data
future_ex_vars_df = future_ex_vars_df[[
"unique_id",
"ds",
"Exogenous1",
"Exogenous2"
]]
# Forecast using both historical and future exogenous variables
forecast_df = nixtla_client.forecast(
df=df,
X_df=future_ex_vars_df,
h=24,
id_col='unique_id',
target_col='y',
time_col='ds',
hist_exog_list=[
'day_0',
'day_1',
'day_2',
'day_3',
'day_4',
'day_5',
'day_6'
]
)
```
</Accordion>
</AccordionGroup>
<Info>
**Run on Azure AI Models**<br/>
When using an Azure AI endpoint, set `model="azureai"`:
</Info>
```python Azure AI Model Example
nixtla_client.detect_anomalies(
...,
model="azureai"
)
```
<Info>
The public API supports two models: `timegpt-1` and `timegpt-1-long-horizon`.
By default, `timegpt-1` is used.
</Info>
For more details on exogenous features and long-horizon forecasting, see:
- [Exogenous variables tutorial](https://docs.nixtla.io/docs/tutorials-exogenous_variables)
- [Categorical variables tutorial](https://docs.nixtla.io/docs/tutorials-categorical_variables)
- [Long-horizon forecasting tutorial](https://docs.nixtla.io/docs/tutorials-long_horizon_forecasting)
\ No newline at end of file
timegpt-docs/pending_content/capabilities-forecast-add_holidays_and_special_dates.mdx 0 → 100644
View file @ f42429f6
---
title: "Add holidays and special dates"
description: "Incorporate country-specific holidays and custom special dates into your forecasting models to improve accuracy."
icon: "calendar"
---
<Info>
Easily incorporate country-specific holidays and custom special dates into your forecasting. This feature helps your models capture seasonal effects and important observances to improve forecast accuracy.
</Info>
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Nixtla/nixtla/blob/main/nbs/docs/capabilities/forecast/10_prediction_intervals.ipynb)
For a quick interactive walkthrough, open the notebook in Google Colab by clicking above.
<CardGroup cols={2}>
<Card title="Why consider holidays?">
Holidays often reflect strong seasonal patterns. Accounting for them helps your forecasts better capture shifts in consumer behavior, staffing needs, and overall demand.
</Card>
<Card title="Why define special dates?">
Beyond standard holidays, custom special dates (such as company events, promotions, or local celebrations) can further improve the granularity and accuracy of your forecasting.
</Card>
</CardGroup>
<Steps>
<Step title="Install and Import Dependencies">
```python Install and Dependencies
import pandas as pd
from nixtla import NixtlaClient
from nixtla.date_features import CountryHolidays, SpecialDates
```
</Step>
<Step title="Create a Nixtla Client">
Use one of the following options to initialize the Nixtla client.
<Tabs>
<Tab title="Default Nixtla Endpoint">
```python Default Nixtla Client Initialization
nixtla_client = NixtlaClient(
# Defaults to os.environ.get("NIXTLA_API_KEY")
api_key='my_api_key_provided_by_nixtla'
)
```
</Tab>
<Tab title="Using Azure AI Endpoint">
<Info>
You must explicitly set the **base_url** parameter for Azure AI endpoints.
</Info>
```python Azure AI Client Initialization
nixtla_client = NixtlaClient(
base_url="your azure ai endpoint",
api_key="your api_key"
)
```
</Tab>
</Tabs>
</Step>
<Step title="Retrieve Country-Specific Holidays">
<AccordionGroup>
<Accordion title="Show code">
```python Retrieve Country-specific Holidays
# Retrieve country-specific holidays (example for the US)
c_holidays = CountryHolidays(countries=['US'])
periods = 365 * 1
dates = pd.date_range(end='2023-09-01', periods=periods)
holidays_df = c_holidays(dates)
holidays_df.head()
```
</Accordion>
</AccordionGroup>
<Check>
Country-level holidays help capture recurring seasonal effects. Make sure to specify countries relevant to your business.
</Check>
</Step>
<Step title="Define and Retrieve Custom Special Dates">
<AccordionGroup>
<Accordion title="Show code">
```python Define Custom Special Dates
# Define custom special dates
special_dates = SpecialDates(
special_dates={
'Important Dates': [
'2021-02-26',
'2020-02-26'
],
'Very Important Dates': [
'2021-01-26',
'2020-01-26',
'2019-01-26'
]
}
)
periods = 365 * 1
dates = pd.date_range(end='2023-09-01', periods=periods)
special_dates_df = special_dates(dates)
special_dates_df.head()
```
</Accordion>
</AccordionGroup>
<Info>
By defining your own special dates, you can capture one-time events or patterns that repeat on arbitrary dates.
</Info>
</Step>
</Steps>
For a more comprehensive tutorial on leveraging holidays and special dates in your forecasting models, see:
[Holidays and special dates](https://docs.nixtla.io/docs/tutorials-holidays_and_special_dates).
\ No newline at end of file
timegpt-docs/pending_content/capabilities-forecast-cross_validation.mdx 0 → 100644
View file @ f42429f6
---
title: "Cross Validation"
description: "Learn how to validate your forecast models using time series cross-validation."
icon: "clipboard-check"
---
# Cross-Validation
<Info>
Cross-validation is a robust method to evaluate and improve your forecasting models. By splitting your time series into multiple windows, you can test how well your model performs on unseen data.
</Info>
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Nixtla/nixtla/blob/main/nbs/docs/capabilities/forecast/09_cross_validation.ipynb)
<Steps>
<Step title="1. Install and Import Dependencies">
<Info>
Make sure you have the `pandas` and `nixtla` libraries installed.
</Info>
```python Import dependencies
import pandas as pd
from nixtla import NixtlaClient
```
</Step>
<Step title="2. Initialize Nixtla Client">
<Check>
Replace `my_api_key_provided_by_nixtla` with the API key you received from Nixtla.
</Check>
<Tabs>
<Tab title="Default Nixtla Setup">
```python Default NixtlaClient initialization
nixtla_client = NixtlaClient(
# defaults to os.environ.get("NIXTLA_API_KEY")
api_key='my_api_key_provided_by_nixtla'
)
```
</Tab>
<Tab title="Azure AI Setup">
<Check>
To use an Azure AI endpoint, add the `base_url` argument.
</Check>
```python Azure AI NixtlaClient initialization
nixtla_client = NixtlaClient(
base_url="your azure ai endpoint",
api_key="my_api_key_provided_by_nixtla"
)
```
</Tab>
</Tabs>
</Step>
<Step title="3. Read and Prepare Data">
```python Load dataset
# Read the data
df = pd.read_csv(
"https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv"
)
```
<Info>
In this example, we are using the airplane passengers dataset. You can replace the URL with your own dataset.
</Info>
</Step>
<Step title="4. Perform Cross-Validation">
<Info>
Specify the number of windows with the `n_windows` argument. Each window will be used to generate forecasts and evaluate performance.
</Info>
```python Cross-validation example
# Cross-validation using two windows
forecast_cv_df = nixtla_client.cross_validation(
df=df,
h=12,
n_windows=2,
time_col='timestamp',
target_col="value",
)
```
<AccordionGroup>
<Accordion title="Detailed Logging">
```bash Cross-validation logs
INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Inferred freq: MS
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Cross Validation Endpoint...
```
</Accordion>
</AccordionGroup>
</Step>
</Steps>
<Info>
If you're using an Azure AI endpoint for forecasting, define the model explicitly by setting `model="azureai"` in the `forecast` method:
</Info>
```python Forecast with Azure AI model
nixtla_client.forecast(
...,
model="azureai"
)
```
<CardGroup>
<Card title="timegpt-1">
This is the default model in the public API. It provides reliable short- to medium-range forecasts.
</Card>
<Card title="timegpt-1-long-horizon">
Designed for extended-range forecasts. Refer to the [long-horizon forecasting tutorial](https://docs.nixtla.io/docs/tutorials-long_horizon_forecasting) for more details.
</Card>
</CardGroup>
<Info>
For more guidance and examples, consult our [cross-validation tutorial](https://docs.nixtla.io/docs/tutorials-cross_validation).
</Info>
\ No newline at end of file
timegpt-docs/pending_content/capabilities-forecast-fine_tuning.mdx 0 → 100644
View file @ f42429f6
---
title: "Fine-tuning"
description: "How to fine-tune TimeGPT forecasts using finetune_steps and finetune_depth parameters for improved accuracy."
icon: "gear"
---
## Overview
You can fine-tune TimeGPT forecasts by specifying the `finetune_steps` parameter. Fine-tuning allows you to further adjust the model to the nuances of your specific time series data, potentially improving forecast accuracy.
<Info>
Fine-tuning uses additional training iterations on your own dataset. While it can improve forecast performance, it also increases the compute time needed to generate predictions.
</Info>
---
## Key Fine-tuning Concepts
<CardGroup>
<Card title="finetune_steps" icon="gear">
The number of additional training steps to run. Increasing this value can improve accuracy, but also requires more computation.
</Card>
<Card title="finetune_depth" icon="circle-up">
The intensity or depth of the fine-tuning. By default, `finetune_depth=1`. Increasing it can further refine forecasts but also makes training more resource-intensive.
</Card>
</CardGroup>
<Warning>
If you set both `finetune_steps` and `finetune_depth` too high, the training process can become very time-consuming.
</Warning>
---
## Setting Up Your Environment
Before creating forecasts, you need to install and initialize the Nixtla client with your API key.
<Steps>
<Steps title="Install and Import Libraries">
```python Import Libraries
import pandas as pd
from nixtla import NixtlaClient
```
</Steps>
<Steps title="Initialize the Nixtla Client">
```python Initialize Nixtla Client
nixtla_client = NixtlaClient(
# defaults to os.environ.get("NIXTLA_API_KEY")
api_key="my_api_key_provided_by_nixtla"
)
```
</Steps>
</Steps>
<Info>
If you're using an Azure AI endpoint, set the `base_url` parameter accordingly:
</Info>
```python Azure AI Configuration
nixtla_client = NixtlaClient(
base_url="your azure ai endpoint",
api_key="your api_key"
)
```
---
## Forecasting with Fine-tuning
Follow these steps to fine-tune your TimeGPT forecasts.
<Steps>
<Steps title="Load Data">
```python Load Dataset
df = pd.read_csv(
"https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv"
)
```
</Steps>
<Steps title="Create a Forecast (Example: 5 Fine-tune Steps)">
```python Fine-tune Forecast Example
forecast_df = nixtla_client.forecast(
df=df,
h=12,
finetune_steps=5,
time_col="timestamp",
target_col="value"
)
```
</Steps>
</Steps>
<Check>
If you are using Azure AI, specify the model name explicitly:
</Check>
<CodeGroup>
```python Azure AI Model Usage
nixtla_client.forecast(
df=df,
h=12,
finetune_steps=5,
model="azureai",
time_col="timestamp",
target_col="value"
)
```
</CodeGroup>
<Info>
In the public Nixtla API, you can choose from two models:
- `timegpt-1` (default)
- `timegpt-1-long-horizon`
See the [long-horizon forecasting tutorial](https://docs.nixtla.io/docs/tutorials-long_horizon_forecasting) for information about when and how to use `timegpt-1-long-horizon`.
</Info>
---
## Advanced Fine-tuning
<AccordionGroup>
<Accordion title="Increase Fine-tuning Depth">
By default, `finetune_depth=1`. You can increase the fine-tuning intensity by specifying a higher `finetune_depth`.
```python Increase Fine-tuning Depth Example
df = pd.read_csv(
"https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv"
)
forecast_df = nixtla_client.forecast(
df=df,
h=12,
finetune_steps=5,
finetune_depth=2,
time_col="timestamp",
target_col="value"
)
```
</Accordion>
</AccordionGroup>
<Info>
Increasing `finetune_depth` and `finetune_steps` will increase computation time, thus requiring more time to generate predictions.
</Info>
---
## Additional Resources
For more detailed information and advanced configurations, see the
[fine-tuning tutorial](https://docs.nixtla.io/docs/tutorials-fine_tuning).
\ No newline at end of file
timegpt-docs/pending_content/capabilities-forecast-finetuning_with_a_custom_loss_function.mdx 0 → 100644
View file @ f42429f6
---
title: "Finetuning with a custom loss function"
description: "Learn how to fine-tune forecasting models using a preferred loss function for improved performance."
icon: "gear"
---
# Finetuning with a Custom Loss Function
<Info>
Fine-tuning your model allows you to specify a preferred loss function for forecasting tasks. This can significantly impact how your model learns from the data and, ultimately, its performance.
</Info>
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Nixtla/nixtla/blob/main/nbs/docs/capabilities/forecast/08_custom_loss_function.ipynb)
## Overview
When fine-tuning, specify the loss function using the `finetune_loss` argument.
<Check>
The current supported values for `finetune_loss` are:
</Check>
<CardGroup cols={3}>
<Card
title="mae"
description="Mean Absolute Error"
/>
<Card
title="mse"
description="Mean Squared Error"
/>
<Card
title="rmse"
description="Root Mean Squared Error"
/>
<Card
title="mape"
description="Mean Absolute Percentage Error"
/>
<Card
title="smape"
description="Symmetric Mean Absolute Percentage Error"
/>
</CardGroup>
## Steps to Fine-Tune Your Forecast Model
<Steps>
<Step title="1. Import Libraries">
```python Import Libraries
import pandas as pd
from nixtla import NixtlaClient
```
</Step>
<Step title="2. Initialize the Nixtla Client">
<Tabs groupId="client-type">
<Tab title="Nixtla Public API">
<Info>
By default, the `NixtlaClient` will look for the API key in your environment variables (`NIXTLA_API_KEY`).
</Info>
```python Nixtla Public API Initialization
nixtla_client = NixtlaClient(
# defaults to os.environ.get("NIXTLA_API_KEY")
api_key='my_api_key_provided_by_nixtla'
)
```
</Tab>
<Tab title="Azure AI Endpoint">
<Info>
To use an Azure AI endpoint, set the `base_url` parameter. You can also specify the model later in the `forecast` method.
</Info>
```python Azure AI Endpoint Initialization
nixtla_client = NixtlaClient(
base_url="your azure ai endpoint",
api_key="your api_key"
)
```
</Tab>
</Tabs>
</Step>
<Step title="3. Load Your Data">
```python Load CSV Data
# Read data
df = pd.read_csv(
"https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv"
)
```
</Step>
<Step title="4. Fine-Tune the Model and Forecast">
```python Fine-Tune Model with Loss Function
# Fine-tune with a specified loss function and make predictions
forecast_df = nixtla_client.forecast(
df=df,
h=12,
finetune_steps=5,
finetune_loss="mae",
time_col='timestamp',
target_col="value"
)
```
<AccordionGroup>
<Accordion title="Example Logs">
```bash Log Output
INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: MS
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
```
</Accordion>
</AccordionGroup>
</Step>
</Steps>
## Using Azure AI or Nixtla’s Public API
<Info>
When using an Azure AI endpoint, set `model="azureai"` explicitly in the `forecast` method.
</Info>
```python Forecast with Azure AI Model
nixtla_client.forecast(
df=df,
h=12,
finetune_steps=5,
finetune_loss="mae",
time_col='timestamp',
target_col="value",
model="azureai"
)
```
<Info>
When using Nixtla’s public API, two models are available:
</Info>
<CardGroup cols={2}>
<Card
title="timegpt-1"
description="Default model"
/>
<Card
title="timegpt-1-long-horizon"
description="For long-horizon forecasting tasks"
/>
</CardGroup>
For more details on choosing or using `timegpt-1-long-horizon`, see the tutorial:
[Long-Horizon Forecasting](https://docs.nixtla.io/docs/tutorials-long_horizon_forecasting)
---
## Learn More
For a detailed explanation on how different loss functions influence model performance, read the tutorial:
[Fine-tuning with a Specific Loss Function](https://docs.nixtla.io/docs/tutorials-fine_tuning_with_a_specific_loss_function)
\ No newline at end of file
timegpt-docs/pending_content/capabilities-forecast-forecast.mdx 0 → 100644
View file @ f42429f6
---
title: "Forecast"
description: "Advanced zero-shot forecasting capabilities for time series data"
icon: "chart-line"
---
<Info>
TimeGPT offers advanced zero-shot forecasting capabilities for a wide range of
time series domains, thanks to its large-scale and diverse pretraining.
</Info>
<AccordionGroup>
<Accordion title="Overview">
This section provides an overview of forecasting features available in TimeGPT. You can leverage TimeGPT for:
- Zero-shot forecasting
- Forecasting with exogenous variables
- Manipulating holidays and special dates
- Incorporating categorical variables
- Long-horizon forecasting
- Forecasting multiple series
- Fine-tuning TimeGPT
- Working with specific loss functions
- Cross-validation
- Adding prediction intervals
- Handling irregular timestamps
These capabilities allow teams to handle real-world scenarios across different industries and problem domains.
</Accordion>
<Accordion title="When to Use TimeGPT for Forecasting">
TimeGPT is a powerful choice when you need:
- Rapid iteration without explicit training on your own datasets.
- A flexible model that generalizes well across different time series scenarios.
- Support for additional context or features like holidays, external events, or categorical data.
</Accordion>
</AccordionGroup>
<CardGroup cols={2}>
<Card title="Key Feature: Zero-Shot Forecasting">
Zero-shot forecasting lets you generate predictions without having to train
a new model from scratch on your data. This can significantly reduce your
time to production for new or changing forecasting tasks.
</Card>
<Card title="Key Feature: Fine-Tuning">
Gain performance boosts by fine-tuning TimeGPT on your own dataset or by
leveraging specific loss functions. This approach helps tailor the model to
your unique forecasting requirements.
</Card>
</CardGroup>
<Check>
By combining zero-shot approaches with optional fine-tuning, TimeGPT offers a
robust and efficient solution for time series forecasting.
</Check>
<Steps>
<Step title="1. Zero-Shot Forecasting">
Zero-shot forecasting is an excellent starting point for quick insights.
For detailed instructions, see: [Zero-shot forecasting documentation](https://docs.nixtla.io/docs/capabilities-forecast-quickstart).
</Step>
<Step title="2. Add Exogenous Variables">
If you have additional external drivers or explanatory factors, include them to improve predictions.
For more details, visit: [Forecasting with exogenous variables](https://docs.nixtla.io/docs/capabilities-forecast-add_exogenous_variables).
</Step>
<Step title="3. Incorporate Holidays or Special Dates">
Holidays and special dates can have significant impact on time series signals.
Learn how to handle them here: [Forecasting with holidays and special dates](https://docs.nixtla.io/docs/capabilities-forecast-add_holidays_and_special_dates).
</Step>
</Steps>
<Tabs>
<Tab title="More Forecasting Tasks">
<AccordionGroup>
<Accordion title="Forecasting with Categorical Variables">
Explore how to add categorical information and improve your forecasts:
[Forecasting with categorical
variables](https://docs.nixtla.io/docs/capabilities-forecast-add_categorical_variables).
</Accordion>
<Accordion title="Long-Horizon Forecasting">
Learn best practices for forecasting extended time periods well into the
future: [Long-horizon
forecasting](https://docs.nixtla.io/docs/capabilities-forecast-long_horizon_forecasting).
</Accordion>
<Accordion title="Forecasting Multiple Series">
Handle multiple time series simultaneously to build scalable and
efficient solutions: [Forecasting multiple
series](https://docs.nixtla.io/docs/capabilities-forecast-multiple_series_forecasting).
</Accordion>
</AccordionGroup>
</Tab>
<Tab title="Fine-Tuning & Advanced Topics">
<AccordionGroup>
<Accordion title="Fine-Tuning TimeGPT">
Adapt TimeGPT to your specific domain or data distribution: [Fine-tuning
TimeGPT](https://docs.nixtla.io/docs/capabilities-forecast-fine_tuning).
</Accordion>
<Accordion title="Custom Loss Functions">
Go beyond default metrics by defining custom loss functions:
[Fine-tuning with a specific loss
function](https://docs.nixtla.io/docs/capabilities-forecast-finetuning_with_a_custom_loss_function).
</Accordion>
<Accordion title="Cross-Validation">
Ensure robust forecasting performance through cross-validation:
[Cross-validation](https://docs.nixtla.io/docs/capabilities-forecast-cross_validation).
</Accordion>
<Accordion title="Prediction Intervals">
Build prediction intervals to quantify uncertainty in your forecasts:
[Adding prediction
intervals](https://docs.nixtla.io/docs/capabilities-forecast-predictions_intervals).
</Accordion>
<Accordion title="Irregular Timestamps">
Discover approaches to deal with missing or irregular time steps:
[Handling irregular
timestamps](https://docs.nixtla.io/docs/capabilities-forecast-irregular_timestamps).
</Accordion>
</AccordionGroup>
</Tab>
</Tabs>
<Info>
Below is a concise code snippet to get started with zero-shot forecasting.
This example demonstrates how to import TimeGPT and make a simple prediction.
</Info>
<CodeGroup>
```python Zero-Shot Forecasting Example
# Example: Zero-shot forecasting with TimeGPT
from timegpt import TimeGPT
# Initialize TimeGPT
gpt_model = TimeGPT()
# Sample time series data (replace with your own)
time_series_data = [10, 12, 13, 12, 15, 18, 20]
# Make a forecast
forecast = gpt_model.forecast(time_series_data, horizon=3)
print("Forecast:", forecast)
```
</CodeGroup>
<Check>
Congratulations\! You are now equipped with TimeGPT's key forecasting
features. Explore the linked guides for detailed instructions on advanced
topics.
</Check>
timegpt-docs/pending_content/capabilities-forecast-long_horizon_forecasting.mdx 0 → 100644
View file @ f42429f6
---
title: "Long-horizon forecasting"
description: "Learn how to predict multiple seasonal cycles into the future using TimeGPT"
icon: "calendar"
---
Long-horizon forecasting is used to predict multiple seasonal cycles into the future. The TimeGPT model offers long-term forecasting capabilities by setting the parameter `model="timegpt-1-long-horizon"`.
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Nixtla/nixtla/blob/main/nbs/docs/capabilities/forecast/10_prediction_intervals.ipynb)
<Info>
This page provides an overview of how to perform long-horizon forecasting using the Nixtla Client. You'll also learn how to switch between default and Azure AI endpoints.
</Info>
## Overview
Long-horizon forecasting allows you to forecast beyond one full seasonal cycle. For example, if monthly data exhibits annual seasonality, you can project several years into the future. TimeGPT's long-horizon variant can handle these extended forecasts.
<AccordionGroup>
<Accordion title="Why use long-horizon forecasting?">
Long-horizon forecasting is especially useful for capacity planning, budgeting, strategic decision making, and any scenario where you need to see multiple seasonal patterns ahead.
</Accordion>
</AccordionGroup>
<Steps>
<Step title="Step 1 — Install and Import Libraries">
```python Import Libraries
# Import Libraries
import pandas as pd
from nixtla import NixtlaClient
```
</Step>
<Step title="Step 2 — Initialize Nixtla Client">
You can initialize the Nixtla Client by providing your API key:
```python Initialize Nixtla Client
nixtla_client = NixtlaClient(
# defaults to os.environ.get("NIXTLA_API_KEY")
api_key="my_api_key_provided_by_nixtla"
)
```
<Info>
**Use an Azure AI endpoint**<br/>
To use an Azure AI endpoint, explicitly specify the `base_url` parameter:
```python Initialize Azure AI Client
nixtla_client = NixtlaClient(
base_url="your azure ai endpoint",
api_key="your api_key"
)
```
</Info>
</Step>
<Step title="Step 3 — Load Data and Create Forecast">
Load your time series data into a Pandas DataFrame, then call the `forecast` method:
```python Load Data and Create Forecast
# Load sample dataset
df = pd.read_csv(
"https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv"
)
# Generate forecast
forecast_df = nixtla_client.forecast(
df=df,
h=36,
model="timegpt-1-long-horizon",
time_col="timestamp",
target_col="value"
)
```
</Step>
<Step title="Step 4 — Review Logs">
The Nixtla Client emits helpful messages and warnings during the forecasting process:
<Accordion title="Forecasting Log Output">
```bash Forecasting Logs
INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: MS
WARNING:nixtla.nixtla_client:The specified horizon "h" exceeds the model horizon.
This may lead to less accurate forecasts. Please consider using a smaller horizon.
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
```
</Accordion>
<Warning>
When the specified horizon `h` exceeds the model's recommended horizon, the accuracy may be lower. Consider adjusting `h` based on your forecasting needs.
</Warning>
</Step>
</Steps>
## Model Options
<Info>
If using an Azure AI endpoint, explicitly select the Azure model with:
```python Use Azure Model
nixtla_client.forecast(..., model="azureai")
```
</Info>
<CardGroup cols={3}>
<Card title="timegpt-1" icon="robot">
Default model for general forecasting tasks.
</Card>
<Card title="timegpt-1-long-horizon" icon="calendar">
For extended (long-horizon) forecasts.
</Card>
<Card title="azureai" icon="cloud">
For Nixtla services running on your Azure endpoint.
</Card>
</CardGroup>
<Check>
Refer to the
[
Tutorial on Long-horizon Forecasting
](https://docs.nixtla.io/docs/tutorials-long_horizon_forecasting)
for best practices and guidance on choosing the right model for your use case.
</Check>
For a comprehensive walkthrough on forecasting more than one season ahead, visit the complete tutorial on
[Long-horizon forecasting](https://docs.nixtla.io/docs/tutorials-long_horizon_forecasting).
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment