From 7c00731992d6fd24b9a6861fbba29ab249f8ea52 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Mon, 31 Aug 2026 19:02:12 +0200 Subject: [PATCH] docs: publish the powder calibration schemas in the python client docs docs/python_client is tracked and is what readthedocs publishes, but it is generated - update_version.sh copies it out of python-client after regenerating the client - so adding schemas to the spec left it four files behind. The README's model list did not name them and their pages did not exist. Copied the way update_version.sh copies them. The four new pages and four lines in the README, nothing else: the generator's README is built from the spec, so the stale Calibration* pages it had left on disk under the old names are absent from it and were removed before copying rather than published alongside their replacements. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01NfuDvf5ipV3Hi8TiCUKD27 --- docs/python_client/README.md | 4 ++ .../docs/PowderCalibrationFitSigma.md | 36 ++++++++++++++++ .../docs/PowderCalibrationOutput.md | 32 ++++++++++++++ .../docs/PowderCalibrationQuality.md | 42 +++++++++++++++++++ .../docs/PowderCalibrationSpotCheck.md | 33 +++++++++++++++ 5 files changed, 147 insertions(+) create mode 100644 docs/python_client/docs/PowderCalibrationFitSigma.md create mode 100644 docs/python_client/docs/PowderCalibrationOutput.md create mode 100644 docs/python_client/docs/PowderCalibrationQuality.md create mode 100644 docs/python_client/docs/PowderCalibrationSpotCheck.md diff --git a/docs/python_client/README.md b/docs/python_client/README.md index bb784a94f..43a4f293d 100644 --- a/docs/python_client/README.md +++ b/docs/python_client/README.md @@ -211,6 +211,10 @@ Class | Method | HTTP request | Description - [Plot](docs/Plot.md) - [PlotUnitX](docs/PlotUnitX.md) - [Plots](docs/Plots.md) + - [PowderCalibrationFitSigma](docs/PowderCalibrationFitSigma.md) + - [PowderCalibrationOutput](docs/PowderCalibrationOutput.md) + - [PowderCalibrationQuality](docs/PowderCalibrationQuality.md) + - [PowderCalibrationSpotCheck](docs/PowderCalibrationSpotCheck.md) - [RoiAzimList](docs/RoiAzimList.md) - [RoiAzimuthal](docs/RoiAzimuthal.md) - [RoiBox](docs/RoiBox.md) diff --git a/docs/python_client/docs/PowderCalibrationFitSigma.md b/docs/python_client/docs/PowderCalibrationFitSigma.md new file mode 100644 index 000000000..f7b0ca739 --- /dev/null +++ b/docs/python_client/docs/PowderCalibrationFitSigma.md @@ -0,0 +1,36 @@ +# PowderCalibrationFitSigma + +What the powder ring fit knows about its own answer, from the covariance of the converged problem. Each sigma is in its parameter's own unit and is scaled by the residual scatter of that fit, so it is the usual \"how far could this move before the fit got visibly worse\". The two correlations are the ones that matter: a tilt and a beam-centre shift both displace a ring's radius as cos(phi) and are told apart only by how that amplitude grows with the ring's radius, so as the rings run out the pair stops being separable and these approach 1. The rotation sigmas and the correlations are absent when the tilt was not a free parameter. + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**beam_x_pxl** | **float** | Standard error of the fitted PONI x [pixels] | [optional] +**beam_y_pxl** | **float** | Standard error of the fitted PONI y [pixels] | [optional] +**detector_distance_mm** | **float** | Standard error of the fitted detector distance [mm] | [optional] +**poni_rot1_rad** | **float** | Standard error of the fitted rot1 [rad] | [optional] +**poni_rot2_rad** | **float** | Standard error of the fitted rot2 [rad] | [optional] +**correlation_beam_x_rot1** | **float** | Correlation between the fitted PONI x and rot1, -1 to 1 | [optional] +**correlation_beam_y_rot2** | **float** | Correlation between the fitted PONI y and rot2, -1 to 1 | [optional] + +## Example + +```python +from jfjoch_client.models.powder_calibration_fit_sigma import PowderCalibrationFitSigma + +# TODO update the JSON string below +json = "{}" +# create an instance of PowderCalibrationFitSigma from a JSON string +powder_calibration_fit_sigma_instance = PowderCalibrationFitSigma.from_json(json) +# print the JSON string representation of the object +print(PowderCalibrationFitSigma.to_json()) + +# convert the object into a dict +powder_calibration_fit_sigma_dict = powder_calibration_fit_sigma_instance.to_dict() +# create an instance of PowderCalibrationFitSigma from a dict +powder_calibration_fit_sigma_from_dict = PowderCalibrationFitSigma.from_dict(powder_calibration_fit_sigma_dict) +``` +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/python_client/docs/PowderCalibrationOutput.md b/docs/python_client/docs/PowderCalibrationOutput.md new file mode 100644 index 000000000..987957c59 --- /dev/null +++ b/docs/python_client/docs/PowderCalibrationOutput.md @@ -0,0 +1,32 @@ +# PowderCalibrationOutput + +The result of a powder-ring detector calibration - what rugnux --mode calibration writes as .json, and what a calibration run over the image buffer would return. dataset_settings holds the geometry and nothing else, under the property names this API gives them, so it can be POSTed or merged without translating a field. Its beam_x_pxl/beam_y_pxl is the PONI, the foot of the perpendicular from the sample; where the beam actually lands is calibration.direct_beam_x_pxl. The poni_rot*_rad are present whenever any of them is non-zero and absent when all are zero, since a body omitting them states a FLAT detector rather than an unstated one. + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**dataset_settings** | [**DatasetSettings**](DatasetSettings.md) | | +**calibration** | [**PowderCalibrationQuality**](PowderCalibrationQuality.md) | | [optional] +**jfjoch_version** | **str** | Version of the program that produced this | [optional] + +## Example + +```python +from jfjoch_client.models.powder_calibration_output import PowderCalibrationOutput + +# TODO update the JSON string below +json = "{}" +# create an instance of PowderCalibrationOutput from a JSON string +powder_calibration_output_instance = PowderCalibrationOutput.from_json(json) +# print the JSON string representation of the object +print(PowderCalibrationOutput.to_json()) + +# convert the object into a dict +powder_calibration_output_dict = powder_calibration_output_instance.to_dict() +# create an instance of PowderCalibrationOutput from a dict +powder_calibration_output_from_dict = PowderCalibrationOutput.from_dict(powder_calibration_output_dict) +``` +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/python_client/docs/PowderCalibrationQuality.md b/docs/python_client/docs/PowderCalibrationQuality.md new file mode 100644 index 000000000..184ad8bac --- /dev/null +++ b/docs/python_client/docs/PowderCalibrationQuality.md @@ -0,0 +1,42 @@ +# PowderCalibrationQuality + +What a powder calibration knows about the geometry it produced. A calibration that has gone wrong - the wrong standard named, a header too far out for the rings to be found - looks exactly like one that has not until these are read. + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**calibrant** | **str** | The powder standard the rings were fitted to, or the unit cell given in its place | [optional] +**method** | **str** | How the rings were measured. rings fits the arcs of the run-summed (q x azimuth) azimuthal profile; spots fits the pooled per-image spot lists. | [optional] +**ring_points** | **int** | Ring measurements the fit used | [optional] +**rms_radial_pxl** | **float** | Scatter of those measurements about the fitted rings, as a radial distance [pixels]. The single number that separates a calibration that worked from one that did not. | [optional] +**beam_sigma_pxl** | **float** | Standard error the scatter implies on the beam centre [pixels], for a ring of that many points. See powder_calibration_fit_sigma for what the fit itself says, which is not the same and is the larger of the two whenever the tilt is poorly separated. | [optional] +**direct_beam_x_pxl** | **float** | Where the direct beam lands [pixels]. NOT dataset_settings.beam_x_pxl, which is the PONI: the two part company by distance*tan(tilt)/pixel as soon as the detector is tilted. | [optional] +**direct_beam_y_pxl** | **float** | Where the direct beam lands, y [pixels] | [optional] +**header_distance_mm** | **float** | The detector distance the input file declared, for comparison [mm] | [optional] +**ring_seed_distance_mm** | **float** | The distance measured from the ring radii before the fit ran [mm]. It is taken from the radii, the wavelength and the pixel size alone, so a large gap from header_distance_mm is the answer to the question the calibration was run to ask. Absent when the profile showed too few rings to fix a scale. | [optional] +**tilt_refined** | **bool** | Whether the reported rot1/rot2 were measured by this fit. False means they were declined and pinned at the input file's values, because the rings could not separate a tilt from a shift of the beam centre. | [optional] +**tilt_significance** | **float** | How many of its own sigmas the fitted tilt stands from zero. Below about 3 it is not a measurement of a tilt but of a beam-centre shift, and the tilt is declined. Passing does not certify a tilt: that estimator is limited by systematics rather than by this sigma. | [optional] +**fit_sigma** | [**PowderCalibrationFitSigma**](PowderCalibrationFitSigma.md) | | [optional] +**spot_cross_check** | [**PowderCalibrationSpotCheck**](PowderCalibrationSpotCheck.md) | | [optional] + +## Example + +```python +from jfjoch_client.models.powder_calibration_quality import PowderCalibrationQuality + +# TODO update the JSON string below +json = "{}" +# create an instance of PowderCalibrationQuality from a JSON string +powder_calibration_quality_instance = PowderCalibrationQuality.from_json(json) +# print the JSON string representation of the object +print(PowderCalibrationQuality.to_json()) + +# convert the object into a dict +powder_calibration_quality_dict = powder_calibration_quality_instance.to_dict() +# create an instance of PowderCalibrationQuality from a dict +powder_calibration_quality_from_dict = PowderCalibrationQuality.from_dict(powder_calibration_quality_dict) +``` +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + + diff --git a/docs/python_client/docs/PowderCalibrationSpotCheck.md b/docs/python_client/docs/PowderCalibrationSpotCheck.md new file mode 100644 index 000000000..b8daa8bf6 --- /dev/null +++ b/docs/python_client/docs/PowderCalibrationSpotCheck.md @@ -0,0 +1,33 @@ +# PowderCalibrationSpotCheck + +Where the circle through the found spots puts the beam, and how far that is from the geometry actually fitted. An independent cross-check: it reads nothing from the file's own geometry, so it holds where the summed azimuthal profile does not - a profile binned about a badly wrong centre shows each ring smeared across its sectors, and a fit on it converges on the wrong answer without saying so. Two methods sharing no assumption, so the disagreement is the statement. Absent when no spots were available. + +## Properties + +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**beam_x_pxl** | **float** | Beam centre x the spots vote for [pixels] | [optional] +**beam_y_pxl** | **float** | Beam centre y the spots vote for [pixels] | [optional] +**detector_distance_mm** | **float** | Detector distance the spots imply [mm] | [optional] +**disagreement_pxl** | **float** | Distance between the spots' beam centre and the fitted one [pixels] | [optional] + +## Example + +```python +from jfjoch_client.models.powder_calibration_spot_check import PowderCalibrationSpotCheck + +# TODO update the JSON string below +json = "{}" +# create an instance of PowderCalibrationSpotCheck from a JSON string +powder_calibration_spot_check_instance = PowderCalibrationSpotCheck.from_json(json) +# print the JSON string representation of the object +print(PowderCalibrationSpotCheck.to_json()) + +# convert the object into a dict +powder_calibration_spot_check_dict = powder_calibration_spot_check_instance.to_dict() +# create an instance of PowderCalibrationSpotCheck from a dict +powder_calibration_spot_check_from_dict = PowderCalibrationSpotCheck.from_dict(powder_calibration_spot_check_dict) +``` +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + +