atomscale 0.18.0__tar.gz → 0.20.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. {atomscale-0.18.0/src/atomscale.egg-info → atomscale-0.20.0}/PKG-INFO +1 -1
  2. {atomscale-0.18.0 → atomscale-0.20.0}/docs/guides/analysis-results.rst +34 -0
  3. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/client.py +259 -0
  4. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/group.py +10 -1
  5. atomscale-0.20.0/src/atomscale/rheed_metadata.py +127 -0
  6. atomscale-0.20.0/src/atomscale/samples.py +292 -0
  7. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/__init__.py +6 -0
  8. atomscale-0.20.0/src/atomscale/timeseries/physical_sample.py +137 -0
  9. {atomscale-0.18.0 → atomscale-0.20.0/src/atomscale.egg-info}/PKG-INFO +1 -1
  10. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale.egg-info/SOURCES.txt +5 -0
  11. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale.egg-info/scm_file_list.json +5 -0
  12. atomscale-0.20.0/src/atomscale.egg-info/scm_version.json +8 -0
  13. atomscale-0.20.0/tests/test_physical_sample_timeseries.py +290 -0
  14. atomscale-0.20.0/tests/test_samples.py +421 -0
  15. atomscale-0.18.0/src/atomscale.egg-info/scm_version.json +0 -8
  16. {atomscale-0.18.0 → atomscale-0.20.0}/.github/workflows/release.yml +0 -0
  17. {atomscale-0.18.0 → atomscale-0.20.0}/.github/workflows/testing.yml +0 -0
  18. {atomscale-0.18.0 → atomscale-0.20.0}/.github/workflows/upgrade_dependencies.yml +0 -0
  19. {atomscale-0.18.0 → atomscale-0.20.0}/.gitignore +0 -0
  20. {atomscale-0.18.0 → atomscale-0.20.0}/.pre-commit-config.yaml +0 -0
  21. {atomscale-0.18.0 → atomscale-0.20.0}/CHANGELOG.md +0 -0
  22. {atomscale-0.18.0 → atomscale-0.20.0}/LICENSE +0 -0
  23. {atomscale-0.18.0 → atomscale-0.20.0}/MANIFEST.in +0 -0
  24. {atomscale-0.18.0 → atomscale-0.20.0}/README.md +0 -0
  25. {atomscale-0.18.0 → atomscale-0.20.0}/atomicds-shim-dist/pyproject.toml +0 -0
  26. {atomscale-0.18.0 → atomscale-0.20.0}/docs/Makefile +0 -0
  27. {atomscale-0.18.0 → atomscale-0.20.0}/docs/_static/AtomscaleLogoFull.png +0 -0
  28. {atomscale-0.18.0 → atomscale-0.20.0}/docs/_static/custom.css +0 -0
  29. {atomscale-0.18.0 → atomscale-0.20.0}/docs/_templates/custom-class-template.rst +0 -0
  30. {atomscale-0.18.0 → atomscale-0.20.0}/docs/_templates/custom-module-template.rst +0 -0
  31. {atomscale-0.18.0 → atomscale-0.20.0}/docs/conf.py +0 -0
  32. {atomscale-0.18.0 → atomscale-0.20.0}/docs/guides/monitor-live.rst +0 -0
  33. {atomscale-0.18.0 → atomscale-0.20.0}/docs/guides/quickstart.rst +0 -0
  34. {atomscale-0.18.0 → atomscale-0.20.0}/docs/guides/search-and-download.rst +0 -0
  35. {atomscale-0.18.0 → atomscale-0.20.0}/docs/guides/stream-rheed.rst +0 -0
  36. {atomscale-0.18.0 → atomscale-0.20.0}/docs/guides/stream-timeseries.rst +0 -0
  37. {atomscale-0.18.0 → atomscale-0.20.0}/docs/guides/upload-files.rst +0 -0
  38. {atomscale-0.18.0 → atomscale-0.20.0}/docs/index.rst +0 -0
  39. {atomscale-0.18.0 → atomscale-0.20.0}/docs/make.bat +0 -0
  40. {atomscale-0.18.0 → atomscale-0.20.0}/docs/modules.rst +0 -0
  41. {atomscale-0.18.0 → atomscale-0.20.0}/examples/changepoints.ipynb +0 -0
  42. {atomscale-0.18.0 → atomscale-0.20.0}/examples/general_use.ipynb +0 -0
  43. {atomscale-0.18.0 → atomscale-0.20.0}/examples/rheed_streaming.ipynb +0 -0
  44. {atomscale-0.18.0 → atomscale-0.20.0}/examples/timeseries_polling.ipynb +0 -0
  45. {atomscale-0.18.0 → atomscale-0.20.0}/examples/vxwse2-placeholder/task1_films.ipynb +0 -0
  46. {atomscale-0.18.0 → atomscale-0.20.0}/examples/vxwse2-placeholder/task1_sapphire.ipynb +0 -0
  47. {atomscale-0.18.0 → atomscale-0.20.0}/examples/vxwse2-placeholder/task2_composition.ipynb +0 -0
  48. {atomscale-0.18.0 → atomscale-0.20.0}/pyproject.toml +0 -0
  49. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.10.txt +0 -0
  50. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.10_extras.txt +0 -0
  51. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.11.txt +0 -0
  52. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.11_extras.txt +0 -0
  53. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.12.txt +0 -0
  54. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.12_extras.txt +0 -0
  55. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.13.txt +0 -0
  56. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-macos-latest_py3.13_extras.txt +0 -0
  57. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.10.txt +0 -0
  58. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.10_extras.txt +0 -0
  59. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.11.txt +0 -0
  60. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.11_extras.txt +0 -0
  61. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.12.txt +0 -0
  62. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.12_extras.txt +0 -0
  63. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.13.txt +0 -0
  64. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-ubuntu-latest_py3.13_extras.txt +0 -0
  65. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.10.txt +0 -0
  66. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.10_extras.txt +0 -0
  67. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.11.txt +0 -0
  68. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.11_extras.txt +0 -0
  69. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.12.txt +0 -0
  70. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.12_extras.txt +0 -0
  71. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.13.txt +0 -0
  72. {atomscale-0.18.0 → atomscale-0.20.0}/requirements/requirements-windows-latest_py3.13_extras.txt +0 -0
  73. {atomscale-0.18.0 → atomscale-0.20.0}/scripts/ci_auth_preflight.py +0 -0
  74. {atomscale-0.18.0 → atomscale-0.20.0}/setup.cfg +0 -0
  75. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomicds/__init__.py +0 -0
  76. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/__init__.py +0 -0
  77. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/core/__init__.py +0 -0
  78. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/core/client.py +0 -0
  79. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/core/files.py +0 -0
  80. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/core/utils.py +0 -0
  81. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/__init__.py +0 -0
  82. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/changepoint.py +0 -0
  83. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/ellipsometry.py +0 -0
  84. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/embeddings.py +0 -0
  85. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/metrology.py +0 -0
  86. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/optical.py +0 -0
  87. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/photoluminescence.py +0 -0
  88. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/raman.py +0 -0
  89. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/recipe.py +0 -0
  90. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/rheed_image.py +0 -0
  91. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/rheed_video.py +0 -0
  92. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/similarity_trajectory.py +0 -0
  93. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/tool_state.py +0 -0
  94. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/unknown.py +0 -0
  95. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/xps.py +0 -0
  96. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/results/xrd.py +0 -0
  97. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/similarity/__init__.py +0 -0
  98. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/similarity/embedding_provider.py +0 -0
  99. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/similarity/polling.py +0 -0
  100. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/similarity/provider.py +0 -0
  101. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/streaming/Cargo.lock +0 -0
  102. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/streaming/Cargo.toml +0 -0
  103. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/streaming/__init__.py +0 -0
  104. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/streaming/rheed_stream.py +0 -0
  105. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/streaming/rheed_stream.pyi +0 -0
  106. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/streaming/src/initialize.rs +0 -0
  107. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/streaming/src/lib.rs +0 -0
  108. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/streaming/src/timeseries.rs +0 -0
  109. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/streaming/src/upload.rs +0 -0
  110. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/streaming/src/utils.rs +0 -0
  111. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/_polling_utils.py +0 -0
  112. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/align.py +0 -0
  113. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/ellipsometry.py +0 -0
  114. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/metrology.py +0 -0
  115. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/optical.py +0 -0
  116. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/polling.py +0 -0
  117. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/provider.py +0 -0
  118. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/recipe.py +0 -0
  119. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/registry.py +0 -0
  120. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/rheed.py +0 -0
  121. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/sample.py +0 -0
  122. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale/timeseries/tool_state.py +0 -0
  123. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale.egg-info/dependency_links.txt +0 -0
  124. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale.egg-info/requires.txt +0 -0
  125. {atomscale-0.18.0 → atomscale-0.20.0}/src/atomscale.egg-info/top_level.txt +0 -0
  126. {atomscale-0.18.0 → atomscale-0.20.0}/tests/__init__.py +0 -0
  127. {atomscale-0.18.0 → atomscale-0.20.0}/tests/_mock_http_server.py +0 -0
  128. {atomscale-0.18.0 → atomscale-0.20.0}/tests/conftest.py +0 -0
  129. {atomscale-0.18.0 → atomscale-0.20.0}/tests/data/test_rheed.mp4 +0 -0
  130. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_align.py +0 -0
  131. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_atomicds_alias.py +0 -0
  132. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_changepoint.py +0 -0
  133. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_client.py +0 -0
  134. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_core.py +0 -0
  135. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_ellipsometry.py +0 -0
  136. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_embeddings.py +0 -0
  137. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_metrology.py +0 -0
  138. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_optical.py +0 -0
  139. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_photoluminescence.py +0 -0
  140. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_polling.py +0 -0
  141. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_raman.py +0 -0
  142. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_recipe.py +0 -0
  143. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_rheed_embedding.py +0 -0
  144. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_rheed_image.py +0 -0
  145. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_rheed_stream.py +0 -0
  146. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_rheed_timeseries.py +0 -0
  147. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_rheed_video.py +0 -0
  148. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_similarity_matches.py +0 -0
  149. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_similarity_trajectory.py +0 -0
  150. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_timeseries_stream.py +0 -0
  151. {atomscale-0.18.0 → atomscale-0.20.0}/tests/test_xps.py +0 -0
  152. {atomscale-0.18.0 → atomscale-0.20.0}/uv.lock +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: atomscale
