adichtion

Overview

A recording made with the LabChart data-acquisition software is stored in an .adicht file, a format that is normally only read by the program that wrote it. Adichtion reads these files without that program, on macOS, Windows and Linux. Its description of the file format was worked out from the files themselves; it is published in the source repository.

It exists for one practical reason: getting a recording into an analysis. Respiratory recordings made as .adicht files often need to be cut into a stable epoch and handed to other software. Adichtion makes that a matter of selecting an interval in the viewer and choosing a format, or of one command in a script.

• A viewer that shows every channel of a recording on one time axis, with the blocks laid end to end, the comments marked, a cursor with the value of every channel, and interval statistics.
• An exporter for the whole recording, one block, or the interval you selected, in five formats.
• A command line and a Python library with the same capabilities, for batches and scripts.

Adichtion never recomputes a calculated channel: what the viewer shows and the exporter writes is what the recording stored, converted to the units the file itself specifies. The one derived thing is the up-sampling of slower channels in an export, described below.

Download and install

The desktop app is a native installer for each platform, attached to every release on GitHub. The Windows and macOS installers bundle their own Python and libraries; the Ubuntu package uses Ubuntu 24.04’s own Python 3.12, which apt installs with it. Nothing else needs to be installed. On Windows and macOS, double-clicking an .adicht file opens it in the app.

From PyPI

With Python 3.10 or later, the library and the command line install with pip; numpy is their only dependency. Excel export also needs openpyxl and video clips need ffmpeg, which the ui extra brings together with the app.

pip install adichtion            # the library and the command line
pip install "adichtion[ui]"      # plus the viewer: then `adichtion` alone starts the app

From source

git clone https://github.com/emilwalsted/adichtion
cd adichtion
pip install -e ".[ui]"

The viewer

Start the app, or, with the command line installed, run adichtion recording.adicht. The window shows every channel of the file on one time axis, with the recording's blocks laid end to end as they were recorded, a strip above the channels with the block labels and comment flags, and two panels below: the file's comments, channels and blocks on the left, and the values at the cursor on the right.

• Cursor and interval. Click a channel to place a cursor on all channels at once; each channel shows its value there, and the Data at cursor panel lists them all. Drag across a channel, or click and then Shift-click, to select an interval; the panel then shows minimum, maximum and mean per channel.
• Zoom and pan. Scroll to zoom the time axis, and Alt-drag, a sideways swipe or the middle button to pan; all channels follow. Each channel can also be zoomed in its own y-axis, and the channels can be given different heights or hidden.
• Comments and blocks. Right-click a comment or a block in the file panel and choose Mark interval: the interval is selected and every graph is zoomed to show all of it.
• Large files. The curves are drawn from the file's own min/max index first and refined from the decoded samples in the background, so a file of several hundred megabytes can be panned and zoomed without waiting.
• Calculated channels are tinted. Their stored values are shown as the recording holds them, with the definition recovered from the data where it can be (a LabChart for Mac document stores no calculated channels; see below).
• Video. When a block has a video clip, a video panel shows the frame at the cursor and plays the clip with the cursor following, from 0.1 to 8 times normal speed.

Exporting

Right-click a channel, or choose Export in the toolbar or the File menu, to export the whole recording, the block under the cursor, or the selected interval, for the channels shown, all channels, or a choice of channels. The same export is available on the command line.

The export dialog

• What to export: the whole file, the block under the cursor, or the selection (available once an interval is selected).
• Channels: those shown, all, or a choice.
• Decimal separator: point or comma. With a comma, CSV fields are separated by semicolons.
• Header lines (interval, start time, channel titles, units), comments as a trailing column (not in MATLAB files), and values in units or, switched off, the stored raw values.

A file is written under a temporary name and renamed when it is complete, so a cancelled or failed export leaves no half-written file and keeps an existing one. The dialog shows progress and has a Cancel button.

The export formats

A short CSV export of two channels, with a decimal comma, looks like this:

time_s;Flow [L/s];Pmo [cmH2O];comment
0;-0,04375;1,76375
0,001;0,009375;1,824375
0,002;0,012;1,290625

Line breaks, tabs and the file's own separator inside a comment, or a channel title in a table, never break a row: each becomes a space (in a comma-separated CSV, a comma in a comment becomes a semicolon).

Exporting for RespMech

RespMech reads the CSV, tab-separated and Excel exports as they are; for MATLAB see below. A few choices keep the column numbers it expects:

• Export one block at a time. With several blocks a CSV or tab-separated table gets a leading block column that shifts the column numbers, and RespMech reads only the first Excel sheet and the first MATLAB block.
• Keep the header on. RespMech treats the first row as channel titles, so without a header it would take the first row of data for them.
• Time is column 1 of a CSV, tab-separated or Excel export, so channel 1 is column 2 in RespMech’s column settings. A MATLAB export has no time column (choose the windows variant in RespMech), and RespMech’s app keeps column 1 for time, so the first channel of a MATLAB export cannot be assigned there: for the app, use CSV, the tab-separated table or Excel.
• Use the tab-separated table, not the instrument-style text, for a .txt file RespMech can open.

