Client - Atomscale Documentation

The Client class is your entry point to the Atomscale API. It provides methods for searching the catalogue, fetching analysis results, querying RHEED features and masks, running similarity queries, uploading files, and downloading raw or processed data.

View source on GitHub

Constructor

from atomscale import Client

client = Client(
    api_key="YOUR_API_KEY",
    endpoint="https://api.atomscale.ai/",
    mute_bars=False,
)

str | None

default:"None"

API key for authentication. If not provided, reads from the AS_API_KEY environment variable.

str

default:"https://api.atomscale.ai/"

Root API endpoint. Can be overridden with the AS_API_ENDPOINT environment variable.

bool

default:"False"

Whether to suppress progress bars. Set to True for non-interactive environments like CI pipelines.

search()

Search and filter items in the data catalogue.

results = client.search(
    keywords="GaN",
    include_organization_data=True,
    data_type="rheed_stationary",
    status="success",
)

Parameters

str | list[str] | None

default:"None"

Keyword or list of keywords to search all catalogue fields. Applied after other explicit filters.

bool

default:"True"

Whether to include catalogue entries from other users in your organization.

str | list[str] | None

default:"None"

Filter to specific data IDs.

str | list[str] | None

default:"None"

Filter by physical sample IDs.

str | list[str] | None

default:"None"

Filter by project IDs.

str

default:"all"

Filter by data type.

Value	Description
`rheed_image`	Single RHEED image
`rheed_stationary`	Stationary RHEED video
`rheed_rotating`	Rotating RHEED video
`xps`	XPS spectrum
`xrd`	XRD pattern
`photoluminescence`	Photoluminescence spectrum
`pl`	Alias for photoluminescence
`raman`	Raman spectrum
`ellipsometry`	Ellipsometry measurement
`optical`	Optical imaging
`metrology`	Instrument metrology log
`recipe`	Growth recipe
`all`	All types

str

default:"all"

Filter by pipeline status.

Value	Description
`success`	Analysis completed
`pending`	Queued for processing
`running`	Currently processing
`error`	Analysis failed
`stream_active`	Streaming in progress
`stream_interrupted`	Stream was interrupted
`stream_finalizing`	Stream finishing
`stream_error`	Streaming failed
`all`	All statuses

tuple[int | None, int | None]

default:"(None, None)"

Filter by growth length in seconds. Tuple of (min, max) with None for open bounds.

tuple[datetime | None, datetime | None]

default:"(None, None)"

Filter by upload timestamp. Tuple of (min, max) with None for open bounds.

tuple[datetime | None, datetime | None]

default:"(None, None)"

Filter by last updated timestamp. Tuple of (min, max) with None for open bounds.

tuple[datetime | None, datetime | None] | None

default:"None"

deprecated

Deprecated alias for last_updated. Passing it emits a warning and will stop working in a future release.

Returns

pandas.DataFrame

DataFrame with columns:

Column	Description
`Data ID`	Unique identifier
`File Name`	Original filename
`Type`	Data type (rheed_image, rheed_stationary, etc.)
`Status`	Pipeline status
`File Type`	File extension/format
`File Metadata`	Format-specific metadata captured at ingest
`Instrument Source`	Source instrument
`Sample Name`	Associated sample name
`Growth Length`	Duration in seconds (for videos)
`Physical Sample ID`	Linked physical sample
`Physical Sample Name`	Physical sample name
`Sample Notes`	Associated notes
`Sample Notes Last Updated`	When the notes last changed
`Project ID`	Linked project
`Project Name`	Project name
`Tags`	Tags attached to the item
`Collected Datetime`	When the data was collected
`Upload Datetime`	When the file was uploaded
`Last Updated`	When the entry last changed
`Has Instrument Logs`	Whether instrument logs are linked
`Owner`	Uploader’s name
`Workspaces`	Associated workspaces

Example

from datetime import datetime

results = client.search(
    keywords="GaN",
    data_type="rheed_stationary",
    status="success",
    upload_datetime=(datetime(2025, 1, 1), None),
    growth_length=(3000, None),
)
print(results[["Data ID", "Status", "Sample Name"]])

