Smart Datasets (🧪Beta)

albert.resources.smart_datasets

Attributes:

Name	Type	Description
`SmartDatasetVariable`

SmartDatasetVariable

SmartDatasetVariable = Annotated[
    MaterialAmountVariable
    | ParameterVariable
    | MoleculeVariable
    | PropertyVariable,
    Field(discriminator="type"),
]

SmartDatasetBuildState

Bases: str, Enum

The build state of a smart dataset.

A smart dataset is populated asynchronously; its build state reports where it is in that process. Data can only be retrieved once the state is READY.

Attributes:

Name	Type	Description
`BUILDING`	`str`	The dataset is still being assembled from its scope; data is not yet available.
`READY`	`str`	The dataset has finished building and its experiment data matrix can be retrieved.
`FAILED`	`str`	The build did not complete successfully.

BUILDING

BUILDING = 'building'

READY

READY = 'ready'

FAILED

FAILED = 'failed'

SmartDatasetScope

Bases: BaseAlbertModel

The scope defining which experiment data a smart dataset draws from.

The scope selects the source of the dataset's records: the projects to include, any specific targets, and optionally the worksheets to restrict to. It is the main input supplied when creating or re-scoping a dataset.

Example

from albert.resources.smart_datasets import SmartDatasetScope

scope = SmartDatasetScope(
    project_ids=["PRO123"],
    sheet_ids=["WKS456"],
)

Show JSON schema:

{
  "description": "The scope defining which experiment data a smart dataset draws from.\n\nThe scope selects the source of the dataset's records: the projects to\ninclude, any specific targets, and optionally the worksheets to restrict to.\nIt is the main input supplied when creating or re-scoping a dataset.\n\n!!! example\n    ```python\n    from albert.resources.smart_datasets import SmartDatasetScope\n\n    scope = SmartDatasetScope(\n        project_ids=[\"PRO123\"],\n        sheet_ids=[\"WKS456\"],\n    )\n    ```",
  "properties": {
    "projectIds": {
      "description": "The projects whose experiments feed the dataset.",
      "items": {
        "type": "string"
      },
      "title": "Projectids",
      "type": "array"
    },
    "targetIds": {
      "description": "Specific targets to include.",
      "items": {
        "type": "string"
      },
      "title": "Targetids",
      "type": "array"
    },
    "sheetIds": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The worksheets to restrict to. If None, all worksheets in the selected projects are used.",
      "title": "Sheetids"
    },
    "targetParentIds": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional mapping from target ID to a parent project ID. When set, the target inherits its ACL policy from the referenced project.",
      "title": "Targetparentids"
    }
  },
  "title": "SmartDatasetScope",
  "type": "object"
}

Fields:

project_ids (list[ProjectId])
target_ids (list[TargetId])
sheet_ids (list[WorksheetId] | None)
target_parent_ids (dict[TargetId, ProjectId] | None)

Validators:

filter_invalid_sheet_ids → sheet_ids

project_ids

project_ids: list[ProjectId]

The projects whose experiments feed the dataset.

target_ids

target_ids: list[TargetId]

Specific targets to include.

sheet_ids

sheet_ids: list[WorksheetId] | None = None

The worksheets to restrict to. If None, all worksheets in the selected projects are used.

target_parent_ids

target_parent_ids: dict[TargetId, ProjectId] | None

Optional mapping from target ID to a parent project ID. When set, the target inherits its ACL policy from the referenced project.

filter_invalid_sheet_ids

filter_invalid_sheet_ids(v)

Source code in src/albert/resources/smart_datasets.py

@field_validator("sheet_ids", mode="before")
@classmethod
def filter_invalid_sheet_ids(cls, v):
    if v is None:
        return v
    valid = [sid for sid in v if isinstance(sid, str) and sid.upper().startswith("WKS")]
    return valid or None

SmartDataset

Bases: BaseResource

A smart dataset: a scoped, built matrix of experiment data.

A smart dataset is created from a SmartDatasetScope and built asynchronously by Albert. Its experiment data matrix is retrieved separately (see get_data) rather than being carried on this object.

A SmartDataset and a BTDataset are distinct entities that share an ETL engine (Zeus stored procedures) but are not interchangeable: a SmartDataset is a Smart Projects entity (S3-backed, via storage_key and schema_), while a BTDataset is a Breakthrough pointer record. A SmartDataset is not itself an input to Albert Breakthrough.