Channels with different sampling rates

Channels that share a sampling rate are exported at that rate. When the channels you export have different rates, the export is one table at the recording's tick rate, and each slower channel is up-sampled by the rule the recording program applies in its own exports: linear interpolation (rounded to whole counts, half away from zero, for raw channels) with the last sample held. Checked on ten recordings against that program's own exports, the result is identical for 99.998 % of the values; the rest differ by one count at exact half-count ties. The dialog, the command line and the status bar all say when this has happened.

Video clips

When the blocks you export have a video file, the export dialog has a Video box. Tick it to also write the matching clip, either in the file's original format (copied, nothing re-encoded, and it may start a little before the interval, at the previous key frame) or as H.264 in an MP4 file that plays everywhere and is cut frame-accurately. The clip takes the data file's name and sits in the same folder. An interval across several blocks gives one clip. Cutting uses an ffmpeg program, which the app brings.

The command line

The command line comes with the Python package (see From PyPI) and with the Ubuntu package: adichtion alone starts the app, and adichtion <command> runs a command. The macOS and Windows installers are for the app: they do not put adichtion on the PATH, and on macOS the app’s text output goes to the system log, not the terminal. For scripts on those systems, install with pip.

adichtion info FILE                       # blocks, channels, units, videos
adichtion comments FILE                   # the comment list with times
adichtion export FILE -o out.csv --format csv --record 2 --channels 1,2 --decimal ,   # block 2 (--record counts blocks)
adichtion export FILE -o out.txt --format tsv --start 355.2 --stop 385.9
adichtion export FILE -o out.txt --between "start" "stop"    # the interval between two comments
adichtion export FILE -o out.mat --record 2 --channels 1,2,3
adichtion export FILE -o all.xlsx --all-records              # every block; format from the extension
adichtion export FILE -o part.csv --start 10 --stop 20 --video h264   # also writes part.mp4
adichtion check FILE                      # decode every block and compare with the file's own index

The library gives the same access from Python: open a file, read the channels of a block in their units, and select by time or between comments.

What it reads, and how it is checked

• Recordings from Windows and macOS. Adichtion opens .adicht files and the documents the older Mac version of the program wrote. Those are usually saved without a file extension, so open them with File > Open (the dialog's second filter shows all files) or name them on the command line.
• Sample-exact decoding. Raw integer channels and calculated floating-point channels were checked against the recording program's own text and MATLAB exports, and agree to the last digit. Comments, block start times, channel titles, input ranges, the units conversion, the per-block min/max index and video clips are read as well.
• Calculated channels are never recomputed. Files written in the older v26 format store the results of calculated channels but not their definitions, so Adichtion can recover the definitions from the data (adichtion infer) and reads them from Mac settings files, but it shows and exports the stored values. A LabChart for Mac document does not store calculated channels at all: they are listed with the definition the document holds, greyed out, and are neither drawn nor exported.
• A built-in check. adichtion check decodes every block of a file and compares it with the minimum and maximum the recording stored, which is worth running on a new kind of file.
• Tests on synthetic files. The tests in the repository run on synthetic files. Integration tests against real recordings run locally, and no real recording, and nothing derived from one, is ever committed; the screenshots on this page show a synthetic recording.

The byte-level description of the format, with what is verified and what is inferred, is in the source repository: FORMAT.md for .adicht files and MAC_FORMAT.md for the Mac documents.

Release notes

Version 1.0.0 is the first public release. This section lists what it contains and will carry each later release, newest first. The complete log is the project's changelog on GitHub.

1.0.0 6 Oct 2026

• The viewer: every channel on one time axis across blocks, comment flags, cursor and interval selection with per-channel values and statistics, per-channel zoom, a channel chooser, and video playback in step with the cursor.
• Five export formats: instrument-style text, CSV, tab-separated, Excel and MATLAB; see Exporting for RespMech for which ones RespMech reads. Export of the whole file, a block or an interval, with a progress dialog and a Cancel button.
• LabChart for Mac documents open in the app, the library and the command line, with their movies in step; calculated channels, which these documents do not store, are listed with their definition.
• Video clips with an interval, copied in the original format or cut as H.264 in an MP4 file.
• Fast on large files: background indexing and prefetch, zero-copy reading of large files, and faster text, CSV and Excel writers.
• Video from the command line: adichtion export … --video h264 also writes the clip of the exported interval.
• Command line and library, including check, infer and bench.
• Installers for Windows (signed), macOS (signed and notarised) and Ubuntu, and a package on PyPI.

Licence and trademarks

Adichtion is free software under the GNU General Public License, version 3 or later, like RespMech, and written by the same author. The video clip export uses an ffmpeg program (a GPL build with libx264, brought by the imageio-ffmpeg package; source at ffmpeg.org).

Not affiliated with ADInstruments. ADInstruments, LabChart and PowerLab are trademarks of ADInstruments. Adichtion is an independent project that reads the files their software writes, and it is neither made, endorsed nor supported by them. The names appear on this page only to say which file format and which software the project is about.