SampleOperations

Access via client.samples.

crucible.resources.samples.SampleOperations

Sample-related API operations.

Access via: client.samples.get(), client.samples.list(), etc.

get(sample_id, include_links=False, include_metadata=False)

Get sample information by ID.

Parameters:

Name	Type	Description	Default
sample_id	str	Sample unique identifier	required
include_links	bool	Whether to include immediate parent/child/associated links	False
include_metadata	bool	Whether to include scientific metadata	False

Returns:

Name	Type	Description
Dict	Dict	Sample information with optional links and metadata

list(dataset_id=None, parent_id=None, include_metadata=False, include_links=False, limit=DEFAULT_LIMIT, offset=0, **kwargs)

List samples with optional filtering and automatic pagination.

Parameters:

Name	Type	Description	Default
dataset_id	str	Get samples from specific dataset	None
parent_id	str	Get child samples from parent (deprecated)	None
include_metadata	bool	Include scientific metadata in results	False
include_links	bool	Include linked resources (parents, children, associated) per sample	False
limit	int	Maximum total results to return (default: 100). Requests above API_PAGE_MAX (1000) are handled transparently via parallel pagination.	DEFAULT_LIMIT
offset	int	Starting position in the full result set (default: 0)	0
**kwargs		Query parameters for filtering samples	{}

Returns:

Type	Description
List[Dict]	List[Dict]: Sample information

create(unique_id=None, sample_name=None, description=None, timestamp=None, owner_orcid=None, project_id=None, sample_type=None, public=None, parents=[], children=[], scientific_metadata=None, date_created=None, creation_date=None, owner_id=None, owner_user_id=None)

Add a new sample with optional parent-child relationships.

Parameters:

Name	Type	Description	Default
sample_name	str	Human-readable sample name	None
sample_type	str	Category of sample (for filtering)	None
description	str	Sample description	None
timestamp	str	User-defined timestamp	None
owner_orcid	str	Owner's ORCID	None
project_id	str	Project ID	None
public	bool	Whether the sample is publicly visible	None
parents	List[Dict]	Parent samples	[]
children	List[Dict]	Child samples	[]
scientific_metadata	Dict	Scientific metadata to attach after creation	None

Returns:

Name	Type	Description
Dict	Dict	Created sample object

Raises:

Type	Description
Exception	If neither unique_id nor sample_name is provided

update(unique_id, sample_name=None, description=None, timestamp=None, owner_orcid=None, project_id=None, sample_type=None, public=None, parents=[], children=[], date_created=None, creation_date=None, owner_id=None, owner_user_id=None)

Update an existing sample.

Parameters:

Name	Type	Description	Default
unique_id	str	Sample unique identifier (required)	required
sample_name	str	Human-readable sample name	None
sample_type	str	Category of sample (for filtering)	None
description	str	Sample description	None
timestamp	str	User-defined timestamp	None
owner_orcid	str	Owner's ORCID	None
public	bool	Whether the sample is publicly visible	None
project_id	str	Project ID	None
parents	List[Dict]	Parent samples to link	[]
children	List[Dict]	Child samples to link	[]

Returns:

Name	Type	Description
Dict	Dict	Updated sample object

add_dataset(sample_id, dataset_id)

Link a dataset to this sample.

Delegates to DatasetOperations.add_sample — single implementation.

Parameters:

Name	Type	Description	Default
sample_id	str	Sample unique identifier	required
dataset_id	str	Dataset unique identifier	required

Returns:

Name	Type	Description
Dict	Dict	Information about the created link

remove_dataset(sample_id, dataset_id)

Remove the link between a sample and a dataset.

Requires admin permissions.

Parameters:

Name	Type	Description	Default
sample_id	str	Sample unique identifier	required
dataset_id	str	Dataset unique identifier	required

Returns:

Name	Type	Description
Dict	Dict	Deletion confirmation

link(parent_id, child_id)

Link two samples with a parent-child relationship.

Parameters:

Name	Type	Description	Default
parent_id	str	Unique sample identifier of parent sample	required
child_id	str	Unique sample identifier of child sample	required

Returns:

Name	Type	Description
Dict	Dict	Created link object

remove_child(parent_id, child_id)

Remove the parent-child link between two samples.

Parameters:

Name	Type	Description	Default
parent_id	str	Unique sample identifier of parent sample	required
child_id	str	Unique sample identifier of child sample	required

Returns:

Name	Type	Description
Dict	Dict	Deletion confirmation

list_parents(sample_id, limit=DEFAULT_LIMIT, offset=0, **kwargs)

List the parents of a given sample with optional filtering.

Parameters:

Name	Type	Description	Default
sample_id	str	The unique ID of the sample for which you want to find the parents	required
limit	int	Maximum number of results to return (default: 100)	DEFAULT_LIMIT
offset	int	Starting position in the full result set (default: 0)	0
**kwargs		Query parameters for filtering samples	{}

Returns:

Type	Description
List[Dict]	List[Dict]: Parent samples

list_children(sample_id, limit=DEFAULT_LIMIT, offset=0, **kwargs)

List the children of a given sample with optional filtering.

Parameters:

Name	Type	Description	Default
sample_id	str	The unique ID of the sample for which you want to find the children	required
limit	int	Maximum number of results to return (default: 100)	DEFAULT_LIMIT
offset	int	Starting position in the full result set (default: 0)	0
**kwargs		Query parameters for filtering samples	{}

Returns:

Type	Description
List[Dict]	List[Dict]: Children samples

graph(sample_id, recursive=False, as_networkx=False)

Return the graph of entities connected to this sample.

Delegates to client.graphs.get(). See GraphOperations.get() for full docs.

Parameters:

Name	Type	Description	Default
sample_id	str	Sample unique identifier.	required
recursive	bool	If True, traverse the full connected component.	False
as_networkx	bool	Return a networkx DiGraph if True.	False

Returns:

Type	Description
	dict | networkx.DiGraph: Node-link graph data.