Record the origin of experimental data and import large integers exactly

doc/locale/fr/LC_MESSAGES/release_notes/release_1.04.po

@@ -0,0 +1,44 @@
+# French translations for Sigima.
+# Copyright (C) 2026 ORGANIZATION
+# This file is distributed under the same license as the Sigima project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: Sigima VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2026-10-22 21:34+0200\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: fr\n"
+"Language-Team: fr <LL@li.org>\n"
+"Plural-Forms: nplurals=2; plural=(n > 1);\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+msgid "Version 1.4"
+msgstr "Version 1.4"
+
+msgid "Sigima Version 1.4.0"
+msgstr "Sigima Version 1.4.0"
+
+msgid "✨ New features since version 1.3.0"
+msgstr "✨ Nouveautés depuis la version 1.3.0"
+
+msgid "**Origin of experimental data**: Objects imported from experimental files or captured from instruments can record where their data came from in the new `experimental_source` metadata entry: source kind, file path or instrument address, scan or dataset, selected part, timestamps, applied conversions and other details. The entry is a versioned dictionary made of JSON types only, so it remains readable without the reader or connector that created it, and it is restored with the same Python types by Sigima's native signal and image files (and by DataLab workspaces): a restored entry can be serialized to JSON or stored again. Values are limited to what HDF5 files restore exactly: `None` and keys that are not plain names are rejected, and NumPy scalars are converted to Python values. It is created and accessed with `make_experimental_source`, `set_experimental_source` and `get_experimental_source` (`sigima.objects`). The existing `source` metadata entry is unchanged."
+msgstr "**Origine des données expérimentales** : les objets importés depuis des fichiers expérimentaux ou acquis par des instruments peuvent enregistrer l'origine de leurs données dans la nouvelle entrée de métadonnées `experimental_source` : type de source, chemin du fichier ou adresse de l'instrument, scan ou jeu de données, partie sélectionnée, horodatages, conversions appliquées et autres détails. Cette entrée est un dictionnaire versionné composé uniquement de types JSON ; elle reste donc lisible sans le lecteur ou connecteur qui l'a créée, et elle est restaurée avec les mêmes types Python par les formats natifs de signaux et d'images de Sigima (et par les espaces de travail DataLab) : une entrée restaurée peut être sérialisée en JSON ou stockée à nouveau. Les valeurs sont limitées à ce que les fichiers HDF5 restituent à l'identique : `None` et les clés qui ne sont pas de simples noms sont rejetés, et les scalaires NumPy sont convertis en valeurs Python. Elle est créée et consultée avec `make_experimental_source`, `set_experimental_source` et `get_experimental_source` (`sigima.objects`). L'entrée de métadonnées existante `source` reste inchangée."
+
+msgid "**Group UUID from the remote client**: `add_group` of the remote client (`sigima.client`) now returns the UUID of the created group, so that objects can be added to it with `group_id=...` (DataLab ≥ 1.4.0; older versions return `None`)."
+msgstr "**UUID de groupe depuis le client distant** : `add_group` du client distant (`sigima.client`) renvoie désormais l'UUID du groupe créé, afin d'y ajouter des objets avec `group_id=...` (DataLab ≥ 1.4.0 ; les versions antérieures renvoient `None`)."
+
+msgid "The [user guide](../user_guide/overview.rst) shows how readers and connectors attach experimental-source metadata, save and restore it, and send an acquisition to a DataLab group. Source recording is opt-in and does not make the experiment reproducible."
+msgstr "Le [guide utilisateur](../user_guide/overview.rst) montre comment les lecteurs et connecteurs attachent les métadonnées d'origine expérimentale, les enregistrent et les restaurent, et envoient une acquisition dans un groupe DataLab. L'enregistrement de l'origine est explicite et ne rend pas l'expérience reproductible."
+
+msgid "🛠️ Bug Fixes since version 1.3.0"
+msgstr "🛠️ Corrections de bugs depuis la version 1.3.0"
+
+msgid "**Exact integer import**: Integer data that does not fit any integer type supported by the destination object (for example `uint32` counts above 2 147 483 647 in an image, or large integers in a signal) is now converted to a floating-point type that represents every value exactly. Such data was previously converted to `float32` when the source used 4-byte integers, which rounded counts above 16 777 216. A warning is now emitted when no supported floating-point type is exact (integers beyond 2⁵³)."
+msgstr "**Import exact des entiers** : les données entières qui ne tiennent dans aucun type entier pris en charge par l'objet de destination (par exemple des comptages `uint32` supérieurs à 2 147 483 647 dans une image, ou de grands entiers dans un signal) sont désormais converties vers un type flottant représentant chaque valeur exactement. Ces données étaient auparavant converties en `float32` lorsque la source utilisait des entiers sur 4 octets, ce qui arrondissait les comptages au-delà de 16 777 216. Un avertissement est désormais émis lorsqu'aucun type flottant pris en charge n'est exact (entiers au-delà de 2⁵³)."