3
- Version: 0.18.0
3
+ Version: 0.20.0
4
4
  Summary: Python SDK for Atomscale.
5
5
  Author-email: Atomscale <info@atomscale.ai>
6
6
  License: GPL-3.0-only
@@ -97,6 +97,40 @@ number — with :meth:`~atomscale.client.Client.get_frame_masks`:
97
97
 
98
98
  masks = client.get_frame_masks(data_id, decode=True) # {frame_number: (H, W) array}
99
99
 
100
+ Sample-Level Results
101
+ --------------------
102
+
103
+ Some results are computed per *physical sample* rather than per data item —
104
+ ``rheed_quality`` and ``composition_metric`` are compiled from a sample's
105
+ constituent RHEED videos into one series each. Fetch them with
106
+ :meth:`~atomscale.client.Client.get_physical_sample_timeseries`:
107
+
108
+ .. code-block:: python
109
+
110
+ ts = client.get_physical_sample_timeseries(
111
+ physical_sample_id, property_names=["rheed_quality"]
112
+ )
113
+
114
+ # Long form: one row per (property, sample-point). Reduce to a scalar yourself.
115
+ q = ts.loc[ts.property_name == "rheed_quality", "value"].dropna()
116
+ print(q.mean())
117
+
118
+ The frame is long (not wide) because distinct properties can have different
119
+ axes, so a wide join on ``real_time_seconds`` would mis-align them. ``value`` is
120
+ ``NaN`` for gaps; provenance columns (``result_id``, ``last_updated``,
121
+ ``generating_dbos_workflow_id``) travel alongside, and per-property
122
+ ``constituent_data_ids`` are in ``ts.attrs["constituent_data_ids"]``.
123
+ ``property_names`` filters client-side; omit it for all properties.
124
+
125
+ The same metrics are attached to :meth:`~atomscale.client.Client.get_physical_sample`
126
+ results as ``sample_metrics`` (pass ``include_sample_metrics=False`` to skip the
127
+ extra request):
128
+
129
+ .. code-block:: python
130
+
131
+ sample = client.get_physical_sample(physical_sample_id)
132
+ print(sample.sample_metrics) # None if the sample has no computed metrics
133
+
100
134
  Embedding Vectors