Show JSON schema:

{
  "$defs": {
    "AuditFields": {
      "description": "The audit fields for a resource",
      "properties": {
        "by": {
          "default": null,
          "title": "By",
          "type": "string"
        },
        "byName": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Byname"
        },
        "at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "At"
        }
      },
      "title": "AuditFields",
      "type": "object"
    },
    "SmartDatasetBuildState": {
      "description": "The build state of a smart dataset.\n\nA smart dataset is populated asynchronously; its build state reports where it\nis in that process. Data can only be retrieved once the state is ``READY``.\n\nAttributes\n----------\nBUILDING : str\n    The dataset is still being assembled from its scope; data is not yet\n    available.\nREADY : str\n    The dataset has finished building and its experiment data matrix can be\n    retrieved.\nFAILED : str\n    The build did not complete successfully.",
      "enum": [
        "building",
        "ready",
        "failed"
      ],
      "title": "SmartDatasetBuildState",
      "type": "string"
    },
    "SmartDatasetScope": {
      "description": "The scope defining which experiment data a smart dataset draws from.\n\nThe scope selects the source of the dataset's records: the projects to\ninclude, any specific targets, and optionally the worksheets to restrict to.\nIt is the main input supplied when creating or re-scoping a dataset.\n\n!!! example\n    ```python\n    from albert.resources.smart_datasets import SmartDatasetScope\n\n    scope = SmartDatasetScope(\n        project_ids=[\"PRO123\"],\n        sheet_ids=[\"WKS456\"],\n    )\n    ```",
      "properties": {
        "projectIds": {
          "description": "The projects whose experiments feed the dataset.",
          "items": {
            "type": "string"
          },
          "title": "Projectids",
          "type": "array"
        },
        "targetIds": {
          "description": "Specific targets to include.",
          "items": {
            "type": "string"
          },
          "title": "Targetids",
          "type": "array"
        },
        "sheetIds": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The worksheets to restrict to. If None, all worksheets in the selected projects are used.",
          "title": "Sheetids"
        },
        "targetParentIds": {
          "anyOf": [
            {
              "additionalProperties": {
                "type": "string"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional mapping from target ID to a parent project ID. When set, the target inherits its ACL policy from the referenced project.",
          "title": "Targetparentids"
        }
      },
      "title": "SmartDatasetScope",
      "type": "object"
    },
    "Status": {
      "description": "The status of a resource.\n\nAttributes\n----------\nACTIVE : str\n    The resource is fully operational and visible in normal operations.\nINACTIVE : str\n    The resource is hidden from normal operations and disabled from use.",
      "enum": [
        "active",
        "inactive"
      ],
      "title": "Status",
      "type": "string"
    }
  },
  "description": "A smart dataset: a scoped, built matrix of experiment data.\n\nA smart dataset is created from a [`SmartDatasetScope`][albert.resources.smart_datasets.SmartDatasetScope] and built\nasynchronously by Albert. Its experiment data matrix is retrieved separately\n(see\n[`get_data`][albert.collections.smart_datasets.SmartDatasetCollection.get_data])\nrather than being carried on this object.\n\nA ``SmartDataset`` and a [`BTDataset`][albert.resources.btdataset.BTDataset] are\ndistinct entities that share an ETL engine (Zeus stored procedures) but are not\ninterchangeable: a ``SmartDataset`` is a Smart Projects entity (S3-backed, via\n``storage_key`` and ``schema_``), while a ``BTDataset`` is a Breakthrough\npointer record. A SmartDataset is not itself an input to Albert Breakthrough.",
  "properties": {
    "status": {
      "anyOf": [
        {
          "$ref": "#/$defs/Status"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The status of the resource, optional."
    },
    "Created": {
      "anyOf": [
        {
          "$ref": "#/$defs/AuditFields"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Audit fields for the creation of the resource, optional."
    },
    "Updated": {
      "anyOf": [
        {
          "$ref": "#/$defs/AuditFields"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Audit fields for the update of the resource, optional."
    },
    "type": {
      "const": "smart",
      "default": "smart",
      "title": "Type",
      "type": "string"
    },
    "id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The unique identifier of the smart dataset (format ``SDT...``).",
      "title": "Id"
    },
    "parentId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The ID of the parent project this smart dataset belongs to. When set, the smart dataset inherits its ACL policy from the referenced project.",
      "title": "Parentid"
    },
    "buildState": {
      "anyOf": [
        {
          "$ref": "#/$defs/SmartDatasetBuildState"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Where the dataset is in its build lifecycle. Data is available once this is ``ready``."
    },
    "scope": {
      "anyOf": [
        {
          "$ref": "#/$defs/SmartDatasetScope"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The scope defining which projects, targets, and worksheets the dataset draws its experiment data from."
    },
    "schema": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Serialized dataset schema (from the dataset's ``get_schema()``): variable metadata for the experiments/mixtures/inventory tables.",
      "title": "Schema"
    },
    "storageKey": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "S3 key for the built dataset JSON.",
      "title": "Storagekey"
    }
  },
  "title": "SmartDataset",
  "type": "object"
}

Fields:

status (Status | None)
created (AuditFields | None)
updated (AuditFields | None)
type (Literal['smart'])
id (SmartDatasetId | None)
parent_id (ProjectId | None)
build_state (SmartDatasetBuildState | None)
scope (SmartDatasetScope | None)
schema_ (dict | None)
storage_key (str | None)

type

type: Literal['smart'] = 'smart'

id

id: SmartDatasetId | None = None

The unique identifier of the smart dataset (format SDT...).

parent_id

parent_id: ProjectId | None = None

The ID of the parent project this smart dataset belongs to. When set, the smart dataset inherits its ACL policy from the referenced project.

build_state

build_state: SmartDatasetBuildState | None = None

Where the dataset is in its build lifecycle. Data is available once this is ready.

scope

scope: SmartDatasetScope | None = None

The scope defining which projects, targets, and worksheets the dataset draws its experiment data from.

schema_

schema_: dict | None = None

Serialized dataset schema (from the dataset's get_schema()): variable metadata for the experiments/mixtures/inventory tables.

storage_key

storage_key: str | None = None

S3 key for the built dataset JSON.

SmartDatasetAggregateBy

Bases: str, Enum

The aggregation level for smart dataset experiment data.

Controls what each row (record) in the returned matrix represents, from the coarsest (one row per inventory item) to the finest (one row per measurement).

Attributes:

Name	Type	Description
`INV`	`str`	Aggregate to one record per inventory item.
`LOT`	`str`	Aggregate to one record per lot.
`WFL`	`str`	Aggregate to one record per workflow (experiment).
`PTD`	`str`	Finest granularity: one record per measurement (API value `measurement`); record identifiers at this level include `property_data_id`.

Methods:

Name	Description
`to_api_value`
`from_api_value`

INV

INV = 'inv'

LOT

LOT = 'lot'

WFL

WFL = 'wfl'

PTD

PTD = 'ptd'

to_api_value

to_api_value() -> str

Source code in src/albert/resources/smart_datasets.py

def to_api_value(self) -> str:
    return {
        SmartDatasetAggregateBy.INV: "inventory",
        SmartDatasetAggregateBy.LOT: "lot",
        SmartDatasetAggregateBy.WFL: "workflow",
        SmartDatasetAggregateBy.PTD: "measurement",
    }[self.value]

from_api_value

from_api_value(value: str) -> SmartDatasetAggregateBy

Source code in src/albert/resources/smart_datasets.py

@staticmethod
def from_api_value(value: str) -> "SmartDatasetAggregateBy":
    return {
        "inventory": SmartDatasetAggregateBy.INV,
        "lot": SmartDatasetAggregateBy.LOT,
        "workflow": SmartDatasetAggregateBy.WFL,
        "measurement": SmartDatasetAggregateBy.PTD,
    }[value]

SmartDatasetVariableDataType

Bases: str, Enum

The data type of a smart dataset variable (column).

Attributes:

Name	Type	Description
`NUMERIC`	`str`	Continuous or discrete numeric values.
`CATEGORICAL`	`str`	Discrete, unordered category labels.
`MOLECULAR`	`str`	Molecular structure values (e.g. a molecule column).
`BOOLEAN`	`str`	True/false values.

NUMERIC

NUMERIC = 'numeric'

CATEGORICAL

CATEGORICAL = 'categorical'

MOLECULAR

MOLECULAR = 'molecular'

BOOLEAN

BOOLEAN = 'boolean'

SmartDatasetRecordIdentifier

Bases: BaseAlbertModel

An identifier for a record in a smart dataset experiment data matrix.

The same shape is used across all aggregation levels (inventory, material, experiment, measurement); fields that don't apply at a given level are left unset.

Show JSON schema:

{
  "description": "An identifier for a record in a smart dataset experiment data matrix.\n\nThe same shape is used across all aggregation levels (inventory, material,\nexperiment, measurement); fields that don't apply at a given level are left\nunset.",
  "properties": {
    "type": {
      "description": "The identifier type (e.g., ``albert_inventory``, ``albert_material``).",
      "title": "Type",
      "type": "string"
    },
    "inventory_id": {
      "description": "The inventory ID of the record.",
      "title": "Inventory Id",
      "type": "string"
    },
    "key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The unique key of the identifier.",
      "title": "Key"
    },
    "lot_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The lot ID, if applicable.",
      "title": "Lot Id"
    },
    "workflow_interval": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The workflow interval, if applicable.",
      "title": "Workflow Interval"
    },
    "task_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The task ID, if applicable.",
      "title": "Task Id"
    },
    "property_data_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The property data ID, if applicable.",
      "title": "Property Data Id"
    }
  },
  "required": [
    "type",
    "inventory_id"
  ],
  "title": "SmartDatasetRecordIdentifier",
  "type": "object"
}

Fields:

type (str)
inventory_id (str)
key (str | None)
lot_id (str | None)
workflow_interval (str | None)
task_id (str | None)
property_data_id (str | None)

type

type: str

The identifier type (e.g., albert_inventory, albert_material).

inventory_id

inventory_id: str

The inventory ID of the record.

key

key: str | None = None

The unique key of the identifier.

lot_id

lot_id: str | None = None

The lot ID, if applicable.

workflow_interval

workflow_interval: str | None = None

The workflow interval, if applicable.

task_id

task_id: str | None = None

The task ID, if applicable.

property_data_id

property_data_id: str | None = None

The property data ID, if applicable.

MaterialAmountVariable

Bases: _BaseVariable

A dataset column for the amount of a material used in an experiment.

Show JSON schema:

{
  "description": "A dataset column for the amount of a material used in an experiment.",
  "properties": {
    "key": {
      "title": "Key",
      "type": "string"
    },
    "name": {
      "title": "Name",
      "type": "string"
    },
    "type": {
      "const": "material_amount",
      "default": "material_amount",
      "description": "The variable type discriminator; always ``material_amount``.",
      "title": "Type",
      "type": "string"
    },
    "data_type": {
      "const": "numeric",
      "default": "numeric",
      "description": "The value type; always ``NUMERIC`` for material amounts.",
      "title": "Data Type",
      "type": "string"
    }
  },
  "required": [
    "key",
    "name"
  ],
  "title": "MaterialAmountVariable",
  "type": "object"
}

Fields:

key (str)
name (str)
type (Literal['material_amount'])
data_type (Literal[NUMERIC])

type

type: Literal['material_amount'] = 'material_amount'

The variable type discriminator; always material_amount.

data_type

data_type: Literal[NUMERIC] = (
    SmartDatasetVariableDataType.NUMERIC
)

The value type; always NUMERIC for material amounts.

ParameterVariable

Bases: _BaseVariable

A dataset column for an experiment parameter.

Show JSON schema:

{
  "$defs": {
    "SmartDatasetVariableDataType": {
      "description": "The data type of a smart dataset variable (column).\n\nAttributes\n----------\nNUMERIC : str\n    Continuous or discrete numeric values.\nCATEGORICAL : str\n    Discrete, unordered category labels.\nMOLECULAR : str\n    Molecular structure values (e.g. a molecule column).\nBOOLEAN : str\n    True/false values.",
      "enum": [
        "numeric",
        "categorical",
        "molecular",
        "boolean"
      ],
      "title": "SmartDatasetVariableDataType",
      "type": "string"
    }
  },
  "description": "A dataset column for an experiment parameter.",
  "properties": {
    "key": {
      "title": "Key",
      "type": "string"
    },
    "name": {
      "title": "Name",
      "type": "string"
    },
    "type": {
      "const": "parameter",
      "default": "parameter",
      "description": "The variable type discriminator; always ``parameter``.",
      "title": "Type",
      "type": "string"
    },
    "data_type": {
      "$ref": "#/$defs/SmartDatasetVariableDataType",
      "description": "The value type of the parameter."
    },
    "sources": {
      "description": "Which RET48 origins contributed the parameter values: ``\"property\"``, ``\"batch\"``, or ``\"process_design\"`` (overlaps resolved by the ETL, with batch taking precedence over process-design).",
      "items": {
        "enum": [
          "property",
          "batch",
          "process_design"
        ],
        "type": "string"
      },
      "title": "Sources",
      "type": "array"
    }
  },
  "required": [
    "key",
    "name",
    "data_type"
  ],
  "title": "ParameterVariable",
  "type": "object"
}

Fields:

key (str)
name (str)
type (Literal['parameter'])
data_type (SmartDatasetVariableDataType)
sources (list[Literal['property', 'batch', 'process_design']])

type

type: Literal['parameter'] = 'parameter'

The variable type discriminator; always parameter.

data_type

data_type: SmartDatasetVariableDataType

The value type of the parameter.

sources

sources: list[
    Literal["property", "batch", "process_design"]
]

Which RET48 origins contributed the parameter values: "property", "batch", or "process_design" (overlaps resolved by the ETL, with batch taking precedence over process-design).

MoleculeVariable

Bases: _BaseVariable

A dataset column for a molecular structure.

Show JSON schema:

{
  "description": "A dataset column for a molecular structure.",
  "properties": {
    "key": {
      "title": "Key",
      "type": "string"
    },
    "name": {
      "title": "Name",
      "type": "string"
    },
    "type": {
      "const": "molecule",
      "default": "molecule",
      "description": "The variable type discriminator; always ``molecule``.",
      "title": "Type",
      "type": "string"
    },
    "data_type": {
      "const": "molecular",
      "default": "molecular",
      "description": "The value type; always ``MOLECULAR`` for molecule variables.",
      "title": "Data Type",
      "type": "string"
    }
  },
  "required": [
    "key",
    "name"
  ],
  "title": "MoleculeVariable",
  "type": "object"
}

Fields:

key (str)
name (str)
type (Literal['molecule'])
data_type (Literal[MOLECULAR])

type

type: Literal['molecule'] = 'molecule'

The variable type discriminator; always molecule.

data_type

data_type: Literal[MOLECULAR] = (
    SmartDatasetVariableDataType.MOLECULAR
)

The value type; always MOLECULAR for molecule variables.

PropertyVariable

Bases: _BaseVariable

A dataset column for a measured property.

Show JSON schema:

{
  "$defs": {
    "SmartDatasetVariableDataType": {
      "description": "The data type of a smart dataset variable (column).\n\nAttributes\n----------\nNUMERIC : str\n    Continuous or discrete numeric values.\nCATEGORICAL : str\n    Discrete, unordered category labels.\nMOLECULAR : str\n    Molecular structure values (e.g. a molecule column).\nBOOLEAN : str\n    True/false values.",
      "enum": [
        "numeric",
        "categorical",
        "molecular",
        "boolean"
      ],
      "title": "SmartDatasetVariableDataType",
      "type": "string"
    }
  },
  "description": "A dataset column for a measured property.",
  "properties": {
    "key": {
      "title": "Key",
      "type": "string"
    },
    "name": {
      "title": "Name",
      "type": "string"
    },
    "type": {
      "const": "property",
      "default": "property",
      "description": "The variable type discriminator; always ``property``.",
      "title": "Type",
      "type": "string"
    },
    "data_type": {
      "$ref": "#/$defs/SmartDatasetVariableDataType",
      "description": "The value type of the measured property."
    }
  },
  "required": [
    "key",
    "name",
    "data_type"
  ],
  "title": "PropertyVariable",
  "type": "object"
}

Fields:

key (str)
name (str)
type (Literal['property'])
data_type (SmartDatasetVariableDataType)

type

type: Literal['property'] = 'property'

The variable type discriminator; always property.

data_type

data_type: SmartDatasetVariableDataType

The value type of the measured property.

SmartDatasetData

Bases: BaseAlbertModel

The built experiment data matrix for a smart dataset.

Rows are records (experiments, materials, lots, or measurements, depending on aggregate_by) and columns are variables (material amounts, parameters, molecules, and measured properties). identifiers describes each row and variables describes each column, aligned with data.

Show JSON schema:

{
  "$defs": {
    "MaterialAmountVariable": {
      "description": "A dataset column for the amount of a material used in an experiment.",
      "properties": {
        "key": {
          "title": "Key",
          "type": "string"
        },
        "name": {
          "title": "Name",
          "type": "string"
        },
        "type": {
          "const": "material_amount",
          "default": "material_amount",
          "description": "The variable type discriminator; always ``material_amount``.",
          "title": "Type",
          "type": "string"
        },
        "data_type": {
          "const": "numeric",
          "default": "numeric",
          "description": "The value type; always ``NUMERIC`` for material amounts.",
          "title": "Data Type",
          "type": "string"
        }
      },
      "required": [
        "key",
        "name"
      ],
      "title": "MaterialAmountVariable",
      "type": "object"
    },
    "MoleculeVariable": {
      "description": "A dataset column for a molecular structure.",
      "properties": {
        "key": {
          "title": "Key",
          "type": "string"
        },
        "name": {
          "title": "Name",
          "type": "string"
        },
        "type": {
          "const": "molecule",
          "default": "molecule",
          "description": "The variable type discriminator; always ``molecule``.",
          "title": "Type",
          "type": "string"
        },
        "data_type": {
          "const": "molecular",
          "default": "molecular",
          "description": "The value type; always ``MOLECULAR`` for molecule variables.",
          "title": "Data Type",
          "type": "string"
        }
      },
      "required": [
        "key",
        "name"
      ],
      "title": "MoleculeVariable",
      "type": "object"
    },
    "ParameterVariable": {
      "description": "A dataset column for an experiment parameter.",
      "properties": {
        "key": {
          "title": "Key",
          "type": "string"
        },
        "name": {
          "title": "Name",
          "type": "string"
        },
        "type": {
          "const": "parameter",
          "default": "parameter",
          "description": "The variable type discriminator; always ``parameter``.",
          "title": "Type",
          "type": "string"
        },
        "data_type": {
          "$ref": "#/$defs/SmartDatasetVariableDataType",
          "description": "The value type of the parameter."
        },
        "sources": {
          "description": "Which RET48 origins contributed the parameter values: ``\"property\"``, ``\"batch\"``, or ``\"process_design\"`` (overlaps resolved by the ETL, with batch taking precedence over process-design).",
          "items": {
            "enum": [
              "property",
              "batch",
              "process_design"
            ],
            "type": "string"
          },
          "title": "Sources",
          "type": "array"
        }
      },
      "required": [
        "key",
        "name",
        "data_type"
      ],
      "title": "ParameterVariable",
      "type": "object"
    },
    "PropertyVariable": {
      "description": "A dataset column for a measured property.",
      "properties": {
        "key": {
          "title": "Key",
          "type": "string"
        },
        "name": {
          "title": "Name",
          "type": "string"
        },
        "type": {
          "const": "property",
          "default": "property",
          "description": "The variable type discriminator; always ``property``.",
          "title": "Type",
          "type": "string"
        },
        "data_type": {
          "$ref": "#/$defs/SmartDatasetVariableDataType",
          "description": "The value type of the measured property."
        }
      },
      "required": [
        "key",
        "name",
        "data_type"
      ],
      "title": "PropertyVariable",
      "type": "object"
    },
    "SmartDatasetAggregateBy": {
      "description": "The aggregation level for smart dataset experiment data.\n\nControls what each row (record) in the returned matrix represents, from the\ncoarsest (one row per inventory item) to the finest (one row per measurement).\n\nAttributes\n----------\nINV : str\n    Aggregate to one record per inventory item.\nLOT : str\n    Aggregate to one record per lot.\nWFL : str\n    Aggregate to one record per workflow (experiment).\nPTD : str\n    Finest granularity: one record per measurement (API value ``measurement``);\n    record identifiers at this level include ``property_data_id``.",
      "enum": [
        "inv",
        "lot",
        "wfl",
        "ptd"
      ],
      "title": "SmartDatasetAggregateBy",
      "type": "string"
    },
    "SmartDatasetRecordIdentifier": {
      "description": "An identifier for a record in a smart dataset experiment data matrix.\n\nThe same shape is used across all aggregation levels (inventory, material,\nexperiment, measurement); fields that don't apply at a given level are left\nunset.",
      "properties": {
        "type": {
          "description": "The identifier type (e.g., ``albert_inventory``, ``albert_material``).",
          "title": "Type",
          "type": "string"
        },
        "inventory_id": {
          "description": "The inventory ID of the record.",
          "title": "Inventory Id",
          "type": "string"
        },
        "key": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The unique key of the identifier.",
          "title": "Key"
        },
        "lot_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The lot ID, if applicable.",
          "title": "Lot Id"
        },
        "workflow_interval": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The workflow interval, if applicable.",
          "title": "Workflow Interval"
        },
        "task_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The task ID, if applicable.",
          "title": "Task Id"
        },
        "property_data_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "The property data ID, if applicable.",
          "title": "Property Data Id"
        }
      },
      "required": [
        "type",
        "inventory_id"
      ],
      "title": "SmartDatasetRecordIdentifier",
      "type": "object"
    },
    "SmartDatasetVariableDataType": {
      "description": "The data type of a smart dataset variable (column).\n\nAttributes\n----------\nNUMERIC : str\n    Continuous or discrete numeric values.\nCATEGORICAL : str\n    Discrete, unordered category labels.\nMOLECULAR : str\n    Molecular structure values (e.g. a molecule column).\nBOOLEAN : str\n    True/false values.",
      "enum": [
        "numeric",
        "categorical",
        "molecular",
        "boolean"
      ],
      "title": "SmartDatasetVariableDataType",
      "type": "string"
    }
  },
  "description": "The built experiment data matrix for a smart dataset.\n\nRows are records (experiments, materials, lots, or measurements, depending on\n``aggregate_by``) and columns are variables (material amounts, parameters,\nmolecules, and measured properties). ``identifiers`` describes each row and\n``variables`` describes each column, aligned with ``data``.",
  "properties": {
    "aggregate_by": {
      "$ref": "#/$defs/SmartDatasetAggregateBy",
      "description": "The aggregation level of the returned rows."
    },
    "identifiers": {
      "description": "The identifier metadata for each row, aligned with the rows of ``data``.",
      "items": {
        "$ref": "#/$defs/SmartDatasetRecordIdentifier"
      },
      "title": "Identifiers",
      "type": "array"
    },
    "variables": {
      "description": "The variable metadata for each column, aligned with the columns of ``data``.",
      "items": {
        "discriminator": {
          "mapping": {
            "material_amount": "#/$defs/MaterialAmountVariable",
            "molecule": "#/$defs/MoleculeVariable",
            "parameter": "#/$defs/ParameterVariable",
            "property": "#/$defs/PropertyVariable"
          },
          "propertyName": "type"
        },
        "oneOf": [
          {
            "$ref": "#/$defs/MaterialAmountVariable"
          },
          {
            "$ref": "#/$defs/ParameterVariable"
          },
          {
            "$ref": "#/$defs/MoleculeVariable"
          },
          {
            "$ref": "#/$defs/PropertyVariable"
          }
        ]
      },
      "title": "Variables",
      "type": "array"
    },
    "data": {
      "description": "The experiment data values as a record-by-variable matrix.",
      "title": "Data",
      "type": "object"
    },
    "uncertainty": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The associated uncertainty values, if available.",
      "title": "Uncertainty"
    },
    "counts": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The associated observation counts, if available.",
      "title": "Counts"
    }
  },
  "required": [
    "aggregate_by",
    "data"
  ],
  "title": "SmartDatasetData",
  "type": "object"
}

Fields:

aggregate_by (SmartDatasetAggregateBy)
identifiers (list[SmartDatasetRecordIdentifier])
variables (list[SmartDatasetVariable])
data (OrientTightDataFrame)
uncertainty (OrientTightDataFrame | None)
counts (OrientTightDataFrame | None)

aggregate_by

aggregate_by: SmartDatasetAggregateBy

The aggregation level of the returned rows.

identifiers

identifiers: list[SmartDatasetRecordIdentifier]

The identifier metadata for each row, aligned with the rows of data.

variables

variables: list[SmartDatasetVariable]

The variable metadata for each column, aligned with the columns of data.

data

data: OrientTightDataFrame

The experiment data values as a record-by-variable matrix.

uncertainty

uncertainty: OrientTightDataFrame | None = None

The associated uncertainty values, if available.

counts

counts: OrientTightDataFrame | None = None

The associated observation counts, if available.