get()

Fetch analysis results for one or more data IDs.

analysed = client.get(data_ids=["44fa63b0-74da-4d25-a362-2276c80a670a"])

Parameters

str | list[str]

required

Data ID or list of data IDs from the catalogue.

Returns

List of result objects. The type depends on the source data:RHEEDVideoResult (for rheed_stationary, rheed_rotating):

timeseries_data - DataFrame with per-frame metrics, indexed against Time
snapshot_image_data - List of extracted frame snapshots
rotating - Whether the video was taken of a rotating stage

For the full low-level feature set, per-frame masks, or a time window, use get_rheed_timeseries() instead.RHEEDImageResult (for rheed_image):

processed_image - Processed image as a PIL Image
mask - Binary segmentation mask (numpy array)
pattern_graph - NetworkX graph of the diffraction pattern
get_pattern_dataframe() - Tidy table of spot positions (params: extra_data, symmetrize, return_as_features)
get_laue_zero_radius() - Best-fit radius and center of the zeroth order Laue zone
get_plot() - PIL Image with overlays (params: show_mask, show_spot_nodes, symmetrize, alpha)

XPSResult (for xps):

binding_energies - Array of binding energy values
intensities - Array of intensity values
predicted_composition - Dict mapping element symbols to fractional composition
detected_peaks - Detected peak positions
get_plot() - Matplotlib figure

XRDResult (for xrd):

two_theta - 2-theta angle values, in the unit given by two_theta_unit
intensities - Intensity values aligned with two_theta
detected_peaks - Peak dicts with two_theta, intensity, d_spacing_angstrom, prominence, and fwhm_degrees
wavelength_angstrom - Source wavelength (default Cu Kα, 1.5406)
get_plot() - Matplotlib figure

PhotoluminescenceResult (for photoluminescence):

energies - Energy axis values
intensities - Intensity values
detected_peaks - Peak labels and positions
get_plot() - Matplotlib figure

RamanResult (for raman):

raman_shift - Raman shift axis values
intensities - Intensity values
detected_peaks - Peak labels and positions
get_plot() - Matplotlib figure

MetrologyResult (for metrology/instrument data):

timeseries_data - DataFrame with instrument readings (pyrometer, pressure, etc.)

OpticalResult (for optical imaging):

timeseries_data - DataFrame with per-frame metrics (edge perimeter, circularity, etc.)
snapshot_image_data - List of OpticalImageResult snapshots, each with a processed_image

EllipsometryResult (for ellipsometry):

timeseries_data - DataFrame with per-wavelength channels (psi_<λ>, delta_<λ>, depol_<λ>, incidentI_<λ>) and scalar fits such as thickness

UnknownResult (fallback for unsupported types):

data_type - Type string
catalogue_entry - Raw catalogue metadata

Example

# Search and get results
search_results = client.search(keywords="demo", status="success")
analysed = client.get(search_results["Data ID"].to_list())

# Access time series data
video = analysed[0]
print(video.timeseries_data.columns)
print(video.timeseries_data.tail())

get_rheed_timeseries()

Fetch the RHEED feature timeseries for a data entry. Unlike get(), which returns only the standard feature set, this method can also return the full set of low-level features, attach per-frame segmentation masks, and filter which points come back.

df = client.get_rheed_timeseries(
    data_id,
    include_low_level_features=True,
    include_masks=True,
    last_n=500,
)

Parameters

str

required

Data ID of the RHEED video.

list[str] | None

default:"None"

Restrict the result to these feature names. These are the underlying property names (for example specular_intensity, referenced_strain), which differ from the display column names in the returned DataFrame. None returns the standard set.

bool

default:"False"

Include the full set of low-level per-point features as additional columns. These keep their raw backend names, and nested values are flattened into dotted column paths.

bool

default:"False"

Fetch the per-frame segmentation masks (see get_frame_masks()) and attach them as mask_rle, mask_height, and mask_width columns, joined on the Frame Number axis. Only masks for the frames the returned series spans are fetched, so this respects any last_n or elapsed_seconds window.