101
135
  -----------------
102
136
 
@@ -40,7 +40,17 @@ from atomscale.results import (
40
40
  decode_mask_rle,
41
41
  )
42
42
  from atomscale.results.group import PhysicalSampleResult, ProjectResult
43
+ from atomscale.rheed_metadata import rheed_azimuths_to_dataframe
44
+ from atomscale.samples import (
45
+ ai_summaries_to_dataframe,
46
+ ai_summary_row,
47
+ process_steps_to_dataframe,
48
+ spatial_annotations_to_dataframe,
49
+ )
43
50
  from atomscale.timeseries.align import align_timeseries
51
+ from atomscale.timeseries.physical_sample import (
52
+ physical_sample_timeseries_to_dataframe,
53
+ )
44
54
  from atomscale.timeseries.registry import get_provider
45
55
 
46
56
  TimeseriesDomain = Literal["rheed", "optical", "tool_state"]
@@ -717,6 +727,39 @@ class Client(BaseClient):
717
727
  ts_df = provider.attach_frame_masks(ts_df, mask_rows) # type: ignore[arg-type]
718
728
  return ts_df
719
729
 
730
+ def get_rheed_azimuths(self, data_ids: str | list[str]) -> DataFrame:
731
+ """Per-azimuth metadata for rotating RHEED recordings.
732
+
733
+ For each seed frame of a rotating video this returns both the rotation
734
+ angle it sits at and the crystallographic azimuth the production
735
+ classifier assigned it. The angle depends on where the substrate happened
736
+ to be parked, so the same azimuth appears at different angles in different
737
+ recordings of one sample; the label is the stable identity, and so the
738
+ right key for aligning or concatenating series across recordings.
739
+
740
+ Args:
741
+ data_ids: Data ID or list of data IDs of rotating RHEED videos.
742
+
743
+ Returns:
744
+ DataFrame: One row per (data item, seed frame) with columns
745
+ ``data_id``, ``seed_frame``, ``angle_degrees``, ``azimuth_label``
746
+ (``"100"`` / ``"110"`` / ``"210"``, or ``None`` when the classifier
747
+ could not call it), ``label_confidence``, ``crystal_system`` and
748
+ ``surface_miller``. Data items with no rotating configuration
749
+ contribute no rows.
750
+ """
751
+ if isinstance(data_ids, str):
752
+ data_ids = [data_ids]
753
+
754
+ payload = self._get(
755
+ sub_url="configuration/rheed/video/", params={"data_ids": data_ids}
756
+ )
757
+ if payload is None:
758
+ return rheed_azimuths_to_dataframe([])
759
+ return rheed_azimuths_to_dataframe(
760
+ payload if isinstance(payload, list) else [payload]
761
+ )
762
+
720
763
  def get_frame(
721
764
  self,
722
765
  data_id: str,
@@ -1066,6 +1109,7 @@ class Client(BaseClient):
1066
1109
  *,
1067
1110
  include_organization_data: bool = True,
1068
1111
  align: bool | str = False,
1112
+ include_sample_metrics: bool = True,
1069
1113
  ) -> PhysicalSampleResult:
