Usage Guide

Core Concept

The NMR Sample Manager creates simple metadata files in your dataset directories to record when samples are injected and ejected. All other information is optional but can be recorded to help keep track of your measurements.

Information can be captured about:

• Users: People involved in the experiment
• Sample: Molecule names, concentrations, isotopic labeling
• Buffer: pH, buffer components, solvent information
• NMR Tube: Tube type, diameter, sample volume
• Sample Position: SampleJet rack positions
• Laboratory Reference: Lab book entries, experiment IDs
• Notes: Additional observations

Remember: all fields are optional - use only what you need!

Managing Samples

Creating a New Sample

1. Click the "New Sample" button
2. Fill in the form with your sample information (all fields are optional)
3. The plus (+) buttons can be used to add fields, e.g. for users, or buffer components
4. Click "Save" or press ENTER to store the sample metadata
5. To cancel entry, just interact with another sample, or go to the timeline view

Editing Existing Samples

1. Select a sample from the list
2. Click "Edit" to modify the information
3. Make your changes and click "Save"

Duplicating Samples

Perfect for titration series or similar experiments:

1. Select an existing sample
2. Click "Duplicate"
3. Modify the details as needed
4. Save the new sample

Timeline View

Click "Show timeline" to see a complete history of all samples in the current experiment, including when they were created, modified, and ejected.

Sample Ejection

When you're done with a sample, click "Eject" to timestamp when it was removed. This helps track which samples are currently active in the spectrometer.

File Storage

Sample data is stored as human-readable JSON files in your experiment directories. These files:

• Can be opened in any text editor
• Work well with version control systems like Git
• Include timestamps for creation, modification, and ejection
• Follow a consistent naming pattern: timestamp_samplename.json

Tips

• Use the duplicate feature for sample series with small variations
• The timeline view helps you see the complete experiment history
• All sample information is automatically timestamped
• You can edit or update samples anytime
• Use the Notes field for any additional observations

Controlling the App via URL Parameters

The application can be controlled via URL parameters, which is useful for TopSpin integration scripts:

Navigate to a specific folder

https://waudbylab.org/nmr-samples/?folder=/path/to/experiment

This will automatically navigate to the specified experiment folder.

Sample injection

https://waudbylab.org/nmr-samples/?folder=/path/to/experiment&action=inject

This will navigate to the folder and open the sample creation form for a new injection.

Automatic sample ejection

https://waudbylab.org/nmr-samples/?folder=/path/to/experiment&action=eject

This will navigate to the folder and automatically eject the most recent active sample.

These URL parameters enable TopSpin integration scripts to automatically manage samples during your workflow.

JSON Schema

The NMR Sample Manager uses a JSON Schema to define the structure and validation rules for sample metadata. A JSON Schema is like a blueprint that describes what information can be stored and how it should be formatted.

For example, the schema defines:

• Which fields are available (Users, Sample, Buffer, etc.)
• What type of data each field accepts (text, numbers, predefined options)
• Validation rules (e.g., pH must be between 0 and 14)
• Default values and descriptions for each field

The current schema version is available at: current.json

This schema-driven approach ensures:

• Consistency: All sample files follow the same structure
• Validation: Data is checked for correctness before saving
• Evolution: The schema can be updated while maintaining compatibility with existing data
• Transparency: The data structure is clearly documented and machine-readable

Support and Development

The NMR Sample Manager is an open-source project hosted on GitHub:

• Source code: github.com/waudbygroup/nmr-samples
• Report issues or request features: Create a new issue

Found a bug or have a suggestion? Please report it on GitHub - this helps improve the application for everyone.