Tiled Cheat Sheet#

The audience for this cheat sheet is a scientist reading and writing data in Tiled from within a Python program. Not included: Running a Tiled server, or using Tiled’s HTTP REST and WebSocket APIs from other programming languages.

See 10 minutes to Tiled for an expanded version.

Install Python Tiled client

With pip or uv, install "tiled[client]". With conda or pixi, install tiled-client available on the conda-forge channel.

Connect

# Explicit URL
from tiled.client import from_uri
c = from_uri("https://tiled-demo.nsls2.bnl.gov")

# Alternatively, use a "profile" as shorthand.
from tiled.client import from_profile
c = from_profile("some_alias")

Navigate

x = c['examples/xraydb']
x.metadata

Search

from tiled.queries import Key

results = x.search(Key('element.category') == 'nonmetal')

Fetch items

results.keys().first()
results.keys()[0]  # equivalent

results.values().first()
results.values()[0]  # equivalent

# Loops progressively download results in paginated batches.
for key, value in results.items():
    print(f"~~ {key} ~~")
    print(value.metadata)

# See also last(), head(), tail().

Export

# Tiled infers desired format from '.csv' file extension
c['examples/xraydb/C/edges'].export('my_table.csv')

# List avaiable formats.
c['examples/images/binary_blobs'].formats
# Specify format explicitly as MIME type.
c['examples/images/binary_blobs'].export('my_image.png', format='image/png')

Slice remotely

# Download array slice into numpy object in memory.
arr = c['examples/images/binary_blobs'][:50,-50:]

# Download array slice to file on disk.
c['examples/images/binary_blobs'].export(
    'top_right_corner.png',
     slice=np.s_[:50,-50:],
)

# Download table columns into pandas DataFrame in memory.
c['examples/xraydb/C/edges'].read(['edge', 'energy_eV'])

# Download table columns into file on disk.
c['examples/xraydb/C/edges'].export('my_table.csv', columns=['edge', 'energy_eV'])

Locate data sources

from tiled.client.utils import get_asset_filepaths

# Just the file path(s)
get_asset_filepaths(c['examples/xraydb/C/edges'])

# More detailed information, including format, shape or column names
(as applicable), URIs, etc.
c['examples/xraydb/C/edges'].data_sources()

Upload data

This requires a server that you are authorized to write to.

c.write_array([1, 2, 3], metadata={'color': 'blue'})
c.write_table({'a': [1, 2], 'b': [3, 4]}, metadata={'color': 'blue'})
s = c.create_container('stuff')
s.write_array([1, 2, 3], key='nested stuff')

More features not shown:

  • Downloading raw files in parallel

  • Registering data (e.g. files) without uploading a copy

  • Streaming data live

  • Specialized array structures, including sparse arrays and Awkward Arrays

See 10 minutes to Tiled for an expanded version.

This Page