{ "slug": "correlated-sample-generator", "name": "gizza-ai/correlated-sample-generator", "version": "0.1.0", "title": "Correlated Sample Generator — Multivariate Normal Data From a Covariance Matrix — gizza.ai", "description": "Generate multivariate-normal sample data from a covariance or correlation matrix, with seeded CSV, TSV, JSON or stats output.", "tags": [ "multivariate normal", "correlated random data", "covariance matrix", "cholesky decomposition", "synthetic data", "correlated sample generator", "mvrnorm", "monte carlo", "statistics" ], "category": "math", "urls": { "page": "https://gizza.ai/tools/correlated-sample-generator/", "markdown": "https://gizza.ai/tools/correlated-sample-generator/index.md", "descriptor": "https://gizza.ai/tools/correlated-sample-generator/tool.json", "deep_link_example": "https://gizza.ai/tools/correlated-sample-generator/?covariance=1%2C%200.8%3B%200.8%2C%201&matrix_kind=covariance&sd=2%2C%203&mean=10%2C%20-4&samples=100&method=cholesky&seed=42&empirical=true&output=csv&decimals=4&labels=height%2C%20weight&header=true&tol=0.00000001" }, "cli": "gizza tool correlated-sample-generator \"1, 0.8; 0.8, 1\"", "tool": { "description": "Generate random samples that follow a multivariate normal distribution with a given mean vector and covariance matrix, so the columns carry the correlations you asked for. Independent standard normals are transformed by a factor A of the matrix (A*A^T = covariance): method='cholesky' uses the classic lower-triangular Cholesky factor and needs a positive-definite matrix, while method='eigen' uses the symmetric square root and also handles positive-semi-definite or singular matrices such as a correlation of exactly 1. The matrix is accepted as newline-, semicolon- or JSON-delimited rows, read as covariances by default or as a correlation matrix plus sd values when matrix_kind='correlation'. mean sets the per-variable means, labels the column names, samples the number of draws. Randomness is a seeded deterministic generator, so the same seed reproduces the same data exactly; empirical=true additionally rescales the draws so the sample mean and covariance match the targets exactly rather than approximately, like R's mvrnorm(empirical=TRUE). output returns csv, tsv, a json document that also reports the achieved mean/covariance/correlation, or a stats-only comparison of target against sample. Symmetry, definiteness and shape are validated with explicit errors. Capped at 50 variables, 100000 draws and 200000 numbers. Runs locally and never uploads anything.", "parameters": { "additionalProperties": false, "properties": { "covariance": { "description": "The square target matrix, one row per variable. Accepts rows separated by newlines or semicolons and entries separated by commas, tabs or spaces, plus JSON: \"1, 0.8; 0.8, 1\" and [[1,0.8],[0.8,1]] are the same 2-variable matrix. It must be symmetric. By default it is read as a COVARIANCE matrix (variances on the diagonal); set matrix_kind to 'correlation' to supply correlations with 1 on the diagonal instead. Three shorthands build a standard correlation structure instead of typing every entry: iid(4) for 4 uncorrelated variables, cs(4, 0.3) for compound symmetry with 0.3 between every pair, and ar1(4, 0.7) for an autoregressive structure where correlation is 0.7^|i-j|. Up to 50 variables.", "type": "string" }, "decimals": { "default": 4, "description": "Digits after the decimal point in the output, 0-12. Default 4.", "maximum": 12, "minimum": 0, "type": "integer" }, "empirical": { "default": false, "description": "When true, rescale the draws so the SAMPLE mean and SAMPLE covariance equal the targets exactly instead of only in expectation (the behaviour of R's mvrnorm with empirical=TRUE). Useful for fixed test data with known statistics; leave false for an honest random sample that shows natural sampling variation. Needs more draws than variables. Default false.", "type": "boolean" }, "header": { "default": true, "description": "Include the column-name row at the top of csv and tsv output. Set false to get bare numbers for a script. Ignored by json and stats. Default true.", "type": "boolean" }, "labels": { "default": "", "description": "Column names, comma-separated, in matrix-row order — for example \"height, weight\". One per variable. Leave empty to use X1, X2, X3 and so on.", "type": "string" }, "matrix_kind": { "default": "covariance", "description": "How to read the matrix. 'covariance' (default) takes variances on the diagonal and covariances off it. 'correlation' takes correlations in -1..1 with 1 on the diagonal, and is combined with sd to build the covariance matrix — use this when you know the correlations and standard deviations rather than covariances.", "enum": [ "covariance", "correlation" ], "type": "string" }, "mean": { "default": "", "description": "The mean of each variable, comma- or space-separated, in the same order as the matrix rows — for example \"10, -4\". Must have one value per variable. Leave empty for a mean of 0 everywhere.", "type": "string" }, "method": { "default": "cholesky", "description": "How the matrix is factorised into A with A*A^T equal to the covariance. 'cholesky' (default) is the classic fast lower-triangular factor and requires a strictly positive-definite matrix. 'eigen' uses the symmetric square root from an eigendecomposition, which is slower but also handles positive-semi-definite and numerically singular matrices such as a correlation of exactly 1 or -1. Both give samples from the same distribution, but different draws for the same seed.", "enum": [ "cholesky", "eigen" ], "type": "string" }, "output": { "default": "csv", "description": "Result format. 'csv' (default) and 'tsv' emit one row per draw with an optional header line. 'json' returns {count, dimensions, labels, method, seed, empirical, target, achieved, samples} including the sample mean/covariance/correlation actually achieved. 'stats' skips the rows and returns only a readable comparison of the target against the sample mean, covariance and correlation — the quickest way to check that a draw came out right.", "enum": [ "csv", "tsv", "json", "stats" ], "type": "string" }, "samples": { "default": 100, "description": "How many draws (rows) to generate, 1-100000. Total output is also capped at 200000 numbers, so 2 variables allow 100000 draws and 4 variables allow 50000. Default 100.", "maximum": 100000, "minimum": 1, "type": "integer" }, "sd": { "default": "", "description": "Standard deviation of each variable, comma-separated, used only when matrix_kind is 'correlation' — for example \"2, 3\" turns correlation 0.5 into covariance 0.5*2*3 = 3. One value per variable; leave empty for a standard deviation of 1 everywhere (which makes the correlation matrix the covariance matrix).", "type": "string" }, "seed": { "default": 42, "description": "Seed for the built-in deterministic generator. The same seed, matrix and settings always return exactly the same draws — change it for a different sample. Default 42.", "minimum": 0, "type": "integer" }, "tol": { "default": 1e-8, "description": "Numerical tolerance, relative to the size of the matrix entries, used for the symmetry check and for how far an eigenvalue may fall below zero before the matrix is rejected as invalid. Raise it if a matrix that is valid in theory is rejected because of rounding in the values you pasted. Default 0.00000001.", "minimum": 0, "type": "number" } }, "required": [ "covariance" ], "type": "object" } } }