> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atomscale.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Samples and Projects

> Work with physical samples, projects, and aligned timeseries

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

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
# 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:

```python theme={null}
result = client.get_project(project_id="project-uuid", align=True)
print(result.aligned_timeseries.tail())
```

## Next steps

<CardGroup cols={2}>
  <Card title="Inspect Results" icon="chart-line" href="/sdk/inspect-results">
    Work with individual analysis outputs.
  </Card>

  <Card title="Client Reference" icon="code" href="/sdk/reference/client">
    Full Client class documentation.
  </Card>
</CardGroup>