int | None

default:"None"

Only return the last N points.

float | None

default:"None"

Only return points within the last elapsed_seconds of the recording.

Returns

pandas.DataFrame

The RHEED timeseries, indexed by ["Angle", "Frame Number"] when both axes are available. Low-level feature columns appear when include_low_level_features=True, and mask columns when include_masks=True.Mask coverage is sparse: masks exist only for featurized frames, so rows without a mask contain NA in the mask columns, as do all rows when the video has no mask artifact.

Example

from atomscale.results import decode_mask_rle

df = client.get_rheed_timeseries(data_id, include_masks=True, elapsed_seconds=60.0)

row = df.dropna(subset=["mask_rle"]).iloc[0]
mask = decode_mask_rle(row["mask_rle"], row["mask_height"], row["mask_width"])
print(mask.shape)   # (H, W) uint8, values 0/1

get_frame()

Fetch a single extracted RHEED frame as a RHEEDImageResult.

frame = client.get_frame(data_id, frame_index=0)

Parameters

str

required

Data ID of the RHEED video.

int

default:"0"

Index into the video’s extracted-frame list. Negative indexing is supported, so -1 returns the last extracted frame.

Returns

RHEEDImageResult | None

The frame’s image result, or None when the video has no extracted frames, frame_index is out of range, or the selected frame has no image.

get_frame_masks()

Fetch per-frame RHEED segmentation masks for a processed video. Each featurized frame carries a binary mask of the diffraction pattern, encoded as a COCO run-length-encoding (RLE) counts string.

masks = client.get_frame_masks(data_id, from_frame=0, to_frame=500, decode=True)

Parameters

str

required

Data ID of the RHEED video, the same ID used for the video and timeseries.

int

default:"0"

First absolute frame number to fetch, inclusive. Must be >= 0.

int | None

default:"None"

Last absolute frame number to fetch, inclusive. None fetches every featurized frame from from_frame to the end of the video.

bool

default:"False"

When True, decode each RLE mask into an (H, W) uint8 array and return a dict keyed by frame number. When False, return the raw rows with the RLE string intact.

Returns

list[dict] | dict[int, NDArray]

With decode=False, a list of row dicts each containing data_id, processed_data_id, frame_number, mask_rle, mask_height, and mask_width. With decode=True, a dict of {frame_number: ndarray} holding (H, W) uint8 masks with values 0 or 1.Returns an empty list or dict when the video has no per-frame mask artifact.

frame_number is the absolute frame index, keyed identically to the processed video frames and the Frame Number axis of the timeseries. Coverage is sparse: for stationary videos every frame is featurized, but for rotating and per-azimuth videos only a sampled subset is, so returned frame numbers are not necessarily contiguous.

Example

masks = client.get_frame_masks(data_id, decode=True)
frame_numbers = sorted(masks)
print(f"{len(masks)} masks, frames {frame_numbers[0]}-{frame_numbers[-1]}")

get_changepoints()

Get changepoint detection records for one or more data IDs.

changepoints = client.get_changepoints(
    data_ids=["44fa63b0-74da-4d25-a362-2276c80a670a"],
    severity="critical",
)

Parameters

str | list[str]

required

Data ID or list of data IDs from the catalogue.

bool

default:"True"

Return only changepoints from the most recently completed detection run for each (data_id, detection_method) pair. Pass False for every historical run.

str | None

default:"intensity_profile"

Filter to a single detection method: forecasting, clustering, or intensity_profile. Pass None to include all methods.

str | None

default:"critical"

Filter to a single severity level: info, warning, or critical. Pass None to include all severities.

bool

default:"True"

Return a DataFrame. Pass False for a list of ChangepointResult objects.

Returns

DataFrame | list[ChangepointResult]

Changepoint records matching the filters. Each record carries:

id - Unique ID of the changepoint record
data_id - Data ID the changepoint was detected on
data_modality - Modality it was detected in (for example rheed_stationary)
property_name - Property or channel the changepoint was detected on
severity - info, warning, or critical
score - Normalized changepoint score in [0, 1]
window_start_elapsed / window_end_elapsed - Window bounds in seconds from the start of the timeseries
detection_method - forecasting, clustering, or intensity_profile
detail - Method-specific detail dict
label - Applied category label, if any

See Changepoint Detection for how the methods differ and when each fires.

get_similarity_trajectory()

Fetch a one-shot similarity trajectory for a data ID or physical sample ID.

result = client.get_similarity_trajectory(source_id, last_n=200)
print(result.timeseries_data.tail())

Parameters

str

required

Data ID or physical sample ID the trajectory is computed against.

str

default:"rheed_stationary"

Similarity workflow name.

int | None

default:"None"

Only fetch the last N points of the trajectory.

float | None

default:"None"

Window span in seconds, forwarded to the provider.

list[str] | None

default:"None"

Reference data IDs to compare against.

str | None

default:"None"

Softmax mode forwarded to the provider.

int | None

default:"None"

Number of reference values forwarded to the provider.

Returns

SimilarityTrajectoryResult

Result object with attributes:

source_id - The queried source ID
workflow - Workflow name used
window_span - Window length in seconds
source_data_ids - Source data IDs included in the trajectory
timeseries_data - DataFrame indexed by ("Reference ID", "Time") with columns Similarity, Reference Name, UNIX Timestamp, Active, and Averaged Count

get_embeddings()

Fetch similarity embedding vectors for a data entry.

emb = client.get_embeddings(data_id, window_span=60.0, kind="window")
print(emb.vectors.shape)

Parameters

str

required

Data ID to fetch embeddings for.

str

default:"rheed_stationary"

Similarity workflow name.

float

default:"60.0"

Window span in seconds.

str

default:"window"

window for one time-resolved vector per window, or prototype for a small set of representative vectors.

int

default:"0"

Number of leading vectors to skip.

int | None

default:"None"

Maximum number of vectors to return. None returns all available vectors.

Returns

EmbeddingsResult

Result object with attributes:

vectors - (n_returned, dimension) array of embedding vectors
dimension - Length of each vector, 0 when the result is empty
count - Total vectors available before offset and limit
truncated - True when more vectors are available than were returned
offset - Number of leading vectors skipped
real_times / unix_times_ms - Timing arrays, for kind="window"
cluster_sizes - Windows summarized per vector, for kind="prototype"

Metadata arrays that do not apply to the returned kind are None.

When no embeddings exist for the requested workflow and window span, the SDK emits a UserWarning and returns an empty result rather than raising, so loops over many IDs keep running.

query_rheed_embeddings()

Find RHEED data items whose embeddings are most similar to a given item. Runs k-nearest-neighbour search over the embedding index using the item’s own vectors.

neighbours = client.query_rheed_embeddings(data_id, top_k=10)
print(neighbours[["data_id", "similarity"]])

Parameters

str

required

Data ID whose vectors seed the query.

str

default:"rheed_stationary"

Similarity workflow name.

float

default:"60.0"

Embedding window span in seconds. Must match a span the data was embedded at.

str

default:"prototype"

prototype for a coarse query, or window for a finer query with more lookups.

int

default:"10"

Maximum neighbours to return. The backend caps this at 30.

Returns

pandas.DataFrame

Columns data_id and similarity (1 = identical), plus the locus columns source_index, neighbor_index, real_time_seconds, and unix_time_ms, sorted by descending similarity. Empty when the item has no embeddings for the given workflow and window span.

get_similarity_matches()

Fetch the top stored similarity matches for a source entry.

matches = client.get_similarity_matches(source_id, window_span=60.0)

Parameters

str

required

Data ID or physical sample ID to find matches for.

str

default:"rheed_stationary"

Similarity workflow name.

float

default:"60.0"

Window span in seconds.

bool

default:"False"

Also include the source entry’s most recent, still-streaming data in the comparison.

int | None

default:"None"

Maximum number of matches to return. None uses the server default.

Returns

pandas.DataFrame

Columns data_id, item_name, and similarity, one row per match. Empty with those columns when there are no matches or the source is not found.

Trajectory polling wrappers

Four Client methods wrap the polling functions in atomscale.similarity so you can poll a similarity trajectory without importing them separately.

Method	Style	Returns
`iter_poll_similarity_trajectory()`	Synchronous loop	`Iterator[DataFrame]`
`aiter_poll_similarity_trajectory()`	Async iterator	`AsyncIterator[DataFrame]`
`start_polling_similarity_trajectory_thread()`	Background daemon thread	`threading.Event`
`start_polling_similarity_trajectory_task()`	Asyncio task	`asyncio.Task[None]`

Each takes source_id, interval (default 1.0), and last_n. The thread and task variants also take an on_result callback. Extra keyword arguments (distinct_by, until, max_polls, fire_immediately, jitter, on_error) are forwarded to the underlying function.

for frame in client.iter_poll_similarity_trajectory(source_id, interval=5.0, last_n=10):
    print(frame["Similarity"].iloc[-1])
    if not frame["Active"].any():
        break

See Poll Similarity Trajectory for the full walkthrough.

upload()

Upload files for analysis.

client.upload(files=[
    "/path/to/rheed.mp4",
    "/path/to/xps.vms",
])

Parameters

list[str | BinaryIO]

required

List of file paths (strings) or open file handles (BinaryIO objects).

str | None

default:"None"

Physical sample name or UUID to link the uploads to. If a name is given and no matching sample exists, one is created automatically.

str | None

default:"None"

Project name or UUID to associate the uploads with. The project must already exist, since the SDK does not auto-create projects. When provided, physical_sample is required so the sample can be added to the project’s tracking list.

Returns

list[str]

Data IDs assigned to the uploaded files. Analysis runs asynchronously, so use search() or the web UI to monitor progress.

Example

# Upload by path
data_ids = client.upload(files=[
    "/data/growths/2025-02-10/RHEED-stationary.mp4",
    "/data/growths/2025-02-10/RHEED-rotating.imm",
])

# Upload into a sample and project
data_ids = client.upload(
    files=["/data/growths/2025-02-10/RHEED-stationary.mp4"],
    physical_sample="GaN-2025-001",
    project="Nitride Buffer Study",
)

# Upload from file handles
with open("/data/rheed.mp4", "rb") as f:
    client.upload(files=[f])

download()

Download raw or processed files to disk. Works for every data type the platform stores, including RHEED video, XPS, XRD, PL, Raman, optical, metrology, and ellipsometry, returning whatever file format the backend has on record.

client.download(
    data_ids=["44fa63b0-74da-4d25-a362-2276c80a670a"],
    dest_dir="processed/",
    data_type="processed",
)

Parameters

str | list[str]

required

One or more data IDs from the catalogue.

str | Path | None

default:"None"

Directory to write files to. Defaults to current working directory.

str

default:"processed"

Whether to download raw or processed data.

Returns

None. Files are saved to the destination directory.

Example

search_results = client.search(data_type="rheed_stationary", status="success")

# Download processed videos
client.download(
    data_ids=search_results["Data ID"].to_list(),
    dest_dir="processed/",
)

# Download raw files
client.download(
    data_ids=search_results["Data ID"].to_list(),
    dest_dir="raw/",
    data_type="raw",
)

download_videos()

Deprecated alias for download(), kept for backwards compatibility. It takes the same parameters and behaves identically. Use download() in new code.

list_physical_samples()

List all physical samples accessible to your account.

samples = client.list_physical_samples()

Returns

pandas.DataFrame

DataFrame of physical sample records with columns including Physical Sample ID, Physical Sample Name, Project ID, Project Name, Target Material, and Owner.

list_projects()

List all projects accessible to your account.

projects = client.list_projects()

Returns

pandas.DataFrame

DataFrame of project records with columns including Project ID, Project Name, Physical Sample Count, Project Notes, and Owner.

get_physical_sample()

Get all data associated with a physical sample.

result = client.get_physical_sample(
    physical_sample_id="sample-uuid",
    align=True,
)

Parameters

str

required

The physical sample ID.

bool

default:"True"

Whether to include data from other users in your organization.

bool | str

default:"False"

