Add cheatsheet

docs/source/_toc.yml

@@ -11,6 +11,8 @@ subtrees:
           - entries:
             - file: getting-started/what-is-tiled
             - file: getting-started/10-minutes-to-tiled
+            - file: getting-started/cheat-sheet
+              title: Cheat Sheet
             - file: getting-started/integrations/index
               subtrees:
                 - entries:

docs/source/getting-started/10-minutes-to-tiled.md

@@ -13,7 +13,8 @@ kernelspec:
 
 # 10 minutes to Tiled
 
-This is a short, tutorial-style introduction to Tiled, for new users.
+This is a short, tutorial-style introduction to Tiled, for new users. See the
+[cheat sheet](#cheat-sheet) for a condensed and abridged version.
 
 ## Connect
 

docs/source/getting-started/cheat-sheet.md

@@ -0,0 +1,121 @@
+# 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](#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**
+
+```python
+# 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**
+
+```python
+x = c['examples/xraydb']
+x.metadata
+```
+
+**Search**
+
+```python
+from tiled.queries import Key
+
+results = x.search(Key('element.category') == 'nonmetal')
+```
+
+**Fetch items**
+
+```python
+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**
+
+```python
+# 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**
+
+```python
+# 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**
+
+```python
+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._
+
+```python
+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](#10-minutes-to-tiled) for an expanded version.