Instrument Model¶
| Field | Description | Settable |
|---|---|---|
instrument_id |
Unique 3-to-25-character slug used to reference the instrument | create, update |
instrument_name |
Human-readable display name | create, update |
owner_orcid |
Deprecated by the API; read owner instead |
read |
owner |
Flexible owner identifier on create; public-safe user record on reads with owner expansion | create with an ORCID, MFID, username, or email; expanded by default on get() |
location |
Physical location (e.g. room number or building) | create, update |
manufacturer |
Instrument manufacturer (e.g. "FEI", "Bruker") |
create, update |
model |
Manufacturer model name or number | create, update |
instrument_type |
Category of instrument (e.g. "Transmission electron microscope") |
create, update |
description |
Free-text description of the instrument | create, update |
other_id |
External identifier (e.g. facility inventory number, RRID, DOI) | create, update |
other_id_source |
Source of the external identifier (e.g. "RRID", "DOI") |
create, update |
unique_id |
System-assigned MFID identifier | server-assigned |
creation_time |
When the record was created | server-assigned |
modification_time |
When the record was last modified | server-assigned |
status |
Lifecycle state: active, maintenance, or decommissioned |
server-managed |
capabilities |
Optional caller-specific actions calculated for an exact response | server-assigned |
New and renamed instrument IDs must contain 3 to 25 characters. Lookup remains compatible with older IDs outside that range.
Working with Instruments¶
Creating an instrument¶
Instruments are shared across all projects. If an instrument with the same instrument_id slug already exists, create() returns the existing record rather than creating a duplicate.
from crucible.models import Instrument
instrument = client.instruments.create(Instrument(
instrument_id="team-i",
instrument_name="TEAM I",
manufacturer="FEI",
model="Titan 80-300",
location="72-150",
instrument_type="Transmission electron microscope",
description="Aberration-corrected TEM/STEM with monochromator",
other_id="SCR_023886",
other_id_source="RRID",
))
When owner is omitted, the authenticated human identity becomes the owner. A human platform administrator may create an instrument for another registered identity by supplying an ORCID, MFID, username, or email. Service accounts cannot create instruments, including for themselves.
Listing instruments¶
instruments = client.instruments.list()
for i in instruments:
print(i["instrument_name"], i["location"])
Normal list operations return active instruments.
Pass status="maintenance" or status="decommissioned" to select another lifecycle state.
List owner expansion is opt-in with include_owner=True.
owner_ref (one owner or up to 10) keeps instruments owned by any of them, and affiliation keeps those you own (owner), help run as an editor or admin member (maintainer), or belong to at any role (member):
Getting an instrument¶
instrument = client.instruments.get("team-i")
# or by canonical MFID
instrument = client.instruments.get("0tkn2knjast3h0008nyq9zps2c")
Singleton retrieval expands owner by default as a public-safe user record containing unique_id, username, first_name, and last_name.
Pass include_owner=False to suppress expansion.
Exact MFID and slug lookups include caller-specific capabilities when the server has calculated them. General lists and searches normally return capabilities=None, which means the guidance was not calculated rather than that every action is denied. The API remains authoritative for each mutation.
Use instrument_id= or instrument_mfid= when the intended identifier type must be explicit. Display names are not identifiers and are not accepted by the general lookup. An MFID passed as instrument_id= raises RemovedError; use instrument_mfid=.
Updating an instrument¶
client.instruments.update("0tkn2knjast3h0008nyq9zps2c", description="Updated description", location="72-200")
Lifecycle changes use the dedicated status operation:
Ownership is not an update field. Preview an ownership transfer first, then repeat it with confirmation:
client.instruments.transfer_ownership(
"0tkn2knjast3h0008nyq9zps2c",
"new-owner",
)
client.instruments.transfer_ownership(
"0tkn2knjast3h0008nyq9zps2c",
"new-owner",
confirm=True,
)
Managing members¶
Instrument members work like project members. Every member reads the instrument's datasets, editor also edits the instrument's details, and admin also changes its status, binds service accounts, and manages members. The member list is visible to members and to platform administrators running elevated; list_users() returns None for anyone else.
members = client.instruments.list_users("team-i")
client.instruments.add_user("team-i", "alice") # viewer by default
client.instruments.update_user_role("team-i", "alice", "editor")
client.instruments.remove_user("team-i", "alice")
Each change returns the updated list[ProjectMember]. Adding an existing member returns 409; use update_user_role(). Ownership changes only through transfer_ownership(). A member may remove themselves. set_access() and revoke_access() raise RemovedError for instruments.
Managing service-account operators¶
Instrument administrators can inspect, add, and remove service-account operators through the instrument namespace:
operators = client.instruments.list_service_accounts("0tkn2knjast3h0008nyq9zps2c")
client.instruments.bind_service_account("0tkn2knjast3h0008nyq9zps2c", "0tkvpezyz1zzf00076nahf85j4")
client.instruments.unbind_service_account("0tkn2knjast3h0008nyq9zps2c", "0tkvpezyz1zzf00076nahf85j4")
Referencing instruments in datasets¶
Once registered, reference an instrument in datasets by its slug: