atomscale 0.18.0__tar.gz → 0.19.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 (149) hide show
  1. {atomscale-0.18.0 → atomscale-0.19.0}/PKG-INFO +1 -1
  2. {atomscale-0.18.0 → atomscale-0.19.0}/docs/guides/analysis-results.rst +34 -0
  3. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/client.py +86 -0
  4. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/group.py +10 -1
  5. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/__init__.py +6 -0
  6. atomscale-0.19.0/src/atomscale/timeseries/physical_sample.py +137 -0
  7. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale.egg-info/PKG-INFO +1 -1
  8. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale.egg-info/SOURCES.txt +2 -0
  9. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale.egg-info/scm_file_list.json +2 -0
  10. atomscale-0.19.0/src/atomscale.egg-info/scm_version.json +8 -0
  11. atomscale-0.19.0/tests/test_physical_sample_timeseries.py +290 -0
  12. atomscale-0.18.0/src/atomscale.egg-info/scm_version.json +0 -8
  13. {atomscale-0.18.0 → atomscale-0.19.0}/.github/workflows/release.yml +0 -0
  14. {atomscale-0.18.0 → atomscale-0.19.0}/.github/workflows/testing.yml +0 -0
  15. {atomscale-0.18.0 → atomscale-0.19.0}/.github/workflows/upgrade_dependencies.yml +0 -0
  16. {atomscale-0.18.0 → atomscale-0.19.0}/.gitignore +0 -0
  17. {atomscale-0.18.0 → atomscale-0.19.0}/.pre-commit-config.yaml +0 -0
  18. {atomscale-0.18.0 → atomscale-0.19.0}/CHANGELOG.md +0 -0
  19. {atomscale-0.18.0 → atomscale-0.19.0}/LICENSE +0 -0
  20. {atomscale-0.18.0 → atomscale-0.19.0}/MANIFEST.in +0 -0
  21. {atomscale-0.18.0 → atomscale-0.19.0}/README.md +0 -0
  22. {atomscale-0.18.0 → atomscale-0.19.0}/atomicds-shim-dist/pyproject.toml +0 -0
  23. {atomscale-0.18.0 → atomscale-0.19.0}/docs/Makefile +0 -0
  24. {atomscale-0.18.0 → atomscale-0.19.0}/docs/_static/AtomscaleLogoFull.png +0 -0
  25. {atomscale-0.18.0 → atomscale-0.19.0}/docs/_static/custom.css +0 -0
  26. {atomscale-0.18.0 → atomscale-0.19.0}/docs/_templates/custom-class-template.rst +0 -0
  27. {atomscale-0.18.0 → atomscale-0.19.0}/docs/_templates/custom-module-template.rst +0 -0
  28. {atomscale-0.18.0 → atomscale-0.19.0}/docs/conf.py +0 -0
  29. {atomscale-0.18.0 → atomscale-0.19.0}/docs/guides/monitor-live.rst +0 -0
  30. {atomscale-0.18.0 → atomscale-0.19.0}/docs/guides/quickstart.rst +0 -0
  31. {atomscale-0.18.0 → atomscale-0.19.0}/docs/guides/search-and-download.rst +0 -0
  32. {atomscale-0.18.0 → atomscale-0.19.0}/docs/guides/stream-rheed.rst +0 -0
  33. {atomscale-0.18.0 → atomscale-0.19.0}/docs/guides/stream-timeseries.rst +0 -0
  34. {atomscale-0.18.0 → atomscale-0.19.0}/docs/guides/upload-files.rst +0 -0
  35. {atomscale-0.18.0 → atomscale-0.19.0}/docs/index.rst +0 -0
  36. {atomscale-0.18.0 → atomscale-0.19.0}/docs/make.bat +0 -0
  37. {atomscale-0.18.0 → atomscale-0.19.0}/docs/modules.rst +0 -0
  38. {atomscale-0.18.0 → atomscale-0.19.0}/examples/changepoints.ipynb +0 -0
  39. {atomscale-0.18.0 → atomscale-0.19.0}/examples/general_use.ipynb +0 -0
  40. {atomscale-0.18.0 → atomscale-0.19.0}/examples/rheed_streaming.ipynb +0 -0
  41. {atomscale-0.18.0 → atomscale-0.19.0}/examples/timeseries_polling.ipynb +0 -0
  42. {atomscale-0.18.0 → atomscale-0.19.0}/examples/vxwse2-placeholder/task1_films.ipynb +0 -0
  43. {atomscale-0.18.0 → atomscale-0.19.0}/examples/vxwse2-placeholder/task1_sapphire.ipynb +0 -0
  44. {atomscale-0.18.0 → atomscale-0.19.0}/examples/vxwse2-placeholder/task2_composition.ipynb +0 -0
  45. {atomscale-0.18.0 → atomscale-0.19.0}/pyproject.toml +0 -0
  46. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-macos-latest_py3.10.txt +0 -0
  47. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-macos-latest_py3.10_extras.txt +0 -0
  48. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-macos-latest_py3.11.txt +0 -0
  49. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-macos-latest_py3.11_extras.txt +0 -0
  50. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-macos-latest_py3.12.txt +0 -0
  51. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-macos-latest_py3.12_extras.txt +0 -0
  52. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-macos-latest_py3.13.txt +0 -0
  53. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-macos-latest_py3.13_extras.txt +0 -0
  54. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-ubuntu-latest_py3.10.txt +0 -0
  55. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-ubuntu-latest_py3.10_extras.txt +0 -0
  56. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-ubuntu-latest_py3.11.txt +0 -0
  57. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-ubuntu-latest_py3.11_extras.txt +0 -0
  58. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-ubuntu-latest_py3.12.txt +0 -0
  59. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-ubuntu-latest_py3.12_extras.txt +0 -0
  60. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-ubuntu-latest_py3.13.txt +0 -0
  61. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-ubuntu-latest_py3.13_extras.txt +0 -0
  62. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-windows-latest_py3.10.txt +0 -0
  63. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-windows-latest_py3.10_extras.txt +0 -0
  64. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-windows-latest_py3.11.txt +0 -0
  65. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-windows-latest_py3.11_extras.txt +0 -0
  66. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-windows-latest_py3.12.txt +0 -0
  67. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-windows-latest_py3.12_extras.txt +0 -0
  68. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-windows-latest_py3.13.txt +0 -0
  69. {atomscale-0.18.0 → atomscale-0.19.0}/requirements/requirements-windows-latest_py3.13_extras.txt +0 -0
  70. {atomscale-0.18.0 → atomscale-0.19.0}/scripts/ci_auth_preflight.py +0 -0
  71. {atomscale-0.18.0 → atomscale-0.19.0}/setup.cfg +0 -0
  72. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomicds/__init__.py +0 -0
  73. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/__init__.py +0 -0
  74. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/core/__init__.py +0 -0
  75. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/core/client.py +0 -0
  76. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/core/files.py +0 -0
  77. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/core/utils.py +0 -0
  78. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/__init__.py +0 -0
  79. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/changepoint.py +0 -0
  80. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/ellipsometry.py +0 -0
  81. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/embeddings.py +0 -0
  82. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/metrology.py +0 -0
  83. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/optical.py +0 -0
  84. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/photoluminescence.py +0 -0
  85. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/raman.py +0 -0
  86. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/recipe.py +0 -0
  87. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/rheed_image.py +0 -0
  88. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/rheed_video.py +0 -0
  89. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/similarity_trajectory.py +0 -0
  90. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/tool_state.py +0 -0
  91. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/unknown.py +0 -0
  92. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/xps.py +0 -0
  93. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/results/xrd.py +0 -0
  94. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/similarity/__init__.py +0 -0
  95. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/similarity/embedding_provider.py +0 -0
  96. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/similarity/polling.py +0 -0
  97. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/similarity/provider.py +0 -0
  98. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/streaming/Cargo.lock +0 -0
  99. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/streaming/Cargo.toml +0 -0
  100. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/streaming/__init__.py +0 -0
  101. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/streaming/rheed_stream.py +0 -0
  102. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/streaming/rheed_stream.pyi +0 -0
  103. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/streaming/src/initialize.rs +0 -0
  104. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/streaming/src/lib.rs +0 -0
  105. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/streaming/src/timeseries.rs +0 -0
  106. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/streaming/src/upload.rs +0 -0
  107. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/streaming/src/utils.rs +0 -0
  108. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/_polling_utils.py +0 -0
  109. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/align.py +0 -0
  110. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/ellipsometry.py +0 -0
  111. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/metrology.py +0 -0
  112. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/optical.py +0 -0
  113. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/polling.py +0 -0
  114. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/provider.py +0 -0
  115. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/recipe.py +0 -0
  116. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/registry.py +0 -0
  117. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/rheed.py +0 -0
  118. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/sample.py +0 -0
  119. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale/timeseries/tool_state.py +0 -0
  120. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale.egg-info/dependency_links.txt +0 -0
  121. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale.egg-info/requires.txt +0 -0
  122. {atomscale-0.18.0 → atomscale-0.19.0}/src/atomscale.egg-info/top_level.txt +0 -0
  123. {atomscale-0.18.0 → atomscale-0.19.0}/tests/__init__.py +0 -0
  124. {atomscale-0.18.0 → atomscale-0.19.0}/tests/_mock_http_server.py +0 -0
  125. {atomscale-0.18.0 → atomscale-0.19.0}/tests/conftest.py +0 -0
  126. {atomscale-0.18.0 → atomscale-0.19.0}/tests/data/test_rheed.mp4 +0 -0
  127. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_align.py +0 -0
  128. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_atomicds_alias.py +0 -0
  129. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_changepoint.py +0 -0
  130. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_client.py +0 -0
  131. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_core.py +0 -0
  132. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_ellipsometry.py +0 -0
  133. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_embeddings.py +0 -0
  134. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_metrology.py +0 -0
  135. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_optical.py +0 -0
  136. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_photoluminescence.py +0 -0
  137. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_polling.py +0 -0
  138. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_raman.py +0 -0
  139. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_recipe.py +0 -0
  140. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_rheed_embedding.py +0 -0
  141. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_rheed_image.py +0 -0
  142. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_rheed_stream.py +0 -0
  143. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_rheed_timeseries.py +0 -0
  144. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_rheed_video.py +0 -0
  145. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_similarity_matches.py +0 -0
  146. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_similarity_trajectory.py +0 -0
  147. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_timeseries_stream.py +0 -0
  148. {atomscale-0.18.0 → atomscale-0.19.0}/tests/test_xps.py +0 -0
  149. {atomscale-0.18.0 → atomscale-0.19.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.19.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
 
@@ -41,6 +41,9 @@ from atomscale.results import (
41
41
  )
42
42
  from atomscale.results.group import PhysicalSampleResult, ProjectResult
43
43
  from atomscale.timeseries.align import align_timeseries
44
+ from atomscale.timeseries.physical_sample import (
45
+ physical_sample_timeseries_to_dataframe,
46
+ )
44
47
  from atomscale.timeseries.registry import get_provider
45
48
 
46
49
  TimeseriesDomain = Literal["rheed", "optical", "tool_state"]
@@ -1066,6 +1069,7 @@ class Client(BaseClient):
1066
1069
  *,
1067
1070
  include_organization_data: bool = True,
1068
1071
  align: bool | str = False,
1072
+ include_sample_metrics: bool = True,
1069
1073
  ) -> PhysicalSampleResult:
