# Time-Series Seasonality Engine MCP > calculate_acf_seasonality performs Autocorrelation Function (ACF) analysis on time-series data to mathematically confirm cyclical patterns and seasonality lags. This function returns exact correlation coefficients, allowing your AI client to prove—not guess—if a cycle exists in sales, traffic, or temperature records. ## Overview - **Category:** artificial-intelligence - **Price:** Free - **Tags:** time-series, autocorrelation, seasonality, data-science, forecasting, statistical-analysis ## Description When you’re dealing with time-series data—whether it's sales figures, website traffic logs, or temperature readings—you don't just need to *see* if a pattern exists; you need hard proof. The ACF Seasonality Engine handles that. Your AI client runs the `calculate_acf_seasonality` tool, which executes a full Autocorrelation Function (ACF) analysis against your time-series dataset. This function isn't just guessing at cycles; it quantifies them. It detects and measures seasonal cycles by calculating specific autocorrelation coefficients across various lags. When you run this, your agent gives you exact numbers that prove whether a periodicity is statistically significant. You’re not relying on visual inspection or vague trends; you’re getting mathematical evidence. The core function of the tool is to calculate these correlation coefficients at measurable time lags. For instance, if you've got weekly sales data and suspect a seven-day cycle, the ACF output will give you the precise coefficient for lag 7. If you're tracking yearly consumer behavior, it provides the exact metric for lag 365 days. This lets your AI client definitively prove that a specific seasonal pattern exists within the records. It’s about specificity. The engine processes your data to pinpoint exactly *how* correlated one point in time is with another point separated by a defined interval. By generating these precise coefficients, you move past subjective analysis. You'll know if those cyclical patterns are real and measurable enough for robust reporting or if they're just noise. Think of it this way: instead of telling your boss, 'It looks like sales spike every Christmas,' the engine lets your agent tell them, 'The ACF calculation returned a correlation coefficient of 0.91 at lag 365 days, confirming an annual periodicity in Q4.' It's that level of detail and certainty that changes everything. The `calculate_acf_seasonality` tool gives you the ability to test for various cycles simultaneously—weekly, monthly, quarterly, or custom intervals—all within one workflow. It establishes a mathematical baseline for seasonality so you don’t have to guess at underlying rhythms in complex data sets. ## Tools ### calculate_acf_seasonality Runs the Autocorrelation Function (ACF) on time-series data to detect and quantify seasonal cycles. ## Prompt Examples **Prompt:** ``` Here are daily store visitor counts for the last 60 days. Run the ACF up to lag 14 to see if there is a weekly seasonality peak at lag 7. ``` **Response:** ``` The computation has been executed with mathematical precision. All results are exact and ready for review. ``` **Prompt:** ``` Calculate the autocorrelation for these 48 months of revenue data. Tell me which lag has the highest correlation. ``` **Response:** ``` The computation has been executed with mathematical precision. All results are exact and ready for review. ``` **Prompt:** ``` Compute the ACF for these server error spikes. If all lags (1 to 10) are close to 0, confirm that the errors are completely random. ``` **Response:** ``` The computation has been executed with mathematical precision. All results are exact and ready for review. ``` ## Capabilities ### Prove Cyclical Patterns Your AI client runs the ACF function against time-series data to detect specific, measurable seasonality lags. ## Use Cases ### Validating Weekly Sales Peaks A retail analyst feeds the last 90 days of store visitor data into their agent. They run `calculate_acf_seasonality` up to lag 14. The resulting high correlation coefficient at lag 7 mathematically confirms that weekly sales peaks are a genuine, measurable cycle. ### Checking for Financial Cycles A quant researcher needs to know if quarterly revenue patterns are consistent. They use `calculate_acf_seasonality` on 48 months of data. The tool identifies the strongest correlation at lag 12, proving a clear annual cycle they can build their financial model around. ### Debugging Server Errors An ops engineer suspects server errors happen in bursts every few days. They calculate ACF for the error spike logs and run `calculate_acf_seasonality` up to lag 20. If they get a high coefficient at lag 3, they know their system has a predictable three-day cycle. ### Determining Environmental Patterns A climate scientist analyzes temperature readings over two years. They run `calculate_acf_seasonality` and observe clear, strong correlations at both lag 7 (weekly) and lag 365 (annual), confirming both short-term and long-term seasonal dependencies. ## Benefits - Stop guessing about seasonality. Running `calculate_acf_seasonality` provides exact correlation coefficients, giving you mathematical proof of weekly (lag 7) or monthly cycles that general LLMs can’t deliver. - Validate data randomness quickly. If the ACF results across multiple lags are all near zero, you have statistical confirmation that your observed fluctuations are random noise—not a pattern. - Identify specific lag periods. Need to know if yearly peaks happen every 12 months? `calculate_acf_seasonality` pinpoints those exact time intervals using correlation values. - Ground forecasting in fact. By proving the existence and strength of seasonality first, you build models that don't rely on guesswork or superficial visual trends. - Work with diverse data types. The tool handles sales figures, server error counts, temperature readings, and financial metrics equally well. ## How It Works The bottom line is: you get verifiable statistical proof regarding the periodicity or randomness of your time-series data. 1. You feed the `calculate_acf_seasonality` tool a historical dataset and specify the maximum lag (the window size) you want tested. 2. The engine runs the mathematical ACF calculation, determining how correlated data points are with themselves at various intervals (lags). 3. Your agent receives a set of exact correlation coefficients. High values indicate strong cyclical patterns at that specific lag. ## Frequently Asked Questions **What does an ACF score mean?** Scores range from -1 to 1. A high score at Lag 7 (e.g., 0.85) means that today's value is highly correlated with the value from exactly 7 days ago (a strong weekly cycle). **What is the maximum lag I should check?** Typically, you should check lags up to 1/3 or 1/4 of your total dataset length. For 3 years of monthly data (36 points), check up to lag 12. **Why can't Claude do this without a tool?** ACF requires summing the products of mean-adjusted variances across shifting array indices. LLMs cannot compute this in their latent space accurately. **What data format should I use when calling calculate_acf_seasonality?** It expects a single array of numerical values in chronological order. You must pass the raw time-series measurements, not metadata or date objects. **Can calculate_acf_seasonality handle extremely large datasets?** Yes, the engine is built for scale. While performance depends on dataset length, it processes millions of data points efficiently without crashing. **What happens if I pass non-numeric values to calculate_acf_seasonality?** The tool throws a structured data type error. Your agent needs to catch this and ensure the input array contains only valid numbers before making the call. **Does calculate_acf_seasonality require explicit date indexing in the prompt?** No, you just pass the sequence of values. The function assumes that the physical order of the data points represents time passing. **Is my private time-series data kept secure when running calculate_acf_seasonality?** All computations happen within a secured Vurb environment. We do not retain your raw input data once the correlation calculation is complete.