.. _basis_tools:

Basis Spectra Manipulation
==========================

basis_tools
-----------
The :code:`basis_tools` script provides the user with tools for manipulating basis spectra in the FSL-MRS JSON format.

Provide one of the following subcommands with :code:`basis_tools` to convert, scale, add to, difference, or shift basis spectra.

info
****
| *Example* :code:`basis_tools info path/to/my/basis`
| Provides a short summary of the contents of the basis set.

vis
***
| *Example* :code:`basis_tools vis path/to/my/basis --ppmlim 0.2 4.2`
| Provides visualisation of the basis set.

convert
*******
| *Example* :code:`basis_tools convert path/to/my/otherbasis path/to/my/fslbasis`
| Convert LCModel (.Basis), LCModel (directory of .raw), Osprey (.mat) or JMRUI (.txt) format basis sets to FSL-MRS (.json) format.
| Note that for .Basis or .mat formats, the absolute path to the file should be provided; whereas for .raw or .txt formats, the path to the parent folder should.
| Available options are:
|   - `--bandwidth` and `--fieldstrength` must be provided for defining the spectral bandwidth and field strength in .raw format
|   - `--nucleus` may be provided for defining the resonant nucleus in LCmodel format (.Basis or .raw)
|   - `--description` may be provided for naming the FID repetitions in .mat format
|   - `--remove_reference` may be provided for removing the reference peak from the basis sets
|   - `--hlsvd` may be provided for using HLSVD peak removal (to be used in conjunction with `--remove_reference`)

add
***
| *Example* :code:`basis_tools add --scale --name my_new_basis my_new_basis.json path/to/my/fslbasis`
| Add a json formatted basis spectrum to an existing basis set.

shift
*****
| *Example* :code:`basis_tools shift path/to/my/fslbasis NAA 1.0 path/to/my/edited_fslbasis`
| Shift a basis spectrum on the chemical shift axis.

scale
*****
| *Example* :code:`basis_tools shift path/to/my/fslbasis NAA path/to/my/scaled_fslbasis`
| Rescale a basis spectrum to the mean of all other basis spectra (or to specified target :code:`--target_scale`.

diff
****
| *Example* :code:`basis_tools diff --add_or_sub sub mega_on mega_off mega_diff`
| Form a basis set for a difference method using two other basis set. Add or subtract using :code:`--add_or_sub {'add'|'sub}`.

add_set
*******
| *Example* :code:`basis_tools add_set --add_MM basis_without_mm/ basis_with_default_mm/`
| Add a (predefined) set of Gaussian peaks to a basis set. Three default sets are defined:
| 1) The FSL 'default' with peaks at 0.9, 1.2, 1.4, 1.7 ppm and a linked set at 2.08 & 3.0 ppm
| 2) The (experimental) MEGA edited MM peaks at 0.915 & 3.0 ppm (ratio of 3.75:2.0).
| 3) A water peak at 4.65 ppm
| The other options (:code:`--gamma --sigma`) allow a custom set of peaks to be specified.