Samples and Projects

Physical samples and projects let you group related data items for cross-run analysis. Use the SDK to list, fetch, and align data across multiple uploads.

List physical samples

from atomscale import Client

client = Client()

samples = client.list_physical_samples()
print(samples[["Physical Sample ID", "Physical Sample Name"]])

The returned DataFrame includes columns for sample metadata, linked projects, and ownership.

List projects

projects = client.list_projects()
print(projects[["Project ID", "Project Name", "Physical Sample Count"]])

Fetch a physical sample

Use get_physical_sample() to retrieve all analysis results linked to a sample:

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

# Iterate over all result objects
for item in result.data_results:
    print(type(item).__name__, item.data_id)

The returned PhysicalSampleResult contains:

physical_sample_id and physical_sample_name for identification
data_results with all result objects (RHEED, XPS, PL, metrology, etc.)

Fetch a project

Use get_project() to retrieve all data grouped by physical sample:

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

for sample in result.samples:
    print(f"Sample: {sample.physical_sample_name}")
    for item in sample.data_results:
        print(f"  {type(item).__name__}: {item.data_id}")

Align timeseries across sources

Pass align=True to time-align data from multiple sources onto a common time index:

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

# Access the aligned DataFrame
aligned = result.aligned_timeseries
print(aligned.columns)
print(aligned.tail())

This merges RHEED, metrology, optical, and other timeseries data so you can correlate signals across instruments. By default, alignment uses an outer join (union of all timestamps). Pass a join strategy string for different behavior:

# Inner join: only timestamps present in all sources
result = client.get_physical_sample(
    physical_sample_id="sample-uuid",
    align="inner",
)

Project-level alignment works the same way:

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

Introduction

Guides

References

List physical samples

List projects

Fetch a physical sample

Fetch a project

Align timeseries across sources

Next steps

Inspect Results

Client Reference

Introduction

Guides

References

Documentation Index

​List physical samples

​List projects

​Fetch a physical sample

​Fetch a project

​Align timeseries across sources

​Next steps

Inspect Results

Client Reference

List physical samples

List projects

Fetch a physical sample

Fetch a project

Align timeseries across sources

Next steps