Advanced output set: services

AdvancedOutputSetComponentsService

Manages the components (constraints, scalars, objectives) of an advanced output set.

Do not instantiate directly — access via AdvancedOutputSet.components::

sd = client.advanced_output_sets.get("sd-abc123")
sd.components.list()
sd.components.add_scalar("auc", formula="AUC_drug", unit="mg/L*h")

Returned by: AdvancedOutputSet.components

Member	Kind	Description
list	method
list_constraints	method	Return only the constraint components of this advanced output set.
list_scalars	method	Return only the scalar components of this advanced output set.
list_objectives	method	Return only the objective components of this advanced output set.
get	method	Retrieve a single component by its user-defined id.
get_by_immutable_id	method	Retrieve a single component by its platform-assigned immutable id.
get_constraint	method	Retrieve a constraint component by its user-defined id.
get_scalar	method	Retrieve a scalar component by its user-defined id.
get_objective	method	Retrieve an objective component by its user-defined id.
add_constraint	method	Add a new constraint component to this advanced output set.
add_scalar	method	Add a new scalar component to this advanced output set.
add_objective	method	Add a new objective component to this advanced output set.

list

list(
    *,
    limit: int | None = None,
    tags_all: Sequence[str | "AdvancedOutputSetTag"] | None = None,
    tags_any: Sequence[str | "AdvancedOutputSetTag"] | None = None
) -> List[ConstraintComponent | ScalarComponent | ObjectiveComponent]

list_constraints

list_constraints(
    *,
    limit: int | None = None,
    tags_all: Sequence[str | "AdvancedOutputSetTag"] | None = None,
    tags_any: Sequence[str | "AdvancedOutputSetTag"] | None = None
) -> List[ConstraintComponent]

Return only the constraint components of this advanced output set.

list_scalars

list_scalars(
    *,
    limit: int | None = None,
    tags_all: Sequence[str | "AdvancedOutputSetTag"] | None = None,
    tags_any: Sequence[str | "AdvancedOutputSetTag"] | None = None
) -> List[ScalarComponent]

Return only the scalar components of this advanced output set.

list_objectives

list_objectives(
    *,
    limit: int | None = None,
    tags_all: Sequence[str | "AdvancedOutputSetTag"] | None = None,
    tags_any: Sequence[str | "AdvancedOutputSetTag"] | None = None
) -> List[ObjectiveComponent]

Return only the objective components of this advanced output set.

get

get(
    component_id: str,
) -> ConstraintComponent | ScalarComponent | ObjectiveComponent

Retrieve a single component by its user-defined id.

Parameters:

Name	Type	Description	Default
component_id	str	The id you assigned when creating the component (e.g. "adults").

Returns:

• ConstraintComponent|ScalarComponent|ObjectiveComponent: The matching ConstraintComponent, ScalarComponent, or
• ConstraintComponent|ScalarComponent|ObjectiveComponent: ObjectiveComponent handle.

Raises:

• NotFoundError: If no component with that id exists.

get_by_immutable_id

get_by_immutable_id(
    immutable_id: str,
) -> ConstraintComponent | ScalarComponent | ObjectiveComponent

Retrieve a single component by its platform-assigned immutable id.

Immutable ids are stable across renames and version changes and are available via the immutable_id property on any component handle. Prefer get for everyday use; use this method when you have stored an immutable id for cross-version tracking.

Parameters:

Name	Type	Description	Default
immutable_id	str	The platform-assigned immutable id string.

Returns:

• ConstraintComponent|ScalarComponent|ObjectiveComponent: The matching component handle.

Raises:

• NotFoundError: If no component with that immutable id exists.

get_constraint

get_constraint(component_id: str) -> ConstraintComponent

Retrieve a constraint component by its user-defined id.

Parameters:

Name	Type	Description	Default
component_id	str	The id of the constraint.

Returns:

• ConstraintComponent: class:ConstraintComponent handle.

Raises:

• NotFoundError: If no constraint with that id exists.

get_scalar

get_scalar(component_id: str) -> ScalarComponent

Retrieve a scalar component by its user-defined id.

Parameters:

Name	Type	Description	Default
component_id	str	The id of the scalar.

Returns:

• ScalarComponent: class:ScalarComponent handle.

Raises:

• NotFoundError: If no scalar with that id exists.

get_objective

get_objective(component_id: str) -> ObjectiveComponent

Retrieve an objective component by its user-defined id.

Parameters:

Name	Type	Description	Default
component_id	str	The id of the objective.

Returns:

• ObjectiveComponent: class:ObjectiveComponent handle.

Raises:

• NotFoundError: If no objective with that id exists.

add_constraint

add_constraint(
    component_id: str,
    *,
    constraint: str,
    filter: str | None = None,
    description: str | None = None,
    display_name: str | None = None,
    is_active: bool | None = None,
    tags: Sequence[str | "AdvancedOutputSetTag"] | None = None,
    links: Sequence[str | ProjectItem] | None = None,
    version: str | dict | None = None,
    show_validation: bool | None = None
) -> ConstraintComponent