1070
1114
  """Get all data for a physical sample.
1071
1115
 
@@ -1073,6 +1117,11 @@ class Client(BaseClient):
1073
1117
  physical_sample_id: Identifier of the physical sample.
1074
1118
  include_organization_data: Whether to include organization data. Defaults to True.
1075
1119
  align: Whether to align timeseries data. If truthy, an aligned DataFrame is returned.
1120
+ include_sample_metrics: Whether to also fetch the sample-scoped computed
1121
+ timeseries results (``rheed_quality``, ``composition_metric``, …) and
1122
+ expose them on ``PhysicalSampleResult.sample_metrics``. Defaults to True.
1123
+ This is one extra request; set ``False`` to skip it. See
1124
+ :meth:`get_physical_sample_timeseries`.
1076
1125
  """
1077
1126
  physical_samples: list[dict] | None = self._get( # type: ignore # noqa: PGH003
1078
1127
  sub_url="physical_samples/",
@@ -1113,12 +1162,222 @@ class Client(BaseClient):
1113
1162
  else None
1114
1163
  )
1115
1164
  sample_id = physical_sample_id
1165
+
1166
+ # Sample-scoped computed metrics live in a separate table reached by a
1167
+ # dedicated endpoint (not part of the per-data-item curated join above).
1168
+ # This is best-effort enrichment: it is default-enabled and must never
1169
+ # abort an otherwise-successful sample fetch (nor a ``get_project``
1170
+ # aggregation that loops over samples). A 404 (``_get`` -> None) simply
1171
+ # yields no metrics; any other HTTP error or transport failure is caught
1172
+ # and surfaced as a warning, leaving ``sample_metrics`` None. Callers who
1173
+ # need the metrics to fail loudly use :meth:`get_physical_sample_timeseries`.
1174
+ sample_metrics: DataFrame | None = None
1175
+ if include_sample_metrics:
1176
+ try:
1177
+ raw_metrics = self._get(
1178
+ sub_url=f"physical_samples/{physical_sample_id}/timeseries/"
1179
+ )
1180
+ if raw_metrics is not None:
1181
+ sample_metrics = physical_sample_timeseries_to_dataframe(
1182
+ raw_metrics
1183
+ ) # type: ignore[arg-type]
1184
+ except (ClientError, RequestException) as exc:
1185
+ warnings.warn(
1186
+ f"Could not fetch sample metrics for physical sample "
1187
+ f"'{physical_sample_id}': {exc}. Returning the sample without "
1188
+ "them; call get_physical_sample_timeseries(...) directly to see "
1189
+ "the error, or pass include_sample_metrics=False to skip this.",
1190
+ stacklevel=2,
1191
+ )
1192
+
1116
1193
  return PhysicalSampleResult(
1117
1194
  physical_sample_id=sample_id,
1118
1195
  physical_sample_name=sample_name,
1119
1196
  data_results=results,
1120
1197
  aligned_timeseries=ts_aligned,
1121
1198
  non_timeseries=non_timeseries,
1199
+ sample_metrics=sample_metrics,
1200
+ )
1201
+
1202
+ def get_physical_sample_timeseries(
1203
+ self,
1204
+ physical_sample_id: str,
1205
+ *,
1206
+ property_names: list[str] | None = None,
1207
+ ) -> DataFrame:
1208
+ """Current sample-scoped computed timeseries results for a physical sample.
1209
+
1210
+ Returns the latest row per property (``rheed_quality``,
1211
+ ``composition_metric``, …) from the ``physical_sample_timeseries_results``
1212
+ table — the outputs of per-sample DBOS workflows, content-addressed by
1213
+ their constituent ``data_id`` set. These are the headline "sample result,"
1214
+ distinct from :meth:`get_physical_sample`'s ``aligned_timeseries``, which
1215
+ only re-joins each constituent data item's own curated RHEED series.
1216
+
1217
+ The series are returned faithfully (no scalar reduction): callers wanting a
1218
+ single number reduce the returned series themselves.
1219
+
1220
+ Args:
1221
+ physical_sample_id: Identifier of the physical sample.
1222
+ property_names: Restrict the result to these properties, e.g.
1223
+ ``["rheed_quality"]``. Filtered client-side (the endpoint has no
1224
+ filter param yet). ``None`` (default) returns all properties.
1225
+
1226
+ Returns:
1227
+ DataFrame: Long form — one row per (property, sample-point) — with
1228
+ columns ``property_name``, ``real_time_seconds``, ``value`` (float,
1229
+ ``NaN`` for gaps), ``result_id``, ``last_updated``, and
1230
+ ``generating_dbos_workflow_id``. Long (not wide) because distinct
1231
+ properties can have different axes, so a wide join on
1232
+ ``real_time_seconds`` would mis-align them. Per-property
1233
+ ``constituent_data_ids`` are in ``df.attrs["constituent_data_ids"]``.
1234
+ A sample with no sample-scoped metrics yields an empty DataFrame.
1235
+
1236
+ Raises:
1237
+ ClientError: If the physical sample does not exist (404).
1238
+ """
1239
+ raw = self._get(sub_url=f"physical_samples/{physical_sample_id}/timeseries/")
1240
+ if raw is None:
1241
+ raise ClientError(
1242
+ f"No physical sample found with id '{physical_sample_id}' "
1243
+ "(physical_samples/{id}/timeseries/ returned 404).",
1244
+ status_code=404,
1245
+ )
1246
+ return physical_sample_timeseries_to_dataframe( # type: ignore[arg-type]
1247
+ raw, property_names=property_names
1248
+ )
1249
+
1250
+ def get_process_steps(self, physical_sample_id: str) -> DataFrame:
1251
+ """The physical sample's process steps — its temporal phases.
1252
+
1253
+ A step groups the data items whose acquisition windows cluster together,
1254
+ so one sample's run splits into the phases it actually went through
1255
+ (e.g. a substrate anneal, then a growth, then a cooldown). Steps are the
1256
+ natural scope for a per-run report: the newest step is "this run", and
1257
+ the earlier ones are its history.
1258
+
1259
+ Args:
1260
+ physical_sample_id: Identifier of the physical sample.
1261
+
1262
+ Returns:
1263
+ DataFrame: One row per step ordered by ``step_index``, with columns
1264
+ ``step_index``, ``process_step_id``, ``name`` (the human/material
1265
+ label, ``None`` until set), ``start_unix_ms_utc`` /
1266
+ ``end_unix_ms_utc``, ``duration_seconds``, the tz-aware
1267
+ ``start_datetime`` / ``end_datetime``, ``n_data_ids``, ``data_ids``
1268
+ (tuple of the step's data items), and ``last_updated``. A sample
1269
+ whose steps have never been computed yields an empty DataFrame.
1270
+
1271
+ Raises:
1272
+ ClientError: If the physical sample does not exist (404).
1273
+ """
1274
+ raw = self._get(sub_url=f"physical_samples/{physical_sample_id}/process_steps")
1275
+ if raw is None:
1276
+ raise ClientError(
1277
+ f"No physical sample found with id '{physical_sample_id}' "
1278
+ "(physical_samples/{id}/process_steps returned 404).",
1279
+ status_code=404,
1280
+ )
1281
+ return process_steps_to_dataframe(raw) # type: ignore[arg-type]
1282
+
1283
+ def get_spatial_annotations(
1284
+ self,
1285
+ physical_sample_id: str,
1286
+ *,
1287
+ property_name: str | None = None,
1288
+ char_source_type: str | None = None,
1289
+ x_range: tuple[float | None, float | None] = (None, None),
1290
+ y_range: tuple[float | None, float | None] = (None, None),
1291
+ ) -> DataFrame:
1292
+ """Spatially-resolved property values pinned to a sample's surface.
1293
+
1294
+ Each annotation is one property measured at one position on the sample —
1295
+ an XPS composition ratio stepped across a wafer, a thickness from a
1296
+ mapped ellipsometry scan — which is what a spatial (wafer-map) view of a
1297
+ run is built from.
1298
+
1299
+ Args:
1300
+ physical_sample_id: Identifier of the physical sample.
1301
+ property_name: Restrict to a single property, e.g. ``"sr_ti_ratio"``.
1302
+ char_source_type: Restrict to the technique that produced the values,
1303
+ e.g. ``"xps"``.
1304
+ x_range: Inclusive ``(min, max)`` bounding-box filter on ``coord_x``.
1305
+ The endpoint applies a coordinate filter only when *both* bounds
1306
+ are given, so a half-open range is ignored server-side.
1307
+ y_range: Inclusive ``(min, max)`` bounding-box filter on ``coord_y``,
1308
+ with the same both-bounds requirement as ``x_range``.
1309
+
1310
+ Returns:
1311
+ DataFrame: One row per annotated point with columns
1312
+ ``annotation_id``, ``data_id``, ``char_source_type``,
1313
+ ``property_name``, ``property_value``, ``property_unit``,
1314
+ ``coord_x`` / ``coord_y`` / ``coord_z``, ``coord_ref_frame``,
1315
+ ``coord_units``, ``metadata``, and ``last_updated``. Sorted by
1316
+ property then position. A sample with no annotations — or a filter
1317
+ that matches none — yields an empty DataFrame.
1318
+
1319
+ Raises:
1320
+ ClientError: If the physical sample does not exist (404).
1321
+ """
1322
+ raw = self._get(
1323
+ sub_url=f"physical_samples/{physical_sample_id}/annotations/",
1324
+ params={
1325
+ "property_name": property_name,
1326
+ "char_source_type": char_source_type,
1327
+ "x_min": x_range[0],
1328
+ "x_max": x_range[1],
1329
+ "y_min": y_range[0],
1330
+ "y_max": y_range[1],
1331
+ },
1332
+ )
1333
+ # An existing sample with no annotations returns ``[]``, which ``_get``
1334
+ # hands back as an empty list; only a missing sample 404s to ``None``.
1335
+ if raw is None:
1336
+ raise ClientError(
1337
+ f"No physical sample found with id '{physical_sample_id}' "
1338
+ "(physical_samples/{id}/annotations/ returned 404).",
1339
+ status_code=404,
1340
+ )
1341
+ return spatial_annotations_to_dataframe(raw) # type: ignore[arg-type]
1342
+
1343
+ def get_ai_summaries(self, data_ids: str | list[str]) -> DataFrame:
1344
+ """Agent-written summaries for one or more data items.
1345
+
1346
+ The summary is generated asynchronously, so every requested data id gets
1347
+ a row carrying its ``task_status``: ``"available"`` when a summary
1348
+ exists, ``"pending"`` while the summarization workflow is still running,
1349
+ and ``"not_found"`` when neither is true. That makes an un-summarized
1350
+ item visible to a caller rendering a report rather than silently absent.
1351
+
1352
+ Args:
1353
+ data_ids: Data ID or list of data IDs from the data catalogue.
1354
+
1355
+ Returns:
1356
+ DataFrame: One row per requested data id, in request order, with
1357
+ columns ``data_id``, ``task_status``, ``summary_id``, ``content``
1358
+ (the prose summary), ``structured_content`` (the agent's full
1359
+ structured output), ``generation_model``, ``generation_timestamp``,
1360
+ ``user_feedback``, and ``workflow_id``. Summary-note columns are
1361
+ ``None`` for rows whose status is not ``"available"``.
1362
+ """
1363
+ if isinstance(data_ids, str):
1364
+ data_ids = [data_ids]
1365
+
1366
+ # The endpoint is per-data-item, so fan the requests out rather than
1367
+ # walking them serially.
1368
+ with _make_progress(self.mute_bars, False) as progress:
1369
+ payloads = self._multi_thread(
1370
+ lambda data_id: self._get(sub_url=f"summary/{data_id}"),
1371
+ [{"data_id": data_id} for data_id in data_ids],
1372
+ progress,
1373
+ progress_description="Obtaining AI summaries",
1374
+ )
1375
+
1376
+ return ai_summaries_to_dataframe(
1377
+ [
1378
+ ai_summary_row(data_id, payload)
1379
+ for data_id, payload in zip(data_ids, payloads, strict=True)
1380
+ ]
1122
1381
  )
1123
1382
 
1124
1383
  def get_project(
@@ -14,13 +14,22 @@ class PhysicalSampleResult(MSONable):
14
14
  data_results: list,
15
15
  aligned_timeseries: DataFrame | None,
16
16
  non_timeseries: list,
17
+ sample_metrics: DataFrame | None = None,
17
18
  ):
18
- """Aggregated results for a physical sample."""
19
+ """Aggregated results for a physical sample.
20
+
21
+ ``sample_metrics`` holds the sample-scoped computed timeseries results
22
+ (``rheed_quality``, ``composition_metric``, …) in the long form returned
23
+ by :meth:`~atomscale.client.Client.get_physical_sample_timeseries`, or
24
+ ``None`` when they were not fetched. It is distinct from
25
+ ``aligned_timeseries``, which is the per-data-item curated join.
26
+ """
19
27
  self.physical_sample_id = physical_sample_id
20
28
  self.physical_sample_name = physical_sample_name
21
29
  self.data_results = data_results
22
30
  self.aligned_timeseries = aligned_timeseries
23
31
  self.non_timeseries = non_timeseries
32
+ self.sample_metrics = sample_metrics
24
33
 
25
34
 
26
35
  class ProjectResult(MSONable):
@@ -0,0 +1,127 @@
1
+ """Parse per-azimuth RHEED metadata for a rotating-substrate recording.
2
+
3
+ ``GET /configuration/rheed/video/`` carries, for each seed frame of a rotating
4
+ video, both the rotation angle the frame sits at (``seed_frame_angles``) and the
5
+ crystallographic azimuth the production classifier assigned it
6
+ (``api_configuration.azimuth_labels`` — one of ``"100"`` / ``"110"`` / ``"210"``,
7
+ or ``None`` when it could not be called), plus the fit detail behind that call in
8
+ ``azimuth_label_meta``.
9
+
10
+ The distinction matters when comparing recordings: the rotation angle is a
11
+ property of how the substrate happened to be parked, so the *same* azimuth turns
12
+ up at different angles in different recordings of the same sample. The
13
+ crystallographic label is the stable identity, and therefore the correct key for
14
+ aligning or concatenating series across recordings.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ from collections.abc import Mapping, Sequence
20
+ from typing import Any
21
+
22
+ import pandas as pd
23
+ from pandas import DataFrame
24
+
25
+ # One row per (data item, seed frame).
26
+ RHEED_AZIMUTH_COLUMNS: tuple[str, ...] = (
27
+ "data_id",
28
+ "seed_frame",
29
+ "angle_degrees",
30
+ "azimuth_label",
31
+ "label_confidence",
32
+ "crystal_system",
33
+ "surface_miller",
34
+ )
35
+
36
+
37
+ def _empty() -> DataFrame:
38
+ frame = DataFrame({c: [] for c in RHEED_AZIMUTH_COLUMNS})
39
+ frame["seed_frame"] = frame["seed_frame"].astype("int64")
40
+ frame["angle_degrees"] = frame["angle_degrees"].astype("float64")
41
+ frame["label_confidence"] = frame["label_confidence"].astype("float64")
42
+ return frame
43
+
44
+
45
+ def rheed_azimuths_to_dataframe(payload: Sequence[Mapping[str, Any]]) -> DataFrame:
46
+ """Convert a ``list[RheedVideoConfigurationResponse]`` to one row per azimuth.
47
+
48
+ Args:
49
+ payload: Decoded response body — one entry per requested data id, each
50
+ with ``data_id``, ``seed_frame_angles`` (seed frame -> degrees) and an
51
+ ``api_configuration`` carrying ``azimuth_labels`` (seed frame ->
52
+ label) and ``azimuth_label_meta`` (seed frame -> fit detail).
53
+
54
+ Returns:
55
+ DataFrame: The columns in :data:`RHEED_AZIMUTH_COLUMNS`, sorted by
56
+ ``data_id`` then ``seed_frame``. ``azimuth_label`` is ``None`` for a seed
57
+ frame the classifier could not label, so callers can fall back to the
58
+ angle rather than inventing an identity. Non-rotating or unconfigured
59
+ entries contribute no rows; an empty payload yields an empty frame.
60
+ """
61
+ rows: list[dict[str, Any]] = []
62
+ for entry in payload or []:
63
+ data_id = entry.get("data_id")
64
+ angles = entry.get("seed_frame_angles") or {}
65
+ api_configuration = entry.get("api_configuration") or {}
66
+ labels = api_configuration.get("azimuth_labels") or {}
67
+ meta = api_configuration.get("azimuth_label_meta") or {}
68
+
69
+ # Seed frames come from the angle map: it is the endpoint's own record of
70
+ # which frames this recording actually has, whereas the label map may be
71
+ # partial (an unlabelled azimuth is simply absent).
72
+ for seed_frame, angle in angles.items():
73
+ detail = meta.get(seed_frame) or {}
74
+ surface = detail.get("surface")
75
+ rows.append(
76
+ {
77
+ "data_id": str(data_id),
78
+ "seed_frame": int(seed_frame),
79
+ "angle_degrees": float(angle)
80
+ if angle is not None
81
+ else float("nan"),
82
+ "azimuth_label": labels.get(seed_frame),
83
+ "label_confidence": (
84
+ float(detail["confidence"])
85
+ if detail.get("confidence") is not None
86
+ else float("nan")
87
+ ),
88
+ "crystal_system": detail.get("system"),
89
+ # A Miller index arrives as a list; join it so the column stays
90
+ # scalar and groupable.
91
+ "surface_miller": (
92
+ "".join(str(_i) for _i in surface)
93
+ if isinstance(surface, list | tuple)
94
+ else surface
95
+ ),
96
+ }
97
+ )
98
+
99
+ if not rows:
100
+ return _empty()
101
+
102
+ return (
103
+ DataFrame(rows)[list(RHEED_AZIMUTH_COLUMNS)]
104
+ .sort_values(["data_id", "seed_frame"], kind="stable")
105
+ .reset_index(drop=True)
106
+ )
107
+
108
+
109
+ def azimuth_label_by_seed_frame(
110
+ azimuths: DataFrame, data_id: str
111
+ ) -> dict[int, str | None]:
112
+ """``{seed_frame: azimuth_label}`` for one data item, for joining onto series.
113
+
114
+ Args:
115
+ azimuths: A frame from :func:`rheed_azimuths_to_dataframe`.
116
+ data_id: The data item to select.
117
+
118
+ Returns:
119
+ dict: Seed frame -> label, including seed frames whose label is ``None``.
120
+ """
121
+ if not len(azimuths):
122
+ return {}
123
+ mine = azimuths[azimuths["data_id"].astype(str) == str(data_id)]
124
+ return {
125
+ int(row.seed_frame): (None if pd.isna(row.azimuth_label) else row.azimuth_label)
126
+ for row in mine.itertuples()
127
+ }