DOC: need HOW to use NXWriter documentation

[prjemian]

Existing documentation is very limited, it seems. Need some concrete advice for beam line staff how to use and customize the NXWriter.

[prjemian]

From a recent conversation (involving master & ExternalLink file sets):

• https://bcda-aps.github.io/apstools/latest/api/_filewriters.html
• https://bcda-aps.github.io/apstools/latest/api/_plans.html#apstools.plans.doc_run.write_stream

The NXWriter has a newer templates feature. Here's a quick demo in a bluesky plan:

templates = [
    ["/entry/full_file_name=", adsimdet.hdf1.full_file_name.get()],
]
md = {"title": "APS POLAR", nxwriter.template_key: json.dumps(templates)}

def outer(detectors, motors, **md):
    _md = {}
    _md.update(md)

    nxwriter.file_name = "polar_templates.hdf5"
    print(f"{md=!r}")
    print(f"{_md=!r}")

    @bpp.subs_decorator(nxwriter.receiver)  # collect the data
    @bpp.stage_decorator(list(detectors) + motors)
    @bpp.run_decorator(md=_md)
    def inner():
        # assume adsimdet has already collected its image file
        yield from bps.null()

    yield from inner()
    print(f"{nxwriter.file_path=!r}")
    print(f"{nxwriter.file_name=!r}")


RE(outer([adsimdet], [m1, m2], **md))

Here's what the first part of the HDF5 file looks like:

.../polar_templates.hdf5 : NeXus data file
  @HDF5_Version = "1.14.0"
  @NeXus_version = "v2020.1"
  @creator = "NXWriter"
  @default = "entry"
  @file_name = "polar_templates.hdf5"
  @file_time = "2024-06-03T17:41:42.483911"
  @h5py_version = "3.9.0"
  entry:NXentry
    @NX_class = "NXentry"
    @target = "/entry"
    duration:NX_FLOAT64[] = 
      @units = "s"
    end_time:NX_CHAR = b'2024-06-03T17:41:42.482846'
    entry_identifier --> /entry/instrument/bluesky/metadata/run_start_uid
    full_file_name:NX_CHAR = b'/tmp/adsimdet/2024/06/03/58c46161-22eb-43e3-a3bf_000000.h5'
      @target = "/entry/full_file_name"
    plan_name --> /entry/instrument/bluesky/metadata/plan_name
    program_name:NX_CHAR = b'bluesky'
    start_time:NX_CHAR = b'2024-06-03T17:41:42.479564'

[prjemian]

polar.ipynb.zip

Update to the NXwriter local modifications. This update repositions the external links to image and fast positioners data, according to the NeXus schema

def write_entry(self):
        """Called after stop document has been received."""
        nxentry = super().write_entry()
        print(f"{nxentry=!r}")
        nxinstrument = nxentry["instrument"]
      
        if self.ad_file_name is not None:
            # https://manual.nexusformat.org/classes/base_classes/NXdetector.html
            nxdetector = nxinstrument.create_group("detector")
            nxdetector.attrs["NX_class"] = "NXdetector"
            nxdetector["data"] = h5py.ExternalLink(
                str(self.ad_file_name),
                "/entry/data",  # link to the data group with the image dataset
            )
            nxdetector["data_file"] = adsimdet.hdf1.full_file_name.get()
      
        if self.position_file_name is not None:
            # https://manual.nexusformat.org/classes/base_classes/NXcollection.html
            group = nxinstrument.create_group("fast_positions")
            group.attrs["NX_class"] = "NXcollection"
            group["root"] = h5py.ExternalLink(
                str(self.position_file_name),
                "/",  # link to the root of the file
            )