Skip to content

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=False)

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 the owner into a public-safe user object (default: True)

True
include_datasets bool

Also embed the linked dataset records (default: False). Deprecated by the API: use include_links, or client.datasets.list(sample_mfid=...).

False

Returns:

Name Type Description
Dict Optional[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, sort=None, direction=None, visibility=None, affiliation=None, include_total=None, creation_time_gte=None, creation_time_lte=None, modification_time_gte=None, modification_time_lte=None, cursor=None, mfid=None, **kwargs)

List samples with optional filtering and automatic pagination.

Parameters:

Name Type Description Default
mfid str or list

Only these sample MFIDs (up to 100). Unreadable, missing, or pending-deletion MFIDs are left out.

None
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 the owner 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

Only for the parent-child sub-listing; a nonzero value on the /samples collection raises RemovedError (use cursor).

0
cursor str

Continuation token from a previous result's next_cursor; the listing resumes there.

None
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
sort Optional[str]

Explicit ordering, one of crucible.constants.RESOURCE_SORTS. Omit to keep the legacy unique_id descending order.

None
direction Optional[str]

Sort direction, asc or desc. Requires sort.

None
visibility Optional[str]

Restrict results by public visibility: all, public, or private.

None
affiliation Optional[Union[str, Sequence[str]]]

Caller relationship each result must have: 'owner', or 'member' (reached through the caller's own grants). Accepts a single value or a sequence (OR).

None
include_total Optional[bool]

Request the exact authorization-filtered total. Omit to keep the endpoint's default behavior.

None
creation_time_gte Optional[Union[str, date, datetime]]

Inclusive lower creation-time bound. Accepts a datetime, date, or ISO 8601 string.

None
creation_time_lte Optional[Union[str, date, datetime]]

Inclusive upper creation-time bound, same types.

None
modification_time_gte Optional[Union[str, date, datetime]]

Inclusive lower modification-time bound, same types.

None
modification_time_lte Optional[Union[str, date, datetime]]

Inclusive upper modification-time bound, same types.

None
**kwargs Any

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.

facets(field, limit=100, sort=None, direction=None, cursor=None, **filters)

Group samples into value buckets with counts, without fetching records.

Parameters:

Name Type Description Default
field str

Field to group by, one of crucible.constants.SAMPLE_FACET_FIELDS.

required
limit int

Maximum number of buckets to return (default: 100, max 1000).

100
sort Optional[str]

Bucket ordering, one of crucible.constants.FACET_SORTS (default: value).

None
direction Optional[str]

Bucket ordering direction, asc or desc (default: asc).

None
cursor Optional[str]

Continuation cursor from a previous response's next_cursor.

None
**filters Any

Any sample list filter, restricting which samples contribute to the counts.

{}

Returns:

Name Type Description
Dict Dict

field, items (buckets with value, label, count, and a typed owner/project reference where applicable), limit, and next_cursor.

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

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
owner_ref Optional[Union[str, Sequence[str]]]

Owner or owners (up to 10, any matches): unique_id, linked ORCID, username, or email.

None

Returns:

Type Description
List[Dict]

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

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

Create a new sample record.

Parameters:

Name Type Description Default
sample Sample or dict

The sample's fields, as a Sample model or a dict validated through it. Use owner with an ORCID, MFID, username, or email to create for a specific owner; owner_orcid raises RemovedError. 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: ...}).

None
children list

Child samples to link ({unique_id: ...}).

None

Returns:

Name Type Description
Dict Dict

Created sample record.

update(sample_mfid, sample_name=None, description=None, timestamp=None, *, sample_type=None, parents=None, children=None, **removed)

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
parents List[Dict]

Parent samples to link

None
children List[Dict]

Child samples to link

None

Returns:

Name Type Description
Dict Dict

Updated sample object

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

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 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

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, cursor=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
cursor str

Continuation token from a previous result's next_cursor; the listing resumes there.

None
relationship_type str

Only return parents linked with this kind of link, one of crucible.constants.RELATIONSHIP_TYPES.

None
**kwargs Any

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, cursor=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
cursor str

Continuation token from a previous result's next_cursor; the listing resumes there.

None
relationship_type str

Only return children linked with this kind of link, one of crucible.constants.RELATIONSHIP_TYPES.

None
**kwargs Any

Query parameters for filtering samples

{}

Returns:

Type Description
List[Dict]

List[Dict]: Children samples

get_scientific_metadata(resource_mfid)

Get scientific metadata for a resource.

update_scientific_metadata(resource_mfid, metadata, overwrite=False)

Add or Update scientific metadata for a resource.

Parameters:

Name Type Description Default
overwrite bool

If True, replace all metadata (POST); if False, merge with existing (PATCH)

False

replace_scientific_metadata(resource_mfid, metadata)

Create new scientific metadata entry for a resource.

search_metadata(q, limit=20, owner_ref=None)

Full-text search across scientific metadata of all accessible resources.

Results are ranked by relevance (rank field) and include resource_type, name, owner_orcid, creation_time, modification_time, and scientific_metadata. Resources with pending or approved deletion requests are excluded.

Parameters:

Name Type Description Default
q str

Plain-text search query (English-language stemmed).

required
limit int

Max results to return (default 20, max 50).

20
owner_ref Optional[Union[str, Sequence[str]]]

Owner or owners (up to 10, any matches): unique_id, linked ORCID, username, or email.

None

Returns:

Type Description
list

List of result dicts with unique_id, resource_type, name, owner_orcid,

list

creation_time, modification_time, rank, and scientific_metadata.

list_access(mfid)

List every principal with access to a resource.

Readable by anyone with a role on the resource (not through public access alone); the resource's capabilities.can_view_access says whether you can. Each grant's capabilities says whether you may remove it or change its role, and to which roles.

set_access(mfid, kind, principal, permission)

Grant or change a principal's non-owner access to a resource.

revoke_access(mfid, kind, principal)

Revoke a principal's access to a resource.

set_public(mfid)

Grant public viewer access to a resource.

set_private(mfid)

Revoke public access to a resource.

transfer_ownership(mfid, new_owner, confirm=False)

Preview or apply a resource ownership transfer.

reassign_project(mfid, project_id=None, confirm=False, *, project_mfid=None)

Preview or apply reassignment to another project.

Parameters:

Name Type Description Default
mfid str

Resource MFID.

required
project_id Optional[str]

Target project slug.

None
confirm bool

False previews the reassignment, True applies it.

False
project_mfid Optional[str]

Target project MFID; preferred over project_id.

None