citrine.resources.table_config module

class citrine.resources.table_config.TableBuildAlgorithm(value)

Bases: BaseEnumeration

The algorithm to use in automatically building a Table Configuration.

  • SINGLE_ROW corresponds one row per material history

  • FORMULATIONS corresponds to one row per ingredient, intermediate, or terminal material, splitting the graph at branches.

FORMULATIONS = 'formulations'
SINGLE_ROW = 'single_row'
class citrine.resources.table_config.TableConfig(name: str, *, description: str, datasets: List[UUID], variables: List[Variable], rows: List[Row], columns: List[Column])

Bases: Resource[TableConfig]

The Table Configuration used to build GEM Tables.

Parameters:

  • name (str) – Name of the Table Configuration

  • description (str) – Description of the Table Configuration

  • datasets (list[UUID]) – Datasets that are in scope for the table, as a list of dataset uuids

  • variables (list[Variable]) – Variable definitions, which define data from the material histories to use in the columns

  • rows (list[Row]) – List of row definitions that define the rows of the table

  • columns (list[Column]) – Column definitions, which describe how the variables are shaped into the table

  • gemd_query (Optional[GemdQuery]) – The query used to define the materials underpinning this table

access_control_dict() → dict

Return an access control entity representation of this resource. Internal use only.

add_all_ingredients(*, process_template: LinkByUID | ProcessTemplate | str | UUID, project, quantity_dimension: IngredientQuantityDimension, scope: str = 'id', unit: str | None = None)

Add variables and columns for all of the possible ingredients in a process.

For each allowed ingredient name in the process template there is a column for the id of the ingredient, id for ingredient labels, and a column for the quantity of the ingredient. If the quantities are given in absolute amounts then there is also a column for units.

Parameters:

  • process_template (Union[LinkByUID, ProcessTemplate, str, UUID]) – representation of a registered process template

  • project (Project) – a project that has access to the process template

  • quantity_dimension (IngredientQuantityDimension) – the dimension in which to report ingredient quantities

  • scope (Optional[str]) – the scope for which to get ingredient ids (default is Citrine scope, ‘id’)

  • unit (Optional[str]) – the units for the quantity, if selecting Absolute Quantity

add_all_ingredients_in_output(*, process_templates: List[LinkByUID], project, quantity_dimension: IngredientQuantityDimension, scope: str = 'id', unit: str | None = None)

Add variables and columns for all possible ingredients in a list of processes.

For each allowed ingredient name in the union of all passed process templates there is a column for the id of the ingredient and a column for the quantity of the ingredient. Columns are filled with the “InOutput” method halting at any of the passed process templates. If the quantities are given in absolute amounts then there is also a column for units.

Parameters:

  • process_templates (List[LinkByUID]) – registered process templates from which to pull allowed ingredients and at which to halt searching

  • project (Project) – a project that has access to the process template

  • quantity_dimension (IngredientQuantityDimension) – the dimension in which to report ingredient quantities

  • scope (Optional[str]) – the scope for which to get ingredient ids (default is Citrine scope, ‘id’)

  • unit (Optional[str]) – the units for the quantity, if selecting Absolute Quantity

add_columns(*, variable: Variable, columns: List[Column], name: str | None = None, description: str | None = None) → TableConfig

Add a variable and one or more columns to this TableConfig (out-of-place).

This method checks that the variable name is not already in use and that the columns only reference that variable. It is not able to check if the columns and the variable are compatible (yet, at least).

Parameters:

  • variable (Variable) – Variable to add and use in the added columns

  • columns (list[Column]) – Columns to add, which must only reference the added variable

  • name (Optional[str]) – Optional renaming of the table

  • description (Optional[str]) – Optional re-description of the table

classmethod build(data: dict) → Self

Build an instance of this object from given data.

dump() → dict

Dump this instance.

columns = None
config_uid = None

Unique ID of the table config, independent of its version.

Type:

Optional[UUID]

datasets = None
description = None
gemd_query = None
name = None
rows = None
property uid: UUID

Unique ID of the table config, independent of its version.

variables = None
version_number = None

The version of the table config, starting from 1. It increases every time the table config is updated.

Type:

Optional[int]

version_uid = None

Unique ID that specifies one version of one table config.

Type:

Optional[UUID]

class citrine.resources.table_config.TableConfigCollection(project_id: UUID, session: Session)

Bases: Collection[TableConfig]

Represents the collection of all Table Configs associated with a project.

build(data: dict) → TableConfig

Build an individual Table Config from a dictionary.

default_for_material(*, material: MaterialRun | LinkByUID | str | UUID, name: str, description: str | None = None, algorithm: TableBuildAlgorithm | None = None) → Tuple[TableConfig, List[Tuple[Variable, Column]]]

Build best-guess default table config for provided terminal material’s history.

Currently generates variables for each templated attribute in the material history in either AttributeByTemplate, or if possible AttributeByTemplateAndObjectTemplate. Attributes on object templates used in the history are included regardless of their presence on data objects in the history. Additionally, each quantity dimension specified on ingredients in the material history will be captured in IngredientQuantityByProcessAndName.

If a generated variable would match ambiguously on the given material history, it is excluded from the generated config and included in the second part of the returned tuple.

Parameters:

  • material (Union[MaterialRun, LinkByUid, str, UUID]) – The terminal material whose history is used to construct a table config.

  • name (str) – The name for the table config.

  • description (str, optional) – The description of the table config. Defaults to autogenerated message.

  • algorithm (TableBuildAlgorithm, optional) – The algorithm to use in generating a Table Configuration from the sample material history. If unspecified, uses the webservice’s default.

Returns:

A table config as well as addition variables/columns which would result in ambiguous matches if included in the config.

Return type:

List[Tuple[Variable, Column]]

delete(uid: UUID | str)

Table configs cannot be deleted at this time.

get(uid: UUID | str, *, version: int | None = None)

Get a table config.

If no version is specified, then the most recent version is returned.

get_for_table(table: GemTable) → TableConfig

Get the TableConfig used to build the given table.

Parameters:

table (GemTable) – Table for which to get the config.

Returns:

The table config used to produce the given table.

Return type:

TableConfig

list(*, per_page: int = 100) → Iterator[ResourceType]

Paginate over the elements of the collection.

Leaving page and per_page as default values will yield all elements in the collection, paginating over all available pages.

Parameters:

per_page (int, optional) – Max number of results to return per page. Default is 100. This parameter is used when making requests to the backend service. If the page parameter is specified it limits the maximum number of elements in the response.

Returns:

An iterator that can be used to loop over all the resources in this collection. Use list() to force evaluation of all results into an in-memory list.

Return type:

Iterator[ResourceType]

preview(*, table_config: TableConfig, preview_materials: List[LinkByUID] | None = None) → dict

Preview a Table Config on an explicit set of terminal materials.

Parameters:

  • table_config (TableConfig) – Table Config to preview

  • preview_materials (List[LinkByUID]) – List of links to the material runs to use as terminal materials in the preview

register(table_config: TableConfig) → TableConfig

Register a Table Config.

If the provided TableConfig does not have a definition_uid, create a new element of the TableConfigCollection by registering the provided TableConfig. If the provided TableConfig does have a uid, update (replace) the TableConfig at that uid with the provided TableConfig.

Parameters:

table_config – The TableConfig to register

Returns:

The registered TableConfig with updated metadata

TODO: Consider validating that a resource exists at the given uid before updating.

The code to do so is not yet implemented on the backend

update(table_config: TableConfig) → TableConfig

Update a Table Config.

If the provided Table Config does have a uid, update (replace) the Table Config at that uid with the provided TableConfig.

Raise a ValueError if the provided Table Config does not have a config_uid.

Parameters:

table_config – The Table Config to updated

Returns:

The updated Table Config with updated metadata