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