Skip to content

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

mine = client.instruments.list(affiliation=["owner", "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:

client.instruments.set_status("0tkn2knjast3h0008nyq9zps2c", "maintenance")

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:

from crucible.models import Dataset

dataset = client.datasets.create(dataset=Dataset(
    dataset_name="HAADF-STEM image of Au NPs",
    measurement="STEM imaging",
    instrument_id="team-i",
    project_id="MFP12345",
))