Trial

See also: Builders.

Trial

Domain object wrapping a trial ProjectItemMetadata,with action methods.

Returned by TrialsService.create() or TrialsService.as_trial().

Usage::

trial.run()
status = trial.status()
trial.stop()

The underlying ProjectItemMetadata,is available as trial.item for access to metadata (sid, core_id, snapshot_id, name, …).

Returned by: JinkoClient.create_trial, JinkoClient.create_trial_from_json, JinkoClient.get_trial, JinkoClient.iter_trials, JinkoClient.list_trials, Model.create_trial, SubsamplingDesign.source_trial, Trial.edit_solving_options, Trial.set_solving_times, TrialVisualization.source_trial

Also has every member of ProjectItem.

Member	Kind	Description
model	property	Return the computational model bound to this trial, if any.
data_tables	property	Return the data tables bound to this trial.
vpop	property	Return the virtual population bound to this trial, if any.
protocol_design	property	Return the protocol design bound to this trial, if any.
simple_output_set	property	Return the simple output set bound to this trial, if any.
advanced_output_set	property	Return the advanced output set bound to this trial, if any.
run	method	Start the trial.
stop	method	Stop a running trial.
status	method	Return the current status of this trial snapshot.
sanity	method	Return the pre-launch sanity report for this trial snapshot as a raw dict.
get_solving_times	method	Return base and additional output sampling periods.
get_solving_options	method	Return trial solving options as a raw dictionary.
edit_solving_options	method	Update trial solving options with a complete object or partial dictionary.
set_solving_times	method	Update output sampling periods.
wait_until_completed	method	Poll status until the trial reaches a terminal state or timeout.
run_and_wait_until_completed	method	Start the trial and wait until it reaches a terminal state.
output_ids	method	Return output ids exposed by the trial manager output-ids endpoint.
create_subsampling_design	method	Create a subsampling design from this trial.
create_empty_trial_visualization	method	Create an empty trial visualization bound to this trial.
create_trial_visualization_from_json	method	Create a trial visualization from JSON and bind it to this trial.
descriptors	property	Access typed trial result descriptors derived from results.summary().
results	property	Access trial result helper methods.

model

Type: Model | None

Return the computational model bound to this trial, if any.

data_tables

Type: list['DataTable']

Return the data tables bound to this trial.

vpop

Type: Vpop | None

Return the virtual population bound to this trial, if any.

protocol_design

Type: ProtocolDesign | None

Return the protocol design bound to this trial, if any.

simple_output_set

Type: SimpleOutputSet | None

Return the simple output set bound to this trial, if any.

advanced_output_set

Type: AdvancedOutputSet | None

Return the advanced output set bound to this trial, if any.

run

run() -> None

Start the trial.

stop

stop() -> Any

Stop a running trial.

status

status() -> Any

Return the current status of this trial snapshot.

sanity

sanity() -> Any

Return the pre-launch sanity report for this trial snapshot as a raw dict.

This is the same trial-context validation the Jinkō UI runs before launch, broken down per component (model, protocol, vpop, outputSet for the simple output set, scorings for the advanced output set, dataTables, solvingTimes). Each component exposes sanity.errors/sanity.warnings (an error dict has a code such as ADVANCED_OUTPUTS_ERRORS) and sanity.componentsSanity for per-output diagnostics.

Passing validate_scoring_formula()/standalone advanced-output diagnostics is not sufficient to conclude an advanced output set is compatible with this trial — call sanity() to check that.

Examples:

>>> report = trial.sanity()
>>> report["scorings"]["sanity"]["errors"]
>>> report["scorings"]["sanity"]["componentsSanity"]

get_solving_times

get_solving_times(
    *,
    revision: int | None = None,
    duration_format: Literal["iso8601", "timedelta"] = "iso8601"
) -> tuple[dict[str, timedelta | str], list[dict[str, timedelta | str]]]

Return base and additional output sampling periods.