Add a new constraint component to this advanced output set.

A constraint is a boolean expression that determines which patients are eligible for scoring (e.g. "age >= 18 and weight < 120").

Parameters:

Name	Type	Description	Default
component_id	str	Unique id for the new constraint (e.g. "adults"). Must not conflict with any existing component id.
constraint	str	Boolean expression string evaluated per patient.
filter	str | None	Optional expression to restrict which simulation time points or trial arms this constraint applies to.	None
description	str | None	Optional free-text description shown in the UI.	None
display_name	str | None	Optional human-readable label shown in the UI.	None
is_active	bool | None	Whether this constraint is active. Defaults to True when omitted.	None
version	str | dict | None	Optional label for the new snapshot created by this edit (e.g. "add age constraint"). Can also be a dict with the keys name and description to set a version description.	None
show_validation	bool | None	When True, print a validation report before saving. Defaults to True in Jupyter notebooks.	None

Returns:

• ConstraintComponent: class:ConstraintComponent handle for the newly added constraint.

Raises:

• ValidationError: If the expression fails server-side validation or if component_id is already in use.

add_scalar

add_scalar(
    component_id: str,
    *,
    formula: str,
    unit: str | None = None,
    description: str | None = None,
    display_name: str | None = None,
    is_active: bool | None = None,
    tags: Sequence[str | "AdvancedOutputSetTag"] | None = None,
    links: Sequence[str | ProjectItem] | None = None,
    version: str | dict | None = None,
    show_validation: bool | None = None
) -> ScalarComponent

Add a new scalar component to this advanced output set.

A scalar computes a numeric value from the simulation output for each patient (e.g. "AUC_drug"). Scalars can be referenced as the target of an objective.

Parameters:

Name	Type	Description	Default
component_id	str	Unique id for the new scalar (e.g. "auc"). Must not conflict with any existing component id.
formula	str	Numeric expression string evaluated per patient.
unit	str | None	Optional unit string for display purposes (e.g. "mg/L*h").	None
description	str | None	Optional free-text description shown in the UI.	None
display_name	str | None	Optional human-readable label shown in the UI.	None
is_active	bool | None	Whether this scalar is active. Defaults to True.	None
version	str | dict | None	Optional label for the new snapshot created by this edit. Can also be a dict with the keys name and description to set a version description.	None
show_validation	bool | None	When True, print a validation report before saving. Defaults to True in Jupyter notebooks.	None

Returns:

• ScalarComponent: class:ScalarComponent handle for the newly added scalar.

Raises:

• ValidationError: If the formula fails server-side validation or component_id is already in use.

add_objective

add_objective(
    component_id: str,
    *,
    formula_target: str | None,
    narrow_range_low_bound: float,
    narrow_range_high_bound: float,
    wide_range_low_bound: float,
    wide_range_high_bound: float,
    weight: float,
    filter: str | None = None,
    description: str | None = None,
    display_name: str | None = None,
    is_active: bool | None = None,
    tags: Sequence[str | "AdvancedOutputSetTag"] | None = None,
    links: Sequence[str | ProjectItem] | None = None,
    version: str | dict | None = None,
    show_validation: bool | None = None
) -> ObjectiveComponent

Add a new objective component to this advanced output set.

An objective defines a scoring rule applied to a simulated quantity. The score is determined by how well the quantity falls within the specified narrow and wide ranges around a target.

Parameters:

Name	Type	Description	Default
component_id	str	Unique id for the new objective (e.g. "obj_auc"). Must not conflict with any existing component id.
formula_target	str | None	Expression string for the target value, or None to use the range bounds directly without a central target.
narrow_range_low_bound	float	Lower bound of the narrow (inner) acceptance range.
narrow_range_high_bound	float	Upper bound of the narrow (inner) acceptance range.
wide_range_low_bound	float	Lower bound of the wide (outer) acceptance range. Typically further from the target than the narrow bounds.
wide_range_high_bound	float	Upper bound of the wide (outer) acceptance range.
weight	float	Positive float that controls how much this objective contributes to the overall score relative to other objectives.
filter	str | None	Optional expression to restrict which simulation time points or trial arms this objective applies to.	None
description	str | None	Optional free-text description shown in the UI.	None
display_name	str | None	Optional human-readable label shown in the UI.	None
is_active	bool | None	Whether this objective is active. Defaults to True.	None
version	str | dict | None	Optional label for the new snapshot created by this edit. Can also be a dict with the keys name and description to set a version description.	None
show_validation	bool | None	When True, print a validation report before saving. Defaults to True in Jupyter notebooks.	None

Returns:

• ObjectiveComponent: class:ObjectiveComponent handle for the newly added objective.

Raises:

• ValidationError: If the formula fails server-side validation or component_id is already in use.