1070
1074
  """Get all data for a physical sample.
1071
1075
 
@@ -1073,6 +1077,11 @@ class Client(BaseClient):
1073
1077
  physical_sample_id: Identifier of the physical sample.
1074
1078
  include_organization_data: Whether to include organization data. Defaults to True.
1075
1079
  align: Whether to align timeseries data. If truthy, an aligned DataFrame is returned.
1080
+ include_sample_metrics: Whether to also fetch the sample-scoped computed
1081
+ timeseries results (``rheed_quality``, ``composition_metric``, …) and
1082
+ expose them on ``PhysicalSampleResult.sample_metrics``. Defaults to True.
1083
+ This is one extra request; set ``False`` to skip it. See
1084
+ :meth:`get_physical_sample_timeseries`.
1076
1085
  """
1077
1086
  physical_samples: list[dict] | None = self._get( # type: ignore # noqa: PGH003
1078
1087
  sub_url="physical_samples/",
@@ -1113,12 +1122,89 @@ class Client(BaseClient):
1113
1122
  else None
1114
1123
  )
1115
1124
  sample_id = physical_sample_id
1125
+
1126
+ # Sample-scoped computed metrics live in a separate table reached by a
1127
+ # dedicated endpoint (not part of the per-data-item curated join above).
1128
+ # This is best-effort enrichment: it is default-enabled and must never
1129
+ # abort an otherwise-successful sample fetch (nor a ``get_project``
1130
+ # aggregation that loops over samples). A 404 (``_get`` -> None) simply
1131
+ # yields no metrics; any other HTTP error or transport failure is caught
1132
+ # and surfaced as a warning, leaving ``sample_metrics`` None. Callers who
1133
+ # need the metrics to fail loudly use :meth:`get_physical_sample_timeseries`.
1134
+ sample_metrics: DataFrame | None = None
1135
+ if include_sample_metrics:
1136
+ try:
1137
+ raw_metrics = self._get(
1138
+ sub_url=f"physical_samples/{physical_sample_id}/timeseries/"
1139
+ )
1140
+ if raw_metrics is not None:
1141
+ sample_metrics = physical_sample_timeseries_to_dataframe(
1142
+ raw_metrics
1143
+ ) # type: ignore[arg-type]
1144
+ except (ClientError, RequestException) as exc:
1145
+ warnings.warn(
1146
+ f"Could not fetch sample metrics for physical sample "
1147
+ f"'{physical_sample_id}': {exc}. Returning the sample without "
1148
+ "them; call get_physical_sample_timeseries(...) directly to see "
1149
+ "the error, or pass include_sample_metrics=False to skip this.",
1150
+ stacklevel=2,
1151
+ )
1152
+
1116
1153
  return PhysicalSampleResult(
1117
1154
  physical_sample_id=sample_id,
1118
1155
  physical_sample_name=sample_name,
1119
1156
  data_results=results,
1120
1157
  aligned_timeseries=ts_aligned,
1121
1158
  non_timeseries=non_timeseries,
1159
+ sample_metrics=sample_metrics,
1160
+ )
1161
+
1162
+ def get_physical_sample_timeseries(
1163
+ self,
1164
+ physical_sample_id: str,
1165
+ *,
1166
+ property_names: list[str] | None = None,
1167
+ ) -> DataFrame:
1168
+ """Current sample-scoped computed timeseries results for a physical sample.
1169
+
1170
+ Returns the latest row per property (``rheed_quality``,
1171
+ ``composition_metric``, …) from the ``physical_sample_timeseries_results``
1172
+ table — the outputs of per-sample DBOS workflows, content-addressed by
1173
+ their constituent ``data_id`` set. These are the headline "sample result,"
1174
+ distinct from :meth:`get_physical_sample`'s ``aligned_timeseries``, which
1175
+ only re-joins each constituent data item's own curated RHEED series.
1176
+
1177
+ The series are returned faithfully (no scalar reduction): callers wanting a
1178
+ single number reduce the returned series themselves.
1179
+
1180
+ Args:
1181
+ physical_sample_id: Identifier of the physical sample.
1182
+ property_names: Restrict the result to these properties, e.g.
1183
+ ``["rheed_quality"]``. Filtered client-side (the endpoint has no
1184
+ filter param yet). ``None`` (default) returns all properties.
1185
+
1186
+ Returns:
1187
+ DataFrame: Long form — one row per (property, sample-point) — with
1188
+ columns ``property_name``, ``real_time_seconds``, ``value`` (float,
1189
+ ``NaN`` for gaps), ``result_id``, ``last_updated``, and
1190
+ ``generating_dbos_workflow_id``. Long (not wide) because distinct
1191
+ properties can have different axes, so a wide join on
1192
+ ``real_time_seconds`` would mis-align them. Per-property
1193
+ ``constituent_data_ids`` are in ``df.attrs["constituent_data_ids"]``.
1194
+ A sample with no sample-scoped metrics yields an empty DataFrame.
1195
+
1196
+ Raises:
1197
+ ClientError: If the physical sample does not exist (404).
1198
+ """
1199
+ raw = self._get(sub_url=f"physical_samples/{physical_sample_id}/timeseries/")
1200
+ if raw is None:
1201
+ raise ClientError(
1202
+ f"No physical sample found with id '{physical_sample_id}' "
1203
+ "(physical_samples/{id}/timeseries/ returned 404).",
1204
+ status_code=404,
1205
+ )
1206
+ return physical_sample_timeseries_to_dataframe( # type: ignore[arg-type]
1207
+ raw, property_names=property_names
1122
1208
  )
