SampleOperations

Access via client.samples.

crucible.resources.samples.SampleOperations

Sample-related API operations.

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

get(sample_mfid, include_links=False, include_metadata=False, include_owner=True, include_datasets=True)

Get a sample by its canonical MFID.

Parameters:

Name	Type	Description	Default
sample_mfid	str	Sample MFID	required
include_links	bool	Whether to include immediate parent/child/associated links	False
include_metadata	bool	Whether to include scientific metadata	False
include_owner	bool	Resolve owner_orcid into a public-safe user object (default: True)	True
include_datasets	bool	Include deprecated embedded dataset records (default: True). Set False and use include_links or client.datasets.list(sample_mfid=...) instead.	True

Returns:

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

list(dataset_mfid=None, parent_mfid=None, include_metadata=False, include_links=False, include_owner=False, limit=DEFAULT_LIMIT, offset=0, accessible_to_user=None, accessible_to_project=None, project_id=None, project_mfid=None, project_scope=None, **kwargs)

List samples with optional filtering and automatic pagination.

Parameters:

Name	Type	Description	Default
dataset_mfid	str	Get samples linked to this dataset MFID	None
parent_mfid	str	Get child samples from this parent MFID	None
include_metadata	bool	Include scientific metadata in results	False
include_links	bool	Include linked resources (parents, children, associated) per sample	False
include_owner	bool	Resolve owner_orcid into a public-safe user object per sample	False
limit	int	Maximum total results to return (default: 100). Larger requests are handled transparently by following the server's keyset cursor. Pass None to fetch all matches.	DEFAULT_LIMIT
offset	int	Deprecated for the /samples collection, which uses keyset pagination and ignores offset. Still honored for the parent-child sub-listing.	0
accessible_to_user	Optional[Union[str, Sequence[str]]]	User reference or references whose effective access must include every result	None
accessible_to_project	Optional[Union[str, Sequence[str]]]	Project reference or references whose direct access must include every result	None
project_id	Optional[str]	Project slug used to scope results by project relationship	None
project_mfid	Optional[str]	Canonical project MFID used to scope results by project relationship	None
project_scope	Optional[str]	Project relationship to include: assigned, shared, or all. Requires project_id or project_mfid and defaults to assigned.	None
**kwargs		Query parameters for filtering samples	{}

Returns:

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

count(project_id=None, project_mfid=None, project_scope=None, **kwargs)

Return the total number of samples matching the given filters without fetching items.

search(q, project_id=None, limit=20)

Fuzzy name search across samples. Available to all authenticated users.

Matches against sample_name. Returns samples the caller can read. For scientific metadata search use search_metadata().

Parameters:

Name	Type	Description	Default
q	str	Search term (min 3 chars). Typo-tolerant.	required
project_id	Optional[str]	Optional project to scope results to.	None
limit	int	Max results (default 20, max 50).	20

Returns:

Type	Description
List[Dict]	List[Dict]: Matching SampleResponse records, ranked by relevance.

create(sample=None, scientific_metadata=None, parents=[], children=[], **kwargs)

Create a new sample record.

Parameters:

Name	Type	Description	Default
sample	Sample	Sample model instance with the desired fields. Use owner with an ORCID, MFID, username, or email to create for a specific owner. owner_orcid is deprecated for creation. Providing both owner fields is invalid. project_id accepts the human-readable ID and project_mfid accepts the canonical MFID. Matching selectors may be supplied together.	None
scientific_metadata	dict	Scientific metadata to attach after creation.	None
parents	list	Parent samples to link ({unique_id: ...}).	[]
children	list	Child samples to link ({unique_id: ...}).	[]

Returns:

Name	Type	Description
Dict	Dict	Created sample record.

update(sample_mfid, 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
sample_mfid	str	Sample MFID	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	Deprecated - the API no longer accepts this field here; use client.samples.transfer_ownership() instead.	None
public	bool	Deprecated - use set_public() or set_private()	None
project_id	str	Deprecated - the API no longer accepts this field here; use client.samples.reassign_project() instead.	None
parents	List[Dict]	Parent samples to link	[]
children	List[Dict]	Child samples to link	[]

Returns:

Name	Type	Description
Dict	Dict	Updated sample object

link_dataset(sample_mfid, dataset_mfid)

Link a dataset to this sample.

Delegates to DatasetOperations.link_sample.

Parameters:

Name	Type	Description	Default
sample_mfid	str	Sample MFID	required
dataset_mfid	str	Dataset MFID	required

Returns:

Name	Type	Description
Dict	Dict	Information about the created link

unlink_dataset(sample_mfid, dataset_mfid)

Remove the link between a sample and a dataset.

Requires admin permissions.

Parameters:

Name	Type	Description	Default
sample_mfid	str	Sample MFID	required
dataset_mfid	str	Dataset MFID	required

Returns:

Name	Type	Description
Dict	Dict	Deletion confirmation

link(parent_mfid, child_mfid, relationship_type=None)

Link two samples with a parent-child relationship.

Parameters:

Name	Type	Description	Default
parent_mfid	str	Parent sample MFID	required
child_mfid	str	Child sample MFID	required
relationship_type	str	Kind of link, one of crucible.constants.RELATIONSHIP_TYPES. Describes the child relative to the parent, so 'is_part_of' reads "child is_part_of parent". Omit to leave the kind unspecified; on a link that already exists, omitting it preserves the type already stored rather than clearing it.	None

Returns:

Name	Type	Description
Dict	Dict	Created link object

unlink(parent_mfid, child_mfid)

Remove the parent-child link between two samples.

Parameters:

Name	Type	Description	Default
parent_mfid	str	Parent sample MFID	required
child_mfid	str	Child sample MFID	required

Returns:

Name	Type	Description
Dict	Dict	Deletion confirmation

list_parents(child_mfid, limit=DEFAULT_LIMIT, offset=0, relationship_type=None, **kwargs)

List the parents of a given sample with optional filtering.

Parameters:

Name	Type	Description	Default
child_mfid	str	Child sample MFID	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
relationship_type	str	Only return parents linked with this kind of link, one of crucible.constants.RELATIONSHIP_TYPES.	None
**kwargs		Query parameters for filtering samples	{}

Returns:

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

list_children(parent_mfid, limit=DEFAULT_LIMIT, offset=0, relationship_type=None, **kwargs)

List the children of a given sample with optional filtering.

Parameters:

Name	Type	Description	Default
parent_mfid	str	Parent sample MFID	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
relationship_type	str	Only return children linked with this kind of link, one of crucible.constants.RELATIONSHIP_TYPES.	None
**kwargs		Query parameters for filtering samples	{}

Returns:

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

graph(sample_mfid, 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_mfid	str	Sample MFID.	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.