{
  "$id": "https://schema.rtemis.org/decompositionmetrics/v1/schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "rtemis DecompositionMetrics",
  "description": "Decomposition metrics: a single-row table of reconstruction quality, component redundancy and effective dimensionality. Which cells are populated follows from the algorithm's traits -- a metric its algorithm cannot support is null -- so every column is declared for every algorithm and every cell is nullable. Unprefixed columns describe the data the decomposition was fitted on; `oos_` columns describe data the fit never saw.",
  "type": "object",
  "properties": {
    "sample": {
      "description": "Sample the metrics describe.",
      "type": ["string", "null"],
      "enum": [
        "Training",
        "Validation",
        "Test",
        "Calibrated Training",
        "Calibrated Validation",
        "Calibrated Test",
        null
      ],
      "readOnly": true,
      "x-rtemis": {
        "type": "string",
        "role": "state"
      }
    },
    "metrics": {
      "description": "Decomposition metrics, one row.",
      "type": ["array", "null"],
      "items": {
        "type": "object",
        "properties": {
          "explained_variance_ratio": {
            "description": "Share of the data's variance the reconstruction accounts for, 1 - ||x - xhat||^2 / ||x - colMeans(x)||^2. The generalization of PCA's cumulative explained variance to any invertible method.",
            "type": ["number", "null"],
            "maximum": 1,
            "x-rtemis": {
              "type": "number"
            }
          },
          "relative_reconstruction_error": {
            "description": "Frobenius norm of the reconstruction residual over that of the data, ||x - xhat|| / ||x||. Scale-free, so it compares across datasets and algorithms.",
            "type": ["number", "null"],
            "minimum": 0,
            "x-rtemis": {
              "type": "number"
            }
          },
          "reconstruction_rmse": {
            "description": "Root mean squared reconstruction error, in the units of the data as it was passed to `decomp()`.",
            "type": ["number", "null"],
            "minimum": 0,
            "x-rtemis": {
              "type": "number"
            }
          },
          "max_abs_component_correlation": {
            "description": "Largest absolute correlation between two distinct components. Approximately 0 for PCA by construction; a high value means the components carry redundant information. NA for a single component.",
            "type": ["number", "null"],
            "minimum": 0,
            "maximum": 1,
            "x-rtemis": {
              "type": "number"
            }
          },
          "effective_dimensionality": {
            "description": "Participation ratio of the component variances, sum(v)^2 / sum(v^2). Lies in [1, k]; a value well below k means some components carry almost no variance and k is larger than the data supports.",
            "type": ["number", "null"],
            "minimum": 1,
            "x-rtemis": {
              "type": "number"
            }
          },
          "oos_explained_variance_ratio": {
            "description": "Explained variance ratio on data the fit never saw.",
            "type": ["number", "null"],
            "maximum": 1,
            "x-rtemis": {
              "type": "number"
            }
          },
          "oos_relative_reconstruction_error": {
            "description": "Relative reconstruction error on data the fit never saw.",
            "type": ["number", "null"],
            "minimum": 0,
            "x-rtemis": {
              "type": "number"
            }
          },
          "reconstruction_gap": {
            "description": "Out-of-sample minus in-sample relative reconstruction error. The overfitting signal: approximately 0 when the decomposition generalizes, positive when it has fitted the training cases.",
            "type": ["number", "null"],
            "x-rtemis": {
              "type": "number"
            }
          }
        },
        "additionalProperties": false,
        "required": ["explained_variance_ratio", "relative_reconstruction_error", "reconstruction_rmse", "max_abs_component_correlation", "effective_dimensionality", "oos_explained_variance_ratio", "oos_relative_reconstruction_error", "reconstruction_gap"]
      },
      "readOnly": true,
      "x-rtemis": {
        "type": "object",
        "role": "state",
        "container": "table"
      }
    }
  },
  "additionalProperties": false,
  "required": ["sample", "metrics"]
}