Studies#

Manage studies within projects in Ionworks Studio.

For usage examples and guides, see Managing studies on docs.ionworks.com.

Study client for managing studies and their resource assignments.

This module provides the StudyClient for creating, reading, updating, and deleting studies, as well as assigning and removing simulations and measurements from studies.

class ionworks.study.StudyClient(client)[source]#

Bases: object

Client for managing studies within projects.

Studies group related simulations and measurements for comparison and analysis. They belong to a project within an organization.

All methods accept project_id as an optional argument. When omitted, the value falls back to the project_id configured on the parent Ionworks client (resolved from the IONWORKS_PROJECT_ID env var if not passed explicitly). Methods raise ValueError if no project_id is available from any source.

Parameters:

client (Any)

__init__(client)[source]#

Initialize the StudyClient.

Parameters:

client (Any) – The HTTP client instance for making API requests.

Return type:

None

get(study_id, project_id=None)[source]#

Get a specific study by ID.

Parameters:

  • study_id (str) – The ID of the study to retrieve.

  • project_id (str | None, optional) – The ID of the project. Defaults to the project_id set on the Ionworks client.

Returns:

The requested study object.

Return type:

Study

list(project_id=None, limit=None, offset=None, *, name=None, name_exact=None, order_by=None, order=None)[source]#

List studies within a project.

Parameters:

  • project_id (str | None, optional) – The ID of the project to list studies for. Defaults to the project_id set on the Ionworks client.

  • limit (int | None, optional) – Maximum number of studies to return per page.

  • offset (int | None, optional) – Number of studies to skip for pagination.

  • name (str | None, optional) – Case-insensitive substring match on study name.

  • name_exact (str | None, optional) – Exact match on study name.

  • order_by (str | None, optional) – Column to sort by.

  • order (str | None, optional) – Sort direction: "asc" or "desc".

Returns:

A list of study objects (includes simulation_count and validation_count via extra fields).

Return type:

PaginatedList[Study]

create(data=None, project_id=None)[source]#

Create a new study.

Parameters:

  • data (dict[str, Any]) – Dictionary containing the study data. Required fields: name. Optional fields: description.

  • project_id (str | None, optional) – The ID of the project to create the study in. Defaults to the project_id set on the Ionworks client.

Returns:

The newly created study object.

Return type:

Study

update(study_id, data=None, project_id=None)[source]#

Update an existing study.

Parameters:

  • study_id (str) – The ID of the study to update.

  • data (dict[str, Any]) – Dictionary containing the fields to update. Supports name and description.

  • project_id (str | None, optional) – The ID of the project. Defaults to the project_id set on the Ionworks client.

Returns:

The updated study object.

Return type:

Study

delete(study_id, project_id=None)[source]#

Delete a study by ID.

Parameters:

  • study_id (str) – The ID of the study to delete.

  • project_id (str | None, optional) – The ID of the project. Defaults to the project_id set on the Ionworks client.

Return type:

None

assign_simulation(study_id, simulation_id, project_id=None)[source]#

Assign a simulation to a study.

This operation is idempotent – assigning an already-assigned simulation returns the existing mapping.

Parameters:

  • study_id (str) – The ID of the study.

  • simulation_id (str) – The ID of the simulation to assign.

  • project_id (str | None, optional) – The ID of the project. Defaults to the project_id set on the Ionworks client.

Returns:

The study-simulation mapping record.

Return type:

dict[str, Any]

remove_simulation(study_id, simulation_id, project_id=None)[source]#

Remove a simulation from a study.

Parameters:

  • study_id (str) – The ID of the study.

  • simulation_id (str) – The ID of the simulation to remove.

  • project_id (str | None, optional) – The ID of the project. Defaults to the project_id set on the Ionworks client.

Return type:

None

assign_measurement(study_id, measurement_id, project_id=None)[source]#

Assign a measurement to a study.

Parameters:

  • study_id (str) – The ID of the study.

  • measurement_id (str) – The ID of the measurement to assign.

  • project_id (str | None, optional) – The ID of the project. Defaults to the project_id set on the Ionworks client.

Returns:

The study-measurement mapping record.

Return type:

dict[str, Any]

list_measurements(study_id, project_id=None, limit=None, offset=None)[source]#

List measurements assigned to a study with pagination.

Parameters:

  • study_id (str) – The ID of the study.

  • project_id (str | None, optional) – The ID of the project. Defaults to the project_id set on the Ionworks client.

  • limit (int | None, optional) – Maximum number of measurements to return per page.

  • offset (int | None, optional) – Number of measurements to skip for pagination.

Returns:

Paginated response with items, count, and total keys.

Return type:

dict[str, Any]

remove_measurement(study_id, measurement_id, project_id=None)[source]#

Remove a measurement from a study.

Parameters:

  • study_id (str) – The ID of the study.

  • measurement_id (str) – The ID of the measurement to remove.

  • project_id (str | None, optional) – The ID of the project. Defaults to the project_id set on the Ionworks client.

Return type:

None