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-ncFSL Licence: non-commercial use only experimental - clean room
larmorxApache-2.0 experimental
- replica
- 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
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):
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
Usage: extracttxt search_word file [num_trailing_lines [relative_start]]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",
) -> strWhere 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 Nn_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-roomimplementation="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.
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'larmorx fsl extracttxt value log.txt 3 -1Ports
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-ncholds it (crates-nc/), under the FSL Licence’s terms, andlarmorxruns it as a separate program,larmorx-nc fsl <program>, whenlarmorx-ncis installed (pip install larmorx-nc). - The clean room is written from
specs/flirt.mdby an implementer who never read FSL’s source or the replica. It is part oflarmorx, 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: