Save Folder metadata files

A Save Folder keeps imaging data and recording-specific information together. Two ledger files record what the folder is bound to: UMITRigLedger.json records its rig, and UMITProjectLedger.json (only when the folder is bound to a project) links it to its project, subject, and session. Project information and subject reference libraries are held in the user's central umIT folder; rig definitions are held in the rig library of the computer.

Each .dat file describes itself: its 512-byte header records the size of every axis, the numeric class, the frame rate, and the exposure, so the files in a Save Folder may have different shapes and frame rates. AcqInfos.mat does not describe the imported .dat files. It describes the raw acquisition they came from. Results that are not images use the .umt format.

Do not remove AcqInfos.mat
The .dat files remain readable without it, but AcqInfos.mat holds the facts of the original acquisition, such as the camera and illumination layout, the hardware binning, and the import settings. Dual-camera coregistration and several tools rely on them, and they cannot be rebuilt without the raw recording.

Summary

File	Purpose	Use this interface
AcqInfos.mat	Facts of the raw acquisition (original frame size, frame rate, exposure, cameras, illuminations), the import settings, and a manifest of the imported .dat files. It does not describe the imported data itself; each .dat header does.	Data Import functions or a controlled migration.
DataParams.mat	Display calibration, logical mask, Raw Folder location, and image-registration state.	DataViewer, alignment tools, and DataParams helper functions.
events.mat	Analog traces, event timing, condition names, repetitions, and saved ignored-trial flags.	Events Manager or the EventsManager class.
dataHistory.mat	Processing steps and parameters that produced each saved output file.	Pipeline Manager.
pipeLog.mat	Step-by-step execution results, timing, inputs, outputs, and errors.	Pipeline Manager.
UMITRigLedger.json	The folder's rig: its binding to a rig, the optics, camera coregistration and filter sets used by rig-dependent steps, and the history of these events.	Import functions, rig-dependent analysis functions, and DataViewer (Management > Rig > Folder Rig).
UMITProjectLedger.json	Link from this folder to one project, subject, session, and folder role, with the history of binding changes. Only present for a folder that is or was bound to a project.	Project Binding Manager, the Project Manager, and DataViewer (Management > Project).

Use the interface that owns each file
These files are coordinated with other application state. Do not hand-edit them unless you understand the validation and update rules; use the app, class, or helper listed above.

AcqInfos.mat

The file contains one scalar structure named AcqInfoStream. Import functions create it from the source recording. It describes the raw acquisition: its values are those reported by the acquisition system (info.txt or the TIFF files), before any binning or channel separation applied at import. Its exact optional fields depend on the importer and hardware, but current readers use these groups:

Fields	Meaning
Height, Width	Frame size as acquired, before spatial binning at import. They do not give the size of the imported .dat files.
FrameRateHz, ExposureMsec	Frame rate and exposure of the acquisition, before temporal binning and before the illuminations were separated into channels. The frame rate of each imported file is stored in its own header.
BinningSpatial, BinningTemp	Settings chosen at import. They relate the imported files to the raw data; the imported size and rate are in each .dat header.
ImportedChannels	Manifest of the .dat files created by the import: file name, channel tag, illumination color, and camera, used to match a file to its illumination and camera. The size, class, frame rate, and exposure of each file are always read from the file's own header.
MultiCam and camera/channel fields	Dual-camera acquisition layout, rotations, flips, hardware binning, camera model, and illumination sequence when present.
Hardware/importer-specific fields	Additional facts preserved by the importer, such as analog channel names, the acquisition date and time, or source acquisition information.

AcqInfos.mat holds no rig information: the rig of the folder is recorded only in UMITRigLedger.json. Fields rigUUID and rigID written by earlier development versions are ignored, and they are dropped when the file is rewritten by an import.

Older Save Folders
Folders imported with an earlier development version may hold an AcqInfos.mat whose Height, Width, Length, or Datatype fields describe the imported files. umIT does not read those fields as facts about imported data, and the file is not migrated. New imports no longer write Length or Datatype.

DataParams.mat

The file contains one scalar DataParams structure. It is created and validated independently from acquisition metadata; it cannot replace AcqInfos.mat.

Group	Contents
Top level	schemaVersion, creation/modification times, and optional notes.
view	imageSizeYX, image-axis convention, pixel scale, and the image origin used for calibrated coordinates.
mask	The folder-wide logical mask plus its name, description, coordinate space, source, and creation time.
folders	The Raw Folder path, its availability status, and when/by whom it was set.
registration	Image alignment of the folder, in three parts: reference (the selected reference image, its name, a content fingerprint and where it came from: a subject library, a UMIT .dat file or a reference file), estimate (the estimated transform, method, QC files and measurements), and apply (whether, when and by whom the alignment was applied). This is the only record of a folder's alignment; no transform is stored in the project.
cameraCoregistration	Dual-camera transform status, rig/resource references, review/application history, QC files, and QC measurements.
custom	Reserved validated space for additional recording-level information.

events.mat

This MAT-file stores separate variables rather than one enclosing structure. They include the analog input matrix, sampling rate, trigger threshold/polarity, timestamps and ON/OFF states, condition IDs and names, baseline duration, condition-file settings, and selectedEvents flags. See Events for the full field, class, and dimension table.

dataHistory.mat

The file contains a structure array named dataHistory, with one current entry per saved output filename:

Field	Meaning
file	Output filename within the Save Folder.
timestamp	When this history entry was produced.
pipelineVersion	Version of PipelineManager that assembled the record.
info	Ordered processing steps. Each step records its function name/version, parameter values, and named input sources. Existing history from a saved input is carried forward where applicable.

pipeLog.mat

The file contains a table named pipeLog. Each row describes one attempted step. Columns include NodeTag, FunctionName, NodeID, Status, start/end times, duration, input source, output files, and short/full messages. It is an execution log, while dataHistory.mat describes the provenance of files that remain in the folder.

UMITRigLedger.json

The folder rig ledger is the single source of rig information for the Save Folder. Analysis functions that depend on the rig, such as HemoCompute, read the optics from it, never from the rig library of the computer, so the folder gives the same results on any computer and after the library rig is edited or archived. It is a JSON text file next to AcqInfos.mat, written by the import functions, by rig-dependent analysis functions and by DataViewer's Folder Rig menu.

• Snapshots: copies of the optics (camera and illumination spectra), of the camera coregistration and of the filter sets that the folder was bound to or used. Each snapshot is complete, so the folder does not need the library rig.
• Events: an append-only list of what happened to the folder: imported without a rig, bound or rebound to a rig, a part committed by its first use, a conflict, an acknowledged conflict, a fresh import. Entries are never removed or rewritten. The Rig Ledger History shows them.

The folder states read from the ledger are: no ledger (unknown), no rig, bound (with or without committed parts), conflict, and invalid. They are explained in DataViewer: Folder rig. Reading the ledger never changes it; opening data does not create one.

Never edit UMITRigLedger.json by hand
Every snapshot is checked against its content when the ledger is read. An edited or damaged ledger is invalid: the data still open, but rig-dependent processing is refused for the folder. Restore the file from a backup, re-import the raw data into a fresh Save Folder, or use Repair Rig Ledger in DataViewer, which moves the invalid file aside as UMITRigLedger.invalid_<date>T<time>.json (kept unchanged) so that a rig can be bound again; the folder then loses its rig commitments. An import into the same folder is refused while its rig ledger is invalid.

UMITProjectLedger.json

A folder bound to a project keeps a project ledger, a JSON text file with the folder's binding (project, subject and session identifiers and the folder role, rawDataFolder or processedDataFolder) and an append-only list of binding events: bind, rebind, unbind (with its reason, for example the session was removed), orphan removal and fresh import. Each bind or rebind keeps a copy of the project's names at that time, so the history reads the same when the project is not available. The file stays when a folder is unbound, so its history survives; such a folder reads as unbound.

It is a locator, not a copy of the project information. Use Project Binding Manager or the Project Manager to bind, rebind or remove a binding, and DataViewer (Management > Project) to view the history or repair a binding. Do not edit it by hand.

Folders bound with an earlier development version
Earlier versions stored the binding in UMITProjectBinding.umitlink. That file is no longer read and is not converted: a folder that has only a .umitlink reads as unbound. The file is not deleted; bind the folder again with Project Binding Manager.

Local and centralized information

Save Folder                              Central umIT folder
-----------                              -------------------
imaging files and local metadata
UMITProjectLedger.json  -- binding -->   project / subject / session,
                                         subject reference libraries
UMITRigLedger.json      (self-contained snapshots; the rig library of the
                         computer is used only to choose a rig)

The Save Folder remains a self-contained location for one recording, its processing history, its rig and its alignment. The central project folder provides organization across many recordings and keeps the reference images that should be shared between sessions. The project ledger connects the two without requiring a particular name or folder-tree layout for the imaging data. A project is optional.