Logbook2Mouse

This library reads a measurement logbook and associated project/sample information and generates a script for a SAXS instrument. Currently still under development.

Installation

bash python3.12 -m venv .venv pip install -e .

before using...

Note that the logbook contains a second sheet with motor positions for sample stages. This is now set up so that you can have an arbitrary number of columns (motors) for a given stage position ID. That should allow for the use of alternative stages such as the GISAXS stage for experiments, which has five motors instead of the normal two cartesian stages we have.

Secondly, the script retrieves project and sample information from the project/sample sheets. These must therefore be present before you run the logbook2mouse script. This is done on purpose to ensure these project/sample sheets are actually used and filled in, as they also allow us to track our experiments better.

The project/sample sheets live in a separate directory structure, whcih must be organized by [year]/[proposalid].xlsx The proposal file name (used as the ProposalID) must start with the four-digit year. In our lab, we use the format [YYYY][nnn].xlsx for these proposal sheets, but in principle you're free to use how you adapt the second part of the filename.

a word on specifying sample composition

The samples must have the components specified, with an atomic composition and a density estimate (not a range!). Please be careful to ensure the compositions and densities are machine-interpretable, so atomic compositions should be specified like (C2H4)213NaCl(H2O)5 and not (C2H4)n(H2O)x because we don't know what n and x are... Estimates are good enough if you don't know precisely.

The same holds for density esimates. Don't write a range (1.4 - 1.6) or (~1.2), because this cannot be interpreted. Stick to a single representative value when you can. Again, use a reasonable estimate.

Usage

```bash usage: main.py [-h] [-v] [--logfile LOGFILE] [-V] [-c] logbookfile protocolsdirectory projectbasepath outputscriptfile

Logbook to Measurement Script Generator

positional arguments: logbookfile Path to the logbook Excel file protocolsdirectory Path to the directory containing protocol files projectbasepath Path to the base project directory (i.e. from where you have the project sheets organized by [year]/[proposalid].xlsx) outputscriptfile Path to save the generated measurement script to

options: -h, --help show this help message and exit -v, --verbosity Increase output verbosity (e.g., -v for INFO, -vv for DEBUG) --logfile LOGFILE Path to the optional logging output file -V, --validate Validate the generated script before execution -c, --collate Collate the measurements by configuration ```

Example with test spreadsheets: bash python -m logbook2mouse logbook/Logbook_MOUSE.xlsx protocols tests/testdata/projects test_script.py

the --collate option

When --collate is one of the command-line arguments logbook2mouse sorts the measurements by configuration. This option saves motor movements.

Note that this option will finish all measurements at each configuration before moving to the next, even if their series date is different.

For in-situ measurements avoid this option to proceed row by row.

Protocols and protocol keyword-value combinations

the setup.py protocol

The setup protocol is prepended to the measurement script. Its role is to define and verify the connection to the needed EPICS PVs in the required_pvs list.

Change this list to reflect your setup as needed.

measurement protocols

The measurement protocols are python scripts in the protocols_directory.

Within them, you have access to the information encoded in each line of the logbook encoded in entry of type Logbook2MouseEntry, as well as the EPICS PVs in required_pvs.

Flexibility is introduced via the last columns in the logbook, the "Protocol keyword-value combinations". These are available via the dictionary entry.additional_parameters as: python configuration = entry.additional_parameters.get('configuration', None) Keep in mind that the values returned are strings.

In terms of scattering experiments, the main functions you'll likely need are: ```python from logbook2mouse.measureconfig import measureat_config

measureatconfig(configno = configuration, entry = entry, experiment = experiment, duration=600, # default: 600 repetitions=10, # default depends on configno ) ```

This includes a blank and a transmission measurement.

A simple exposure (no blank and transmission) would be: ```python from logbook2mouse.measureconfig import movetoconfig, movetosampleposition from logbook2mouse.detector import measurement

movetoconfig(experiment, configno = configuration) movetosampleposition(experiment, entry, blank = False) # if blank, it will move # to the positions motor.blank measurement(experiment, duration = 600, storelocation = "/path/to/storeloc")

```

The store location defaults to the working directory and its existence is required.

Data and configuration files

For the moment, data save paths and the (instrument) configuration load path are hard-coded. - Data is stored in Path.home() / "data" / year / yyyymmdd based on the measurement date in the logbook. - Configurations are [0-9].nxs files in Path.home() / "data/configurations", where the motor positions that define your configuration should be stored at f"/saxs/Saxslab/{motorname}" and the file name should be a number (this may change in the future).