doc/locale/fr/LC_MESSAGES/user_guide/overview.po

@@ -6,11 +6,18 @@
 #, fuzzy
 msgid ""
 msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2026-10-22 21:34+0200\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language: fr\n"
+"Language-Team: fr <LL@li.org>\n"
 "Plural-Forms: nplurals=2; plural=(n > 1);\n"
 "MIME-Version: 1.0\n"
 "Content-Type: text/plain; charset=utf-8\n"
 "Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
 
 msgid "Overview"
 msgstr "Vue d'ensemble"
@@ -123,6 +130,36 @@ msgstr "Considérez une mesure de température au cours du temps. Avec un simple
 msgid "This signal object can now be processed, analyzed, saved, and loaded while preserving all its context. When you apply operations like filtering, peak detection, or statistics, the units, labels, and error bars remain attached to your data."
 msgstr "Cet objet signal peut maintenant être traité, analysé, sauvegardé et chargé tout en préservant son contexte. Lorsque vous appliquez des opérations comme le filtrage, la détection de pics ou les statistiques, les unités, étiquettes et barres d'erreur restent attachées à vos données."
 
+msgid "Experimental Data Origin"
+msgstr "Origine des données expérimentales"
+
+msgid "Readers and instrument connectors can attach a structured ``experimental_source`` entry to a signal or image. This is opt-in: creating an object does not identify its experimental origin automatically. The existing ``source`` metadata entry is unchanged."
+msgstr "Les lecteurs et connecteurs d'instruments peuvent attacher une entrée structurée ``experimental_source`` à un signal ou une image. Cette démarche est explicite : créer un objet n'identifie pas automatiquement son origine expérimentale. L'entrée de métadonnées existante ``source`` reste inchangée."
+
+msgid "The required fields identify the source kind (for example ``nexus``, ``spec`` or ``tango``) and its location (file path or instrument address). Optional fields describe the scan or dataset (``entry``), selected columns or indices (``selection``), timestamps, applied conversions and additional details. The versioned dictionary accepts the JSON values that HDF5 files restore exactly: dictionaries with non-empty string keys (without ``/`` and not starting with ``__``), lists, strings, booleans, 64-bit integers and finite numbers. ``None`` (JSON ``null``) is rejected, because HDF5 files would restore it as an empty string: readers use ``\".\"`` for a dimension without axis, as NeXus does. NumPy scalars and tuples are converted to Python values and lists; convert arrays to lists and timestamps to strings. Unknown fields, unsupported versions and non-finite values are rejected."
+msgstr "Les champs obligatoires identifient le type de source (par exemple ``nexus``, ``spec`` ou ``tango``) et son emplacement (chemin de fichier ou adresse d'instrument). Les champs facultatifs décrivent le scan ou jeu de données (``entry``), les colonnes ou indices sélectionnés (``selection``), les horodatages, les conversions appliquées et des détails supplémentaires. Le dictionnaire versionné accepte les valeurs JSON que les fichiers HDF5 restituent à l'identique : dictionnaires à clés chaînes non vides (sans ``/`` et ne commençant pas par ``__``), listes, chaînes, booléens, entiers 64 bits et nombres finis. ``None`` (``null`` en JSON) est rejeté, car les fichiers HDF5 le restitueraient sous forme de chaîne vide : les lecteurs utilisent ``\".\"`` pour une dimension sans axe, comme NeXus. Les scalaires NumPy et les tuples sont convertis en valeurs et listes Python ; convertissez les tableaux en listes et les horodatages en chaînes. Les champs inconnus, versions non prises en charge et valeurs non finies sont rejetés."
+
+msgid "This example records a scan, then saves and restores its origin using the native signal format:"
+msgstr "Cet exemple décrit un scan, puis enregistre et restaure son origine avec le format natif des signaux :"
+
+msgid "The native image format (``.h5ima``) preserves this entry too, with its Python types: a restored source can be serialized to JSON or stored again as is. The setter stores a copy, and the getter returns a copy, so editing either dictionary does not alter the other. The information remains readable without the original reader or instrument connector. It identifies a measurement; it does not make the acquisition reproducible or replace the record of subsequent processing. NeXus import and declarative HDF5 mappings are provided by SigimaX, not by these metadata helpers; naming a source kind does not install its reader or connector."
+msgstr "Le format natif des images (``.h5ima``) préserve aussi cette entrée, avec ses types Python : une source restaurée peut être sérialisée en JSON ou stockée à nouveau telle quelle. La fonction d'affectation stocke une copie, et la fonction de lecture renvoie une copie : modifier l'un des dictionnaires ne modifie pas l'autre. Ces informations restent lisibles sans le lecteur ou connecteur d'instrument d'origine. Elles identifient une mesure ; elles ne rendent pas l'acquisition reproductible et ne remplacent pas l'enregistrement des traitements ultérieurs. L'import NeXus et les profils HDF5 déclaratifs sont fournis par SigimaX, pas par ces fonctions de métadonnées ; nommer un type de source n'installe pas son lecteur ou connecteur."
+
+msgid "Integer Precision on Import"
+msgstr "Précision des entiers à l'import"
+
+msgid "When an integer array does not fit an integer type supported by its destination object, Sigima selects a supported floating-point type with sufficient precision when possible. For example, ``uint32`` image counts up to 4 294 967 295 are preserved exactly in ``float64`` rather than clipped to ``int32`` or rounded to ``float32``. This preserves values, not necessarily the original dtype. If no supported float type can represent the integer range exactly, Sigima emits a warning; ``float64`` guarantees exact integers only up to ``+/-2**53``."
+msgstr "Lorsqu'un tableau entier ne tient dans aucun type entier pris en charge par son objet de destination, Sigima sélectionne si possible un type flottant pris en charge suffisamment précis. Par exemple, les comptages d'image ``uint32`` jusqu'à 4 294 967 295 sont préservés exactement en ``float64`` plutôt qu'écrêtés en ``int32`` ou arrondis en ``float32``. Cela préserve les valeurs, pas nécessairement le dtype original. Si aucun type flottant pris en charge ne peut représenter exactement la plage d'entiers, Sigima émet un avertissement ; ``float64`` ne garantit les entiers exacts que jusqu'à ``+/-2**53``."
+
+msgid "Sending Acquisitions to a DataLab Group"
+msgstr "Envoi d'acquisitions dans un groupe DataLab"
+
+msgid "With a running DataLab 1.4 or later, a remote client can use the UUID returned by ``add_group`` to add measured objects to that group, without looking it up by title:"
+msgstr "Avec DataLab 1.4 ou ultérieur en cours d'exécution, un client distant peut utiliser l'UUID renvoyé par ``add_group`` pour ajouter des objets mesurés à ce groupe, sans le rechercher par son titre :"
+
+msgid "This example uses the signal defined above. Older DataLab servers return ``None`` instead of a group UUID; this grouping workflow requires DataLab 1.4."
+msgstr "Cet exemple utilise le signal défini ci-dessus. Les anciens serveurs DataLab renvoient ``None`` au lieu d'un UUID de groupe ; cette procédure de regroupement nécessite DataLab 1.4."
+
 msgid "Specialized Features"
 msgstr "Fonctionnalités spécialisées"
 

