Advanced output set: advanced output set component handles

AdvancedOutputSetComponentHandle

Base handle for a single advanced output set component.

Subclasses are ConstraintComponent, ScalarComponent, and ObjectiveComponent. You obtain handles from the AdvancedOutputSetComponentsService (sd.components.list(), sd.components.get("my_id"), etc.).

A handle becomes invalidated after delete is called. Any subsequent access will raise DeletedHandleError.

All mutating methods (set_*, update, delete) send a request to the Jinkō platform and refresh the handle's internal state before returning.

Returned by: AdvancedOutputSetComponentHandle.add_link, AdvancedOutputSetComponentHandle.add_tag, AdvancedOutputSetComponentHandle.clear_links, AdvancedOutputSetComponentHandle.refresh, AdvancedOutputSetComponentHandle.remove_link, AdvancedOutputSetComponentHandle.remove_tag, AdvancedOutputSetComponentHandle.set_description, AdvancedOutputSetComponentHandle.set_display_name, AdvancedOutputSetComponentHandle.set_id, AdvancedOutputSetComponentHandle.set_is_active, AdvancedOutputSetComponentHandle.set_links, AdvancedOutputSetComponentHandle.set_tags

Member	Kind	Description
id	property	The user-defined identifier of this component.
immutable_id	property	The platform-assigned immutable identifier, or None if not yet set.
url	property
description	property	Free-text description of this component, or None if not set.
display_name	property	Human-readable label shown in the Jinkō UI, or None if not set.
tags	property
links	property
definition	property	Human-readable one-line rendering of this component's core content.
diagnostics	property	Diagnostics attached to this component in its current cached state.
is_active	property	Whether this component is active and used during scoring.
has_tag	method
has_link	method
refresh	method	Reload this handle's data from the Jinkō platform.
delete	method	Permanently remove this component from the advanced output set.
set_id	method	Rename this component's user-defined id.
set_description	method	Set or clear the description of this component.
set_display_name	method	Set or clear the display name shown in the Jinkō UI.
set_is_active	method	Activate or deactivate this component.
add_tag	method
remove_tag	method
set_tags	method
add_link	method
remove_link	method
set_links	method
clear_links	method

id

Type: str

The user-defined identifier of this component.

This is the id you (or your code) supplied when creating the component. It is mutable via set_id.

immutable_id

Type: str | None

The platform-assigned immutable identifier, or None if not yet set.

Unlike id, this value is assigned by the Jinkō platform and never changes, even if the component is renamed or the advanced output set is versioned. None for components that were just created locally and have not been confirmed by the platform.

url

Type: str

description

Type: str | None

Free-text description of this component, or None if not set.

display_name

Type: str | None

Human-readable label shown in the Jinkō UI, or None if not set.

tags

Type: list['AdvancedOutputSetTag']

links

Type: list[str]

definition

Type: str | None

Human-readable one-line rendering of this component's core content.

The underlying field varies by component kind (a constraint's boolean expression, a scalar's formula, an objective's target and ranges). Returns None for the base handle; typed subclasses override this.

diagnostics

Type: AdvancedOutputSetDiagnostics

Diagnostics attached to this component in its current cached state.

Returns an AdvancedOutputSetDiagnostics view that supports the same filtering and printing as the scoring-design-wide view::

scalar.diagnostics.errors()
print(objective.diagnostics)

The view is built from the handle's last-fetched payload and does not make a network request. Call refresh first if you need the latest server state.

is_active

Type: bool | None

Whether this component is active and used during scoring.

Inactive components are ignored when computing scores. None means the platform default (active) applies.

has_tag

has_tag(tag: str | 'AdvancedOutputSetTag) -> bool

has_link

has_link(link: str | ProjectItem) -> bool

refresh

refresh() -> AdvancedOutputSetComponentHandle

Reload this handle's data from the Jinkō platform.

Call this if you suspect the component was modified externally and you need up-to-date values.

Returns:

• AdvancedOutputSetComponentHandle: self with updated properties.

Raises:

• DeletedHandleError: If this handle has already been deleted.
• NotFoundError: If the component no longer exists on the platform.

delete

delete(*, version: str | dict | None = None) -> None

Permanently remove this component from the advanced output set.

After calling this method the handle is invalidated; any further attribute access will raise DeletedHandleError.

Parameters:

Name	Type	Description	Default
version	str | dict | None	Optional label for the new snapshot created by this deletion (e.g. "remove age constraint"). Can also be a dict with the keys name and description to set a version description.	None

Raises:

• DeletedHandleError: If this handle was already deleted.
• ValidationError: If the component has no immutable id assigned by the platform yet (component cannot be deleted in this state).

set_id

set_id(
    new_id: str, *, version: str | dict | None = None
) -> AdvancedOutputSetComponentHandle

Rename this component's user-defined id.

Parameters:

Name	Type	Description	Default
new_id	str	The new id string (e.g. "eligible_patients").
version	str | dict | None	Optional version name str for the new snapshot. Can also be a dict with the keys name and description to set a version description.	None

Returns:

• AdvancedOutputSetComponentHandle: self with the updated id.

Raises:

• DeletedHandleError: If this handle has been deleted.
• ValidationError: If new_id is already used by another component.

set_description

set_description(
    description: str | None, *, version: str | dict | None = None
) -> AdvancedOutputSetComponentHandle

Set or clear the description of this component.

Parameters:

Name	Type	Description	Default
description	str | None	New description string, or None to remove it.
version	str | dict | None	Optional version name str for the new snapshot. Can also be a dict with the keys name and description to set a version description.	None

Returns:

• AdvancedOutputSetComponentHandle: self with the updated description.

set_display_name

set_display_name(
    display_name: str | None, *, version: str | dict | None = None
) -> AdvancedOutputSetComponentHandle

Set or clear the display name shown in the Jinkō UI.

Parameters:

Name	Type	Description	Default
display_name	str | None	New display name string, or None to remove it.
version	str | dict | None	Optional version name str for the new snapshot. Can also be a dict with the keys name and description to set a version description.	None

Returns:

• AdvancedOutputSetComponentHandle: self with the updated display_name.

set_is_active

set_is_active(
    is_active: bool | None, *, version: str | dict | None = None
) -> AdvancedOutputSetComponentHandle

Activate or deactivate this component.

Deactivated components are excluded from score computation without being deleted.

Parameters:

Name	Type	Description	Default
is_active	bool | None	True to activate, False to deactivate, None to reset to the platform default (active).
version	str | dict | None	Optional version name str for the new snapshot. Can also be a dict with the keys name and description to set a version description.	None

Returns:

• AdvancedOutputSetComponentHandle: self with the updated is_active.

add_tag

add_tag(tag: str | 'AdvancedOutputSetTag, *, version: str | dict | None = None) -> AdvancedOutputSetComponentHandle

remove_tag

remove_tag(tag: str | 'AdvancedOutputSetTag, *, version: str | dict | None = None) -> AdvancedOutputSetComponentHandle

set_tags

set_tags(
    tags: list[str | "AdvancedOutputSetTag"],
    *,
    version: str | dict | None = None
) -> AdvancedOutputSetComponentHandle

add_link

add_link(
    link: str | ProjectItem, *, version: str | dict | None = None
) -> AdvancedOutputSetComponentHandle

remove_link

remove_link(
    link: str | ProjectItem, *, version: str | dict | None = None
) -> AdvancedOutputSetComponentHandle

set_links

set_links(
    links: list[str | ProjectItem], *, version: str | dict | None = None
) -> AdvancedOutputSetComponentHandle

clear_links

clear_links(
    *, version: str | dict | None = None
) -> AdvancedOutputSetComponentHandle

ConstraintComponent

Handle for a constraint component in an advanced output set.

A constraint is a boolean expression evaluated per patient that determines eligibility for scoring (e.g. "age >= 18 and weight < 120").

Obtain instances via AdvancedOutputSetComponentsService.get_constraint or AdvancedOutputSetComponentsService.list_constraints.

Returned by: AdvancedOutputSetComponentsService.add_constraint, AdvancedOutputSetComponentsService.get, AdvancedOutputSetComponentsService.get_by_immutable_id, AdvancedOutputSetComponentsService.get_constraint, AdvancedOutputSetComponentsService.list, AdvancedOutputSetComponentsService.list_constraints, ConstraintComponent.update

Also has every member of AdvancedOutputSetComponentHandle.

Member	Kind	Description
constraint	property	The boolean expression evaluated per patient (e.g. "age >= 18").
filter	property	Optional expression restricting which time points or arms this constraint applies to.
definition	property
update	method	Update one or more fields of this constraint component.

constraint

Type: str | None

The boolean expression evaluated per patient (e.g. "age >= 18").

filter

Type: str | None

Optional expression restricting which time points or arms this constraint applies to.

definition

Type: str | None

update

update(
    *,
    constraint: str | None | UnsetType = UNSET,
    filter: str | None | UnsetType = UNSET,
    description: str | None | UnsetType = UNSET,
    display_name: str | None | UnsetType = UNSET,
    is_active: bool | None | UnsetType = UNSET,
    version: str | dict | None = None
) -> ConstraintComponent

Update one or more fields of this constraint component.

Only the fields you explicitly pass are changed; all others keep their current values (pass None to clear a nullable field).

Parameters:

Name	Type	Description	Default
constraint	str | None | UnsetType	New boolean expression, or None to clear.	UNSET
filter	str | None | UnsetType	New filter expression, or None to clear.	UNSET
description	str | None | UnsetType	New description, or None to clear.	UNSET
display_name	str | None | UnsetType	New display name, or None to clear.	UNSET
is_active	bool | None | UnsetType	True to activate, False to deactivate, None to reset to default.	UNSET
version	str | dict | None	Optional version name str for the new snapshot. Can also be a dict with the keys name and description to set a version description.	None

Returns:

• ConstraintComponent: self with all updated properties.

Raises:

• DeletedHandleError: If this handle has been deleted.
• ValidationError: If the new expression fails server-side validation.

ScalarComponent

Handle for a scalar component in an advanced output set.

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

Obtain instances via AdvancedOutputSetComponentsService.get_scalar or AdvancedOutputSetComponentsService.list_scalars.

Returned by: AdvancedOutputSetComponentsService.add_scalar, AdvancedOutputSetComponentsService.get, AdvancedOutputSetComponentsService.get_by_immutable_id, AdvancedOutputSetComponentsService.get_scalar, AdvancedOutputSetComponentsService.list, AdvancedOutputSetComponentsService.list_scalars, ScalarComponent.update

Also has every member of AdvancedOutputSetComponentHandle.

Member	Kind	Description
formula	property	The numeric expression evaluated per patient (e.g. "AUC_drug").
unit	property	Optional unit string for display purposes (e.g. "mg/L*h").
definition	property
update	method	Update one or more fields of this scalar component.

formula

Type: str | None

The numeric expression evaluated per patient (e.g. "AUC_drug").

unit

Type: str | None

Optional unit string for display purposes (e.g. "mg/L*h").

definition

Type: str | None

update

update(
    *,
    formula: str | None | UnsetType = UNSET,
    unit: str | None | UnsetType = UNSET,
    description: str | None | UnsetType = UNSET,
    display_name: str | None | UnsetType = UNSET,
    is_active: bool | None | UnsetType = UNSET,
    version: str | dict | None = None
) -> ScalarComponent

Update one or more fields of this scalar component.

Only the fields you explicitly pass are changed; all others keep their current values (pass None to clear a nullable field).

Parameters:

Name	Type	Description	Default
formula	str | None | UnsetType	New numeric expression, or None to clear.	UNSET
unit	str | None | UnsetType	New unit string, or None to clear.	UNSET
description	str | None | UnsetType	New description, or None to clear.	UNSET
display_name	str | None | UnsetType	New display name, or None to clear.	UNSET
is_active	bool | None | UnsetType	True to activate, False to deactivate, None to reset to default.	UNSET
version	str | dict | None	Optional version name str for the new snapshot. Can also be a dict with the keys name and description to set a version description.	None

Returns:

• ScalarComponent: self with all updated properties.

Raises:

• DeletedHandleError: If this handle has been deleted.
• ValidationError: If the new formula fails server-side validation.

ObjectiveComponent

Handle for an objective component in an advanced output set.

An objective defines a range-based scoring rule. The Jinkō platform computes a score for each patient by evaluating formula_target and comparing the result against the narrow and wide acceptance ranges. The weight controls how much this objective contributes to the overall population score.

Obtain instances via AdvancedOutputSetComponentsService.get_objective or AdvancedOutputSetComponentsService.list_objectives.

Use AdvancedOutputSet.show_objective_preview to visualise the scoring curve for this objective in a Jupyter notebook.

Returned by: AdvancedOutputSetComponentsService.add_objective, AdvancedOutputSetComponentsService.get, AdvancedOutputSetComponentsService.get_by_immutable_id, AdvancedOutputSetComponentsService.get_objective, AdvancedOutputSetComponentsService.list, AdvancedOutputSetComponentsService.list_objectives, ObjectiveComponent.update

Also has every member of AdvancedOutputSetComponentHandle.

Member	Kind	Description
filter	property	Optional expression restricting which time points or arms this objective applies to.
formula_target	property	Expression string for the target value of this objective, or None.
narrow_range_low_bound	property	Lower bound of the narrow (inner) acceptance range.
narrow_range_high_bound	property	Upper bound of the narrow (inner) acceptance range.
wide_range_low_bound	property	Lower bound of the wide (outer) acceptance range.
wide_range_high_bound	property	Upper bound of the wide (outer) acceptance range.
definition	property
weight	property	Relative weight of this objective in the overall scoring computation.
update	method	Update one or more fields of this objective component.

filter

Type: str | None

Optional expression restricting which time points or arms this objective applies to.

formula_target

Type: str | None

Expression string for the target value of this objective, or None.

The target is the "ideal" value; the scoring curve is centred around it and shaped by the narrow and wide ranges.

narrow_range_low_bound

Type: float

Lower bound of the narrow (inner) acceptance range.

narrow_range_high_bound

Type: float

Upper bound of the narrow (inner) acceptance range.

wide_range_low_bound

Type: float

Lower bound of the wide (outer) acceptance range.

wide_range_high_bound

Type: float

Upper bound of the wide (outer) acceptance range.

definition

Type: str | None

weight

Type: float

Relative weight of this objective in the overall scoring computation.

A higher weight gives this objective more influence on the final score compared to other objectives.

update

update(
    *,
    filter: str | None | UnsetType = UNSET,
    formula_target: str | None | UnsetType = UNSET,
    narrow_range_low_bound: float | UnsetType = UNSET,
    narrow_range_high_bound: float | UnsetType = UNSET,
    wide_range_low_bound: float | UnsetType = UNSET,
    wide_range_high_bound: float | UnsetType = UNSET,
    weight: float | UnsetType = UNSET,
    description: str | None | UnsetType = UNSET,
    display_name: str | None | UnsetType = UNSET,
    is_active: bool | None | UnsetType = UNSET,
    version: str | dict | None = None
) -> ObjectiveComponent

Update one or more fields of this objective component.

Only the fields you explicitly pass are changed; all others keep their current values (pass None to clear a nullable field).

Parameters:

Name	Type	Description	Default
filter	str | None | UnsetType	New filter expression, or None to clear.	UNSET
formula_target	str | None | UnsetType	New target expression, or None to clear.	UNSET
narrow_range_low_bound	float | UnsetType	New lower bound of the narrow range.	UNSET
narrow_range_high_bound	float | UnsetType	New upper bound of the narrow range.	UNSET
wide_range_low_bound	float | UnsetType	New lower bound of the wide range.	UNSET
wide_range_high_bound	float | UnsetType	New upper bound of the wide range.	UNSET
weight	float | UnsetType	New weight (positive float).	UNSET
description	str | None | UnsetType	New description, or None to clear.	UNSET
display_name	str | None | UnsetType	New display name, or None to clear.	UNSET
is_active	bool | None | UnsetType	True to activate, False to deactivate, None to reset to default.	UNSET
version	str | dict | None	Optional version name str for the new snapshot. Can also be a dict with the keys name and description to set a version description.	None

Returns:

• ObjectiveComponent: self with all updated properties.

Raises:

• DeletedHandleError: If this handle has been deleted.
• ValidationError: If the new formula fails server-side validation.