Whether to time-align data from multiple sources. Pass True for outer join, or a string like "inner" to control the join strategy.

Returns

PhysicalSampleResult

Result object with attributes:

physical_sample_id - Sample identifier
physical_sample_name - Sample name
data_results - List of all result objects for this sample
aligned_timeseries - Aligned DataFrame if align was set, otherwise None

get_project()

Get all data associated with a project.

result = client.get_project(
    project_id="project-uuid",
    align=True,
)

Parameters

str

required

The project ID.

bool

default:"True"

Whether to include data from other users in your organization.

bool | str

default:"False"

Whether to time-align data from multiple sources. Pass True for outer join, or a string like "inner" to control the join strategy.

Returns

ProjectResult

Result object with attributes:

project_id - Project identifier
project_name - Project name
samples - List of PhysicalSampleResult objects for each sample in the project
aligned_timeseries - Project-level aligned DataFrame if align was set, otherwise None

list_growth_instruments()

List all growth instruments accessible to your account.

instruments = client.list_growth_instruments()

Returns

list[dict]

List of instrument records. Each dict contains:

synth_source_id - Unique instrument ID (int)
source_name - Display name
synth_source_type - Instrument type (mbe, cvd, etc.)
source_manufacturer - Manufacturer name
source_model - Model name

create_growth_instrument()

instrument_id = client.create_growth_instrument(
    label="Main MBE",
    name="Veeco GEN10",
    instrument_type="mbe",
    serial_id="SN-12345",
)

Parameters

str

required

Display name for the instrument (e.g., “Main MBE”).

str

required

Manufacturer and model (e.g., “Veeco GEN10”).

str

required

Type of growth instrument.

Value	Description
`mbe`	Molecular beam epitaxy
`cvd`	Chemical vapor deposition
`pvd`	Physical vapor deposition
`sputter`	Sputtering
`ald`	Atomic layer deposition
`pld`	Pulsed laser deposition

str | None

default:"None"

Optional serial number or identifier.

Returns

int

The ID of the newly created instrument.

delete_growth_instrument()

Delete a growth instrument.

client.delete_growth_instrument(synth_source_id=42)

Parameters

int

required

ID of the instrument to delete.

Returns

None.

​Constructor

​search()

​Parameters

​Returns

​Example

​get()

​Parameters

​Returns

​Example

​get_rheed_timeseries()

​Parameters

​Returns

​Example

​get_frame()

​Parameters

​Returns

​get_frame_masks()

​Parameters

​Returns

​Example

​get_changepoints()

​Parameters

​Returns

​get_similarity_trajectory()

​Parameters

​Returns

​get_embeddings()

​Parameters

​Returns

​query_rheed_embeddings()

​Parameters

​Returns

​get_similarity_matches()

​Parameters

​Returns

​Trajectory polling wrappers

​upload()

​Parameters

​Returns

​Example

​download()

​Parameters

​Returns

​Example

​download_videos()

​list_physical_samples()

​Returns

​list_projects()

​Returns

​get_physical_sample()

​Parameters

​Returns

​get_project()

​Parameters

​Returns

​list_growth_instruments()

​Returns

​create_growth_instrument()

​Parameters

​Returns

​delete_growth_instrument()

​Parameters

​Returns

Constructor

search()

Parameters

Returns

Example

get()

Parameters

Returns

Example

get_rheed_timeseries()

Parameters

Returns

Example

get_frame()

Parameters

Returns

get_frame_masks()

Parameters

Returns

Example

get_changepoints()

Parameters

Returns

get_similarity_trajectory()

Parameters

Returns

get_embeddings()

Parameters

Returns

query_rheed_embeddings()

Parameters

Returns

get_similarity_matches()

Parameters

Returns

Trajectory polling wrappers

upload()

Parameters

Returns

Example

download()

Parameters

Returns

Example

download_videos()

list_physical_samples()

Returns

list_projects()

Returns

get_physical_sample()

Parameters

Returns

get_project()

Parameters

Returns

list_growth_instruments()

Returns

create_growth_instrument()

Parameters

Returns

delete_growth_instrument()

Parameters

Returns