doc/release_notes/release_1.04.md

@@ -0,0 +1,14 @@
+# Version 1.4 #
+
+## Sigima Version 1.4.0 ##
+
+### ✨ New features since version 1.3.0 ###
+
+* **Origin of experimental data**: Objects imported from experimental files or captured from instruments can record where their data came from in the new `experimental_source` metadata entry: source kind, file path or instrument address, scan or dataset, selected part, timestamps, applied conversions and other details. The entry is a versioned dictionary made of JSON types only, so it remains readable without the reader or connector that created it, and it is restored with the same Python types by Sigima's native signal and image files (and by DataLab workspaces): a restored entry can be serialized to JSON or stored again. Values are limited to what HDF5 files restore exactly: `None` and keys that are not plain names are rejected, and NumPy scalars are converted to Python values. It is created and accessed with `make_experimental_source`, `set_experimental_source` and `get_experimental_source` (`sigima.objects`). The existing `source` metadata entry is unchanged.
+* **Group UUID from the remote client**: `add_group` of the remote client (`sigima.client`) now returns the UUID of the created group, so that objects can be added to it with `group_id=...` (DataLab ≥ 1.4.0; older versions return `None`).
+
+The [user guide](../user_guide/overview.rst) shows how readers and connectors attach experimental-source metadata, save and restore it, and send an acquisition to a DataLab group. Source recording is opt-in and does not make the experiment reproducible.
+
+### 🛠️ Bug Fixes since version 1.3.0 ###
+
+* **Exact integer import**: Integer data that does not fit any integer type supported by the destination object (for example `uint32` counts above 2 147 483 647 in an image, or large integers in a signal) is now converted to a floating-point type that represents every value exactly. Such data was previously converted to `float32` when the source used 4-byte integers, which rounded counts above 16 777 216. A warning is now emitted when no supported floating-point type is exact (integers beyond 2⁵³).

doc/user_guide/overview.rst

@@ -100,6 +100,101 @@ Consider a temperature measurement over time. With a simple NumPy array, you jus
 
 This signal object can now be processed, analyzed, saved, and loaded while preserving all its context. When you apply operations like filtering, peak detection, or statistics, the units, labels, and error bars remain attached to your data.
 
+Experimental Data Origin
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Readers and instrument connectors can attach a structured ``experimental_source``
+entry to a signal or image. This is opt-in: creating an object does not identify
+its experimental origin automatically. The existing ``source`` metadata entry
+is unchanged.
+
+The required fields identify the source kind (for example ``nexus``, ``spec``
+or ``tango``) and its location (file path or instrument address). Optional
+fields describe the scan or dataset (``entry``), selected columns or indices
+(``selection``), timestamps, applied conversions and additional details.
+The versioned dictionary accepts the JSON values that HDF5 files restore
+exactly: dictionaries with non-empty string keys (without ``/`` and not
+starting with ``__``), lists, strings, booleans, 64-bit integers and finite
+numbers. ``None`` (JSON ``null``) is rejected, because HDF5 files would restore
+it as an empty string: readers use ``"."`` for a dimension without axis, as
+NeXus does. NumPy scalars and tuples are converted to Python values and lists;
+convert arrays to lists and timestamps to strings. Unknown fields, unsupported
+versions and non-finite values are rejected.
+
+This example records a scan, then saves and restores its origin using the
+native signal format:
+
+.. code-block:: python
+
+    from pathlib import Path
+    from tempfile import TemporaryDirectory
+
+    import numpy as np
+    import sigima.io
+    from sigima.objects import (
+        create_signal,
+        get_experimental_source,
+        make_experimental_source,
+        set_experimental_source,
+    )
+
+    signal = create_signal(
+        "Transmission", np.array([8.0, 8.1, 8.2]), np.array([10.0, 7.0, 4.0])
+    )
+    signal.xunit = "keV"
+    source = make_experimental_source(
+        "spec",
+        "scan.spec",
+        entry="12.1",
+        selection={"x": "Energy", "y": "I0"},
+        timestamps={"source": "2026-10-20T08:15:00+02:00"},
+        details={"command": "ascan energy 8 8.2 2 0.1"},
+    )
+    set_experimental_source(signal, source)
+    with TemporaryDirectory() as directory:
+        filename = str(Path(directory) / "transmission.h5sig")
+        sigima.io.write_signal(filename, signal)
+        restored = sigima.io.read_signal(filename)
+        assert get_experimental_source(restored) == source
+
+The native image format (``.h5ima``) preserves this entry too, with its Python
+types: a restored source can be serialized to JSON or stored again as is. The
+setter stores a copy, and the getter returns a copy, so editing either
+dictionary does not alter the other. The information remains readable without the original reader
+or instrument connector. It identifies a measurement; it does not make the
+acquisition reproducible or replace the record of subsequent processing.
+NeXus import and declarative HDF5 mappings are provided by SigimaX, not by these
+metadata helpers; naming a source kind does not install its reader or connector.
+
+Integer Precision on Import
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When an integer array does not fit an integer type supported by its destination
+object, Sigima selects a supported floating-point type with sufficient precision
+when possible. For example, ``uint32`` image counts up to 4 294 967 295 are
+preserved exactly in ``float64`` rather than clipped to ``int32`` or rounded
+to ``float32``. This preserves values, not necessarily the original dtype.
+If no supported float type can represent the integer range exactly, Sigima
+emits a warning; ``float64`` guarantees exact integers only up to ``+/-2**53``.
+
+Sending Acquisitions to a DataLab Group
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+With a running DataLab 1.4 or later, a remote client can use the UUID returned by
+``add_group`` to add measured objects to that group, without looking it up by
+title:
+
+.. code-block:: python
+
+    from sigima.client import SimpleRemoteProxy
+
+    proxy = SimpleRemoteProxy()
+    group_id = proxy.add_group("Scan 12.1", panel="signal")
+    proxy.add_object(signal, group_id=group_id)
+
+This example uses the signal defined above. Older DataLab servers return
+``None`` instead of a group UUID; this grouping workflow requires DataLab 1.4.
+
 Specialized Features
 ^^^^^^^^^^^^^^^^^^^^
 

sigima/_metadata.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-__version__ = "1.3.0"
+__version__ = "1.4.0"
 __docurl__ = "https://sigima.readthedocs.io/"
 __homeurl__ = "https://github.com/DataLab-Platform/Sigima"
 __supporturl__ = "https://github.com/DataLab-Platform/sigima/issues/new/choose"