The returned dictionaries have t_min, t_max, and t_step keys. Values are ISO 8601 strings by default, preserving expressions such as P1W. Set duration_format="timedelta" to convert them using Jinko's fixed year (365.25 days), month (one twelfth of a year), and week (7 day) lengths. Use jinko.iso8601 for these same conversions in custom code.

get_solving_options

get_solving_options(
    *,
    revision: int | None = None,
    duration_format: Literal["iso8601", "timedelta"] = "iso8601"
) -> dict[str, Any]

Return trial solving options as a raw dictionary.

Solving-time durations are ISO 8601 strings by default. Set duration_format="timedelta" to convert them.

edit_solving_options

edit_solving_options(
    solving_options: dict[str, Any], *, version: str | dict | None = None
) -> Trial

Update trial solving options with a complete object or partial dictionary.

solvingTimes accepts timedelta values or ISO 8601 strings. Strings are validated and sent unchanged; timedeltas use fixed day and sub-day units.

set_solving_times

set_solving_times(
    *,
    t_max: timedelta | str,
    t_step: timedelta | str,
    t_min: timedelta | str = timedelta(0),
    additional_periods: Sequence[dict[str, timedelta | str]] = (),
    version: str | dict | None = None
) -> Trial

Update output sampling periods.

t_min, t_max and t_step are the parameters of the mandatory simulation-wide period. Each accepts a timedelta or ISO 8601 string. Timedeltas are emitted with fixed day and sub-day units, so a seven-day timedelta is sent as P7D. ISO 8601 strings are validated and sent unchanged, preserving expressions such as P1W and P1M. Use jinko.iso8601 for these same conversions in custom code.

It must contain every additional period: its t_min must be no greater and its t_max no less than each additional period.

additional_periods optionally add shorter sampling windows and may be in any order. Each period needs a positive t_step and t_min <= t_max. Example: [{"t_min": timedelta(0), "t_max": "P28D", "t_step": "P1D"}]. t_min defaults to timedelta(0), for both the base and additional periods.

wait_until_completed

wait_until_completed(
    *,
    timeout: float | None = None,
    poll_interval: float = 2.0,
    show_progress: bool | None = None
) -> Any

Poll status until the trial reaches a terminal state or timeout.

Progress rendering adapts to the current environment: notebooks use Rich live rendering on stdout, interactive terminals use Rich live rendering on stderr, and non-interactive streams fall back to plain text snapshots when progress output is explicitly enabled.

run_and_wait_until_completed

run_and_wait_until_completed(
    *,
    timeout: float | None = None,
    poll_interval: float = 2.0,
    show_progress: bool | None = None
) -> Any

Start the trial and wait until it reaches a terminal state.

output_ids

output_ids() -> Any

Return output ids exposed by the trial manager output-ids endpoint.

create_subsampling_design

create_subsampling_design(
    *,
    numeric_filters: Sequence[object] = (),
    categorical_filters: Sequence[object] = (),
    marginals: Sequence[object] = (),
    categoricals: Sequence[object] = (),
    correlations: Sequence[object] = (),
    survivals: Sequence[object] = (),
    summary_statistics: Sequence[object] = (),
    observables: Sequence[object] = (),
    folder: Folder | str | None = None,
    name: str | None = None,
    description: str | None = None,
    version: str | dict | None = None
) -> SubsamplingDesign

Create a subsampling design from this trial.

Most users build filters and targets from trial.descriptors and pass them here.

Examples:

>>> descriptors = trial.descriptors
>>> age = descriptors.scalars.get("age", arm="treated")
>>> sex = descriptors.categoricals.get("sex", arm="treated")
>>> auc = descriptors.scalars.get("tumorRadius.auc", arm="treated")
>>> trial.create_subsampling_design(
...     name="adult female responders",
...     numeric_filters=[age.gte(18)],
...     categorical_filters=[sex.in_levels(["female"])],
...     marginals=[auc.normal(mean=12.0, standard_deviation=2.5)],
... )

Parameters:

Name	Type	Description	Default
numeric_filters	Sequence[object]	Numeric conditions such as age.gte(18).	()
categorical_filters	Sequence[object]	Categorical conditions such as sex.in_levels(["female"]).	()
marginals	Sequence[object]	Target distributions for scalar outputs.	()
categoricals	Sequence[object]	Target distributions for categorical outputs.	()
correlations	Sequence[object]	Target relationships between scalar outputs.	()
survivals	Sequence[object]	Target survival curves.	()
summary_statistics	Sequence[object]	Target means and related summary values.	()
observables	Sequence[object]	Extra scalar outputs to keep track of.	()
folder	Folder | str | None	Destination folder.	None
name	str | None	Optional display name.	None
description	str | None	Optional description.	None
version	str | dict | None	Optional version label.	None

These arguments also accept raw dict inputs when you need to bypass the ergonomic builders. observables also accepts bare string ids.

create_empty_trial_visualization

create_empty_trial_visualization(
    *,
    folder: Folder | str | None = None,
    name: str | None = None,
    description: str | None = None,
    version: str | dict | None = None
) -> TrialVisualization

Create an empty trial visualization bound to this trial.

create_trial_visualization_from_json

create_trial_visualization_from_json(
    data: dict[str, Any] | str | Path,
    *,
    folder: Folder | str | None = None,
    name: str | None = None,
    description: str | None = None,
    version: str | dict | None = None
) -> TrialVisualization

Create a trial visualization from JSON and bind it to this trial.

If you're not starting from an existing visualization exported to json, we recommend using create_empty_trial_visualization and using the project item's methods to craft your visualization step-by-step.

descriptors

Type: TrialDescriptors

Access typed trial result descriptors derived from results.summary().

results

Type: TrialResults

Access trial result helper methods.

TabularDownload

Represents tabular result content returned by result_manager endpoints.

Member	Kind	Description
raw_bytes	property	Return the raw downloaded payload bytes.
to_dataframe	method	Parse the payload as CSV (or zipped CSV) into a pandas DataFrame.

raw_bytes

Type: bytes

Return the raw downloaded payload bytes.

to_dataframe

to_dataframe()

Parse the payload as CSV (or zipped CSV) into a pandas DataFrame.

TrialDescriptors

Returned by: Trial.descriptors, TrialDescriptors.refresh

Member	Kind	Description
scalars	attribute
scalars_cross_arm	attribute
categoricals	attribute
categoricals_cross_arm	attribute
arms	property	Return the protocol arms exposed by the trial results summary.
refresh	method	Drop the cached results summary and reload on next access.

scalars

scalars_cross_arm

categoricals

categoricals_cross_arm

arms

Type: tuple[str, ...]

Return the protocol arms exposed by the trial results summary.

refresh

refresh() -> TrialDescriptors

Drop the cached results summary and reload on next access.

ScalarTrialDescriptor

Member	Kind	Description
id	attribute
type	attribute
labels	attribute
group	attribute
arm	attribute
available_arms	attribute
description	attribute
display_name	attribute
unit	attribute
eq	method	Build a numeric equality filter for this scalar descriptor.
neq	method	Build a numeric inequality filter for this scalar descriptor.
lt	method	Build a strict upper-bound filter for this scalar descriptor.
lte	method	Build an upper-bound filter for this scalar descriptor.
gt	method	Build a strict lower-bound filter for this scalar descriptor.
gte	method	Build a lower-bound filter for this scalar descriptor.
group_by_values	method	Group results by the distinct values of this descriptor.
group_by_bin_width	method	Group results into fixed-width bins of width starting at offset.
group_by_bins	method	Group results into count equal-width bins.
group_by_quantiles	method	Group results into count quantile groups.
group_by_breaks	method	Group results at explicit, strictly increasing cut points.
uniform	method	Build a uniform target distribution for this scalar descriptor.
normal	method	Build a normal target distribution for this scalar descriptor.
normal_truncated	method	Build a truncated normal target distribution for this descriptor.
log_normal	method	Build a log-normal target distribution for this scalar descriptor.
weibull	method	Build a Weibull target distribution for this scalar descriptor.
mixture	method	Build a mixture target distribution for this scalar descriptor.
observable	method	Track this scalar descriptor as an extra observable.
summary_statistic	method	Build a summary-statistic target for this scalar descriptor.
survival	method	Build a survival target for this scalar descriptor.
correlate_with	method	Build a correlation target between this descriptor and another scalar.

id

Type: str

type

Type: str

labels

Type: tuple[str, ...]

group

Type: TrialDescriptorGroupName

arm

Type: str | None

available_arms

Type: tuple[str, ...]

description

Type: str | None

display_name

Type: str | None

unit

Type: object | None

eq

eq(value: float, *, is_active: bool = True) -> NumericFilterBuilder

Build a numeric equality filter for this scalar descriptor.

neq

neq(value: float, *, is_active: bool = True) -> NumericFilterBuilder

Build a numeric inequality filter for this scalar descriptor.

lt

lt(value: float, *, is_active: bool = True) -> NumericFilterBuilder

Build a strict upper-bound filter for this scalar descriptor.

lte

lte(value: float, *, is_active: bool = True) -> NumericFilterBuilder

Build an upper-bound filter for this scalar descriptor.

gt

gt(value: float, *, is_active: bool = True) -> NumericFilterBuilder

Build a strict lower-bound filter for this scalar descriptor.

gte

gte(value: float, *, is_active: bool = True) -> NumericFilterBuilder

Build a lower-bound filter for this scalar descriptor.

group_by_values

group_by_values(
    *, reference_arm: ReferenceArmRef | None = None
) -> dict[str, Any]

Group results by the distinct values of this descriptor.

Examples:

>>> trial.results.aggregate_scalars([auc], group_by=[dose.group_by_values()])

group_by_bin_width

group_by_bin_width(
    *, offset: float, width: float, reference_arm: ReferenceArmRef | None = None
) -> dict[str, Any]

Group results into fixed-width bins of width starting at offset.

group_by_bins

group_by_bins(
    count: int, *, reference_arm: ReferenceArmRef | None = None
) -> dict[str, Any]

Group results into count equal-width bins.

group_by_quantiles

group_by_quantiles(
    count: int, *, reference_arm: ReferenceArmRef | None = None
) -> dict[str, Any]

Group results into count quantile groups.

Examples:

>>> auc = trial.descriptors.scalars.get('Tumor.Drug.auc', arm='treated')
>>> trial.results.aggregate_scalars([auc], group_by=[auc.group_by_quantiles(4)])

group_by_breaks

group_by_breaks(
    breaks: Sequence[float], *, reference_arm: ReferenceArmRef | None = None
) -> dict[str, Any]

Group results at explicit, strictly increasing cut points.

uniform

uniform(
    *,
    low_bound: float,
    high_bound: float,
    subject_to: Iterable[SubjectToBuilder] = (),
    is_active: bool = True,
    weight: float | None = None,
    reference: str | None = None
) -> MarginalBuilder

Build a uniform target distribution for this scalar descriptor.

normal

normal(
    *,
    mean: float,
    standard_deviation: float,
    subject_to: Iterable[SubjectToBuilder] = (),
    is_active: bool = True,
    weight: float | None = None,
    reference: str | None = None
) -> MarginalBuilder

Build a normal target distribution for this scalar descriptor.

normal_truncated

normal_truncated(
    *,
    mean: float,
    standard_deviation: float,
    low_bound: float,
    high_bound: float,
    subject_to: Iterable[SubjectToBuilder] = (),
    is_active: bool = True,
    weight: float | None = None,
    reference: str | None = None
) -> MarginalBuilder

Build a truncated normal target distribution for this descriptor.

log_normal

log_normal(
    *,
    mean: float,
    standard_deviation: float,
    base: float,
    subject_to: Iterable[SubjectToBuilder] = (),
    is_active: bool = True,
    weight: float | None = None,
    reference: str | None = None
) -> MarginalBuilder

Build a log-normal target distribution for this scalar descriptor.

weibull

weibull(
    *,
    lambda_: float,
    k: float,
    subject_to: Iterable[SubjectToBuilder] = (),
    is_active: bool = True,
    weight: float | None = None,
    reference: str | None = None
) -> MarginalBuilder

Build a Weibull target distribution for this scalar descriptor.

mixture

mixture(
    components: List[dict[str, object]],
    *,
    subject_to: Iterable[SubjectToBuilder] = (),
    is_active: bool = True,
    reference: str | None = None
) -> MarginalBuilder

Build a mixture target distribution for this scalar descriptor.

Each component must define a weight and either:

• distribution set to another marginal builder for the same descriptor
• or distribution as a distribution name plus params

observable

observable() -> ObservableBuilder

Track this scalar descriptor as an extra observable.

summary_statistic

summary_statistic(
    *,
    mean: float,
    subject_to: Iterable[SubjectToBuilder] = (),
    weight: float = 1.0,
    is_active: bool = True,
    standard_deviation: float | None = None,
    mean_wide_range_low_bound: float | None = None,
    mean_wide_range_high_bound: float | None = None,
    std_wide_range_low_bound: float | None = None,
    std_wide_range_high_bound: float | None = None,
    reference: str | None = None
) -> SummaryStatisticBuilder

Build a summary-statistic target for this scalar descriptor.

survival

survival(
    *,
    time_vals: List[float] | tuple[float, ...] | None = None,
    survival_rates: List[float] | tuple[float, ...] | None = None,
    points: dict[float, float] | Iterable[tuple[float, float]] | None = None,
    subject_to: Iterable[SubjectToBuilder] = (),
    weight: float = 1.0,
    is_active: bool = True,
    time_unit: object | None = None,
    reference: str | None = None
) -> SurvivalBuilder

Build a survival target for this scalar descriptor.

Provide either points or both time_vals and survival_rates.

correlate_with

correlate_with(
    other: TrialDescriptor,
    *,
    correlation_coefficient: float,
    subject_to: Iterable[SubjectToBuilder] = (),
    is_active: bool = True,
    weight: float | None = None,
    reference: str | None = None
) -> CorrelationBuilder

Build a correlation target between this descriptor and another scalar.

CategoricalTrialDescriptor

Member	Kind	Description
id	attribute
type	attribute
labels	attribute
group	attribute
arm	attribute
available_arms	attribute
description	attribute
display_name	attribute
levels	attribute
in_levels	method	Build a categorical filter for the selected levels.
group_by_levels	method	Group results by the levels of this categorical descriptor.
categorical	method	Build a target categorical distribution for this descriptor.

id

Type: str

type

Type: str

labels

Type: tuple[str, ...]

group

Type: TrialDescriptorGroupName

arm

Type: str | None

available_arms

Type: tuple[str, ...]

description

Type: str | None

display_name

Type: str | None

levels

Type: tuple[str, ...]

in_levels

in_levels(
    levels: List[str] | tuple[str, ...], *, is_active: bool = True
) -> CategoricalFilterBuilder

Build a categorical filter for the selected levels.

group_by_levels

group_by_levels(
    *, reference_arm: ReferenceArmRef | None = None
) -> dict[str, Any]

Group results by the levels of this categorical descriptor.

Examples:

>>> sex = trial.descriptors.categoricals.get('sex', arm='identity')
>>> trial.results.aggregate_scalars([auc], group_by=[sex.group_by_levels()])

categorical

categorical(
    category_weights: dict[str, float],
    *,
    subject_to: Iterable[SubjectToBuilder] = (),
    is_active: bool = True,
    weight: float | None = None,
    reference: str | None = None
) -> CategoricalTargetBuilder

Build a target categorical distribution for this descriptor.