1123
1209
 
1124
1210
  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):
@@ -22,6 +22,10 @@ from .align import align_timeseries
22
22
  from .ellipsometry import EllipsometryProvider
23
23
  from .metrology import MetrologyProvider
24
24
  from .optical import OpticalProvider
25
+ from .physical_sample import (
26
+ PHYSICAL_SAMPLE_TS_COLUMNS,
27
+ physical_sample_timeseries_to_dataframe,
28
+ )
25
29
  from .polling import (
26
30
  aiter_poll,
27
31
  iter_poll,
@@ -35,6 +39,7 @@ from .rheed import RHEEDProvider
35
39
  from .tool_state import ToolStateProvider
36
40
 
37
41
  __all__ = [
42
+ "PHYSICAL_SAMPLE_TS_COLUMNS",
38
43
  "EllipsometryProvider",
39
44
  "MetrologyProvider",
40
45
  "OpticalProvider",
@@ -46,6 +51,7 @@ __all__ = [
46
51
  "align_timeseries",
47
52
  "get_provider",
48
53
  "iter_poll",
54
+ "physical_sample_timeseries_to_dataframe",
49
55
  "properties_payload_to_dataframe",
50
56
  "start_polling_task",
51
57
  "start_polling_thread",
@@ -0,0 +1,137 @@
1
+ """Parse sample-scoped computed timeseries results.
2
+
3
+ The backend endpoint ``GET /physical_samples/{id}/timeseries/`` returns the
4
+ *current* row per computed property that per-sample DBOS workflows produce —
5
+ today ``rheed_quality`` and ``composition_metric``. Each property is a compiled
6
+ series content-addressed by its constituent ``data_id`` set; the endpoint
7
+ returns the latest row for each property.
8
+
9
+ This module converts that payload into a long-form DataFrame. Long form (rather
10
+ than a wide join on ``real_time_seconds``) because distinct properties can carry
11
+ *different* axes — different ``result_id`` / constituent-data-id sets — so a
12
+ naive wide join would silently mis-align them.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ from collections.abc import Mapping, Sequence
18
+ from typing import Any
19
+
20
+ import numpy as np
21
+ import pandas as pd
22
+ from pandas import DataFrame
23
+
24
+ # Long-form output schema (scalar columns). Per-property list-valued provenance
25
+ # (``constituent_data_ids``) is carried in ``DataFrame.attrs`` instead of a
26
+ # list-in-cell column so the frame stays flat and groupby/filter-friendly.
27
+ PHYSICAL_SAMPLE_TS_COLUMNS: tuple[str, ...] = (
28
+ "property_name",
29
+ "real_time_seconds",
30
+ "value",
31
+ "result_id",
32
+ "last_updated",
33
+ "generating_dbos_workflow_id",
34
+ )
35
+
36
+
37
+ def _float_array(values: Sequence[Any]) -> np.ndarray:
38
+ """Coerce a sequence to ``float64``, mapping ``None`` (JSON null) to ``NaN``."""
39
+ return np.array(
40
+ [np.nan if v is None else float(v) for v in values], dtype="float64"
41
+ )
42
+
43
+
44
+ def _empty_frame() -> DataFrame:
45
+ """Empty long-form frame with the standard columns and dtypes."""
46
+ frame = DataFrame({c: [] for c in PHYSICAL_SAMPLE_TS_COLUMNS})
47
+ frame["real_time_seconds"] = frame["real_time_seconds"].astype("float64")
48
+ frame["value"] = frame["value"].astype("float64")
49
+ frame["last_updated"] = pd.to_datetime(frame["last_updated"])
50
+ frame.attrs["constituent_data_ids"] = {}
51
+ return frame
52
+
53
+
54
+ def physical_sample_timeseries_to_dataframe(
55
+ payload: Mapping[str, Any],
56
+ *,
57
+ property_names: Sequence[str] | None = None,
58
+ ) -> DataFrame:
59
+ """Convert a ``PhysicalSampleTimeseriesResponse`` payload to long form.
60
+
61
+ Args:
62
+ payload: The decoded response body, with a ``"properties"`` list whose
63
+ entries carry ``property_name``, ``property_values`` (JSON ``null``
64
+ for gaps), ``real_time_seconds`` (1:1 with values), and provenance
65
+ (``result_id``, ``last_updated``, ``constituent_data_ids``,
66
+ ``generating_dbos_workflow_id``). If ``unix_times`` is present (a
67
+ backend follow-up), it is passed through as a column.
68
+ property_names: If given, keep only these properties (client-side; the
69
+ endpoint has no filter param yet). ``None`` keeps all.
70
+
71
+ Returns:
72
+ DataFrame: One row per (property, sample-point) with the columns in
73
+ :data:`PHYSICAL_SAMPLE_TS_COLUMNS` (plus ``unix_times`` when the payload
74
+ provides it). ``value`` and ``real_time_seconds`` are ``float64`` with
75
+ ``NaN`` for null gaps; ``last_updated`` is datetime. Per-property
76
+ ``constituent_data_ids`` are stored in ``df.attrs["constituent_data_ids"]``
77
+ keyed by property name. Empty / fully-filtered payloads yield an empty
78
+ frame (never an error).
79
+
80
+ Raises:
81
+ ValueError: If a property's ``property_values`` and ``real_time_seconds``
82
+ differ in length (malformed backend response).
83
+ """
84
+ properties = list(payload.get("properties") or [])
85
+
86
+ if property_names is not None:
87
+ wanted = set(property_names)
88
+ properties = [p for p in properties if p.get("property_name") in wanted]
89
+
90
+ if not properties:
91
+ return _empty_frame()
92
+
93
+ has_unix = any(p.get("unix_times") for p in properties)
94
+
95
+ frames: list[DataFrame] = []
96
+ constituent: dict[str, list] = {}
97
+ for prop in properties:
98
+ name = prop.get("property_name")
99
+ values = list(prop.get("property_values") or [])
100
+ axis = list(prop.get("real_time_seconds") or [])
101
+ if len(values) != len(axis):
102
+ raise ValueError(
103
+ f"Malformed physical-sample timeseries for property {name!r}: "
104
+ f"{len(values)} value(s) vs {len(axis)} time point(s)."
105
+ )
106
+
107
+ axis_arr = _float_array(axis)
108
+ data: dict[str, Any] = {
109
+ # Scalars broadcast to the axis length (0 rows when the axis is empty).
110
+ "property_name": name,
111
+ "real_time_seconds": axis_arr,
112
+ "value": _float_array(values),
113
+ "result_id": prop.get("result_id"),
114
+ "last_updated": prop.get("last_updated"),
115
+ "generating_dbos_workflow_id": prop.get("generating_dbos_workflow_id"),
116
+ }
117
+ if has_unix:
118
+ unix = list(prop.get("unix_times") or [])
119
+ data["unix_times"] = (
120
+ _float_array(unix)
121
+ if len(unix) == len(axis_arr)
122
+ else np.full(len(axis_arr), np.nan, dtype="float64")
123
+ )
124
+ frames.append(DataFrame(data))
125
+ constituent[name] = list(prop.get("constituent_data_ids") or [])
126
+
127
+ out = pd.concat(frames, ignore_index=True)
128
+
129
+ ordered = ["property_name", "real_time_seconds"]
130
+ if has_unix:
131
+ ordered.append("unix_times")
132
+ ordered += ["value", "result_id", "last_updated", "generating_dbos_workflow_id"]
133
+ out = out[ordered]
134
+
135
+ out["last_updated"] = pd.to_datetime(out["last_updated"], errors="coerce")
136
+ out.attrs["constituent_data_ids"] = constituent
137
+ return out
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: atomscale
3
- Version: 0.18.0
3
+ Version: 0.19.0
4
4
  Summary: Python SDK for Atomscale.
5
5
  Author-email: Atomscale <info@atomscale.ai>
6
6
  License: GPL-3.0-only
@@ -109,6 +109,7 @@ src/atomscale/timeseries/align.py
109
109
  src/atomscale/timeseries/ellipsometry.py
110
110
  src/atomscale/timeseries/metrology.py
111
111
  src/atomscale/timeseries/optical.py
112
+ src/atomscale/timeseries/physical_sample.py
112
113
  src/atomscale/timeseries/polling.py
113
114
  src/atomscale/timeseries/provider.py
114
115
  src/atomscale/timeseries/recipe.py
@@ -129,6 +130,7 @@ tests/test_embeddings.py
129
130
  tests/test_metrology.py
130
131
  tests/test_optical.py
131
132
  tests/test_photoluminescence.py
133
+ tests/test_physical_sample_timeseries.py
132
134
  tests/test_polling.py
133
135
  tests/test_raman.py
134
136
  tests/test_recipe.py
@@ -103,6 +103,7 @@
103
103
  "src/atomscale/timeseries/ellipsometry.py",
104
104
  "src/atomscale/timeseries/metrology.py",
105
105
  "src/atomscale/timeseries/optical.py",
106
+ "src/atomscale/timeseries/physical_sample.py",
106
107
  "src/atomscale/timeseries/polling.py",
107
108
  "src/atomscale/timeseries/provider.py",
108
109
  "src/atomscale/timeseries/recipe.py",
@@ -124,6 +125,7 @@
124
125
  "tests/test_metrology.py",
125
126
  "tests/test_optical.py",
126
127
  "tests/test_photoluminescence.py",
128
+ "tests/test_physical_sample_timeseries.py",
127
129
  "tests/test_polling.py",
128
130
  "tests/test_raman.py",
129
131
  "tests/test_recipe.py",
@@ -0,0 +1,8 @@
1
+ {
2
+ "tag": "0.19.0",
3
+ "distance": 0,
4
+ "node": "g0c629c9298ff4ed1babe1d158901446e10306612",
5
+ "dirty": false,
6
+ "branch": "HEAD",
7
+ "node_date": "2026-08-16"
8
+ }