Programs · FSL

extracttxt

extracttxt is a script that prints the lines of a text file from the first line that matches a word.

Original
FSL 6.0.7.23
Command line
larmorx fsl extracttxt
Python
lx.fsl.extracttxt
Ports
  • replica larmorx-nc FSL Licence: non-commercial use only experimental
  • clean room larmorx Apache-2.0 experimental
Evidence
every comparison with FSL
Source
made from docs/api/fsl-flirt.md and the code

What it does

The word is a basic regular expression, as grep reads it. With a count, it prints that many lines, from a given number of lines after the match (before it, when the number is negative), and FSL’s messages for ranges before the first line.

Command line

text
larmorx fsl extracttxt search_word file [num_trailing_lines [relative_start]]

Everything after larmorx fsl extracttxt is the original’s command line: the arguments of FSL 6.0.7.23’s extracttxt, as FSL takes them. LARMORX’s own options stand between larmorx and the family fsl, so they never meet the original’s (below):

text
larmorx
        [--n-threads N]
        [--implementation auto|replica|clean-room]
        [--upstream-defects fix|reproduce]
        fsl extracttxt ...

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

extracttxt's usage text, as the clean room prints it
text
Usage: extracttxt search_word file [num_trailing_lines [relative_start]]

Python

python
lx.fsl.extracttxt(
    search_word: str,
    file: str | os.PathLike,
    trailing_lines: int | None = None,
    relative_start: int | None = None,
    *,
    n_threads: int = 1,
    implementation: ImplementationName = "auto",
) -> str

Where ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room").

FSL’s extracttxt: the lines of file from the first that matches search_word (a basic regular expression, as grep reads it) to the end, or trailing_lines of them, starting relative_start lines after (or before) the match.

The result is the text printed, as a string. relative_start needs trailing_lines.

Options

Each row joins an option of the original’s command line with the Python argument that does the same. The rows are checked against the code at every test run: the options extracttxt accepts (crates/larmorx-fsl/src/cli/extracttxt.rs) and the arguments of lx.fsl.extracttxt (python/larmorx/fsl/flirt_more.py), whose defaults and descriptions are taken from it. Under each option, in grey, FSL’s own help for it.

extracttxt arguments Python Default Notes
search_word search_word a basic regular expression
file file
num_trailing_lines trailing_lines None without it, every line to the end
relative_start relative_start None lines after the match, or before it when negative

LARMORX’s own options

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

They stand between larmorx and fsl on the command line (larmorx --n-threads 4 fsl extracttxt ...); lx.fsl.extracttxt takes n_threads and implementation as arguments, and the other is the command line’s only. Each one given wins over its environment variable, which keeps working.

Command line, then Python What it does
--n-threads N
n_threads=1
Threads (0 = all), given to the program as OMP_NUM_THREADS; the result does not depend on it. Default: every logical CPU on the command line (0), 1 in Python. The variable OMP_NUM_THREADS in 0.1.0rc1.
--implementation auto|replica|clean-room
implementation="auto"
"auto" (default): the replica when larmorx-nc is installed, else the clean room; "replica" or "clean-room" ("original", 0.1.0rc1’s spelling, still works). The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
(no Python argument)
The command line’s only: lx.fsl.extracttxt takes no upstream_defects. The variable LARMORX_UPSTREAM_DEFECTS in 0.1.0rc1.

Examples

The tests run every example below (validation/tests/test_reference.py), each section in a new folder where these inputs are made first: log.txt (a text of five lines, two of them with the word value). The command lines run as python -m larmorx.

python
import larmorx as lx

# Three lines, from the line before the first that holds "value".
text = lx.fsl.extracttxt("value", "log.txt", 3, -1)
text  # -> 'start\nfirst value 1\nmiddle\n'
bash
larmorx fsl extracttxt value log.txt 3 -1

Ports

extracttxt has two ports: a replica and a clean room.

Port Package Licence Status Records
replica larmorx-nc FSL Licence: non-commercial use only experimental fsl-flirt-replica
clean room larmorx Apache-2.0 experimental fsl-flirt

Both ports are complete (specs/flirt.md §15.8). The clean room has its own POSIX basic regular expressions (with GNU grep’s extensions) and the script’s dc and sed arithmetic, messages included. GNU sed’s usage text, which a range read as sed’s options prints, is not reproduced: one LARMORX line takes its place. Refused, as the spec says: arguments that the script’s shell would split or expand, counts and starts that are not integers, and files with NUL bytes.

The replica’s record holds 13 cases of extracttxt: 8 identical to FSL, 5 where both refuse alike. The clean room’s holds 12: 8 within its thresholds, 4 refused alike.

FSL’s licence allows non-commercial use only, so each of FLIRT’s programs has two ports, a replica and a clean room, in different packages (licensing says what each package holds):

  • The replica is translated from FSL’s source. The package larmorx-nc holds it (crates-nc/), under the FSL Licence’s terms, and larmorx runs it as a separate program, larmorx-nc fsl <program>, when larmorx-nc is installed (pip install larmorx-nc).
  • The clean room is written from specs/flirt.md by an implementer who never read FSL’s source or the replica. It is part of larmorx, under Apache-2.0 (crates/larmorx-fsl, with its PROVENANCE, section “FLIRT”), and runs on LARMORX’s clean-room registration engine, the head-motion correction’s (lx.mri.hmc).

implementation="auto" runs the replica when larmorx-nc is installed, and the clean room otherwise. "replica" and "clean-room" choose one ("original", 0.1.0rc1’s spelling of "clean-room", still works); "clean-room" runs the clean room in this process. On the command line, --implementation auto|replica|clean-room before the family chooses alike, from the next release; in 0.1.0rc1 the variable LARMORX_IMPLEMENTATION chooses (original for the clean room).

Evidence

How each of extracttxt’s ports was measured against FSL, case by case: its evidence.

More in the repository

The API page docs/api/fsl-flirt.md holds what extracttxt shares with the page’s other programs: