[1]:

import pyAMARES

pyAMARES.__version__

[1]:

'0.3.15'

Prior Knowledge Spreadsheet for pyAMARES

Try this tutorial on Google Colab!

  • PyAMARES imports prior knowledge from spreadsheets to use as initial values and constraints for fitting MRS data based on the AMARES model function.

  • The prior knowledge spreadsheet can be in CSV or MS Excel (xlsx) format.

  • In this spreadsheet:

    • The upper half defines the initial values.

    • The lower half specifies the fitting constraints.

    • The parameters for a given peak are defined in a column of the spreadsheet.

  • pyAMARES.initialize_FID can be used to load and preview the prior knowledge spreadsheet.

  • Comments: Lines starting with # can be used to add comments to the prior knowledge spreadsheet. In the CSV format, comments cannot be added to the first rows. However, this limitation does not apply to the Excel (xlsx) format.

  • A simple example of peak parameter of a singlet

[2]:

single_obj = pyAMARES.initialize_FID(
    fid=None, priorknowledgefile="attachment/singlet.csv", preview=True
)

Warning, fid is None!
Checking comment lines in the prior knowledge file
Comment: in line 0 #  An example of singlet,,
../_images/notebooks_priorknowledge_3_1.png 
Printing the Prior Knowledge File attachment/singlet.csv
Peak_A Peak_B
Index
Initial Values NaN NaN
amplitude 10 8
chemicalshift 5 -3
linewidth 100 50
phase 0 0
g 0 0
Bounds NaN NaN
amplitude (0, (0,
chemicalshift NaN NaN
linewidth (0, (0,
phase (-180, 180) (-180, 180)
g (0,1) (0,1)

  • Initial Fitting Parameter

    • The parsed initial prior knowledge is converted into an lmfit Parameter object.

    • Each parameter includes initial values, minimum and maximum limits, and a vary flag that indicates whether it is fixed during the fitting process.

    • In addition to editing the input spreadsheet, fitting parameters can also be manually modified in the code.

    • Refinement of Fitted Parameters: The fitted parameters (not shown in this tutorial) will be returned in the same format and can be refined for subsequent rounds of fitting.

Spreadsheet Format

  • Index Column: Always use the terms amplitude, chemicalshift, linewidth, phase, and g as index labels in the spreadsheet for both initial values and constraints

  • Setup Constraints:

    • Constraints are set using brackets. For example, (-180, 180) indicates a range from -180 to 180.

    • If only a lower bound is needed, omit the second half of the bracket. For example, (0, specifies a range of 0 and above.

    • (New after version 0.3.4) If only a single value is specified in a constraint cell, the corresponding parameter is fixed and will not be fitted.

  • Physical Units:

    • In the spreadsheet, the amplitude and g values are unitless. chemicalshift is measured in ppm, linewidth in Hz, and phase in degrees.

Setting Up J-coupling Splitted Multiplets: An Example of In Vivo 31P MRS of the Human Brain at 7T

  • Peak Name Suffix:

    • To set up a multiplet, designate the main sublet peak using ASCII letters, and define other sublets by adding numeric suffixes to the main peak name. For instance, the triplet for \(\beta\)-ATP is labeled BATP, BATP2, and BATP3.

    • Therefore, the numbers are not allowed in other peak names.

    • Similarly, the doublet for \(\gamma\)-ATP is labeled GATP and GATP2.

  • Constraints for Multiplets:

    • Parameters can be constrained using mathematical expressions, which is especially useful for multiplet setups.

    • Multiplets separated by J-coupling share parameters like phase and linewidth (LW). Constraints for these can be linked to the main peak name; for example, BATP in the LW and phase rows.

    • The chemicalshifts of sublets can be constrained relative to the main peak using its peak name and the J-coupling constants. For example, BATP-15Hz indicates the chemicalshift is set 15 Hz lower than that of \(\beta\)-ATP. If ppm is used, it will be converted to Hz using the MHz argument.

    • The amplitude of sublets can be related to the main peak. For instance, with \(\beta\)-ATP as a triplet having 1:2:1 amplitude ratios, the amplitude constraints for the sublets could be set as BATP/2. Similarly, for \(\gamma\)-ATP, where two sublets have a 1:1 amplitude ratio, the amplitude can be set as GATP.

    • Since the prior knowledge dataset spreadsheet is parsed from left to right, the peak that will be mathematically constrained to it must always be put to the left of the peaks that will be constrained. For example, for the multiplets, the main peak, such as BATP, will always be put to the left of BATP2 or BATP3, whose amplitude constraints will be fixed as BATP/2.

[3]:

multiplet_obj = pyAMARES.initialize_FID(
    fid=None,
    priorknowledgefile="./attachment/example_human_brain_31P_7T.csv",
    preview=True,
)

Warning, fid is None!
Checking comment lines in the prior knowledge file
Comment: in line 0 "#  Ren et al, NMR Biomed . 2015 Nov;28(11):1455-62. doi: 10.1002/nbm.3384.",,,,,,,,,,,,,,,,

Comment: in line 14 # Use the same phase for all peaks,,,,,,,,,,,,,,,,

Comment: in line 15 " # 2024/06/24 In Ren et al, the chemical shift range of BATP (0.1 ppm), AATP (0.04 ppm), and GATP (0.02 ppm) are smaller than the J-couplin range (0.125 - 0.25 ppm). ",,,,,,,,,,,,,,,,

Comment: in line 16 "# So, increase the chemical shift range",,,,,,,,,,,,,,,,
../_images/notebooks_priorknowledge_7_1.png 
Printing the Prior Knowledge File ./attachment/example_human_brain_31P_7T.csv
BATP BATP2 BATP3 AATP AATP2 GATP GATP2 UDPG NAD PCr GPC GPE Pin Pex PC PE
Index
Initial Values NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN
amplitude 1.41 BATP/2 BATP/2 1.545 AATP 1.5 GATP 0.08 0.41 4.37 1.32 0.8 0.85 0.3 0.3 2.27
chemicalshift -16.15 BATP-15Hz BATP+15Hz -7.49 AATP-16Hz -2.46 GATP-16Hz -9.72 -8.25 0 2.95 3.5 4.82 5.24 6.24 6.76
linewidth 58.12 BATP BATP 32.28 AATP 39.02 GATP 32.37 40.49 15.41 19.96 19.1 21.04 30.91 19.96 22.63
phase 0 BATP BATP BATP BATP BATP BATP BATP BATP BATP BATP BATP BATP BATP BATP BATP
g 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
Bounds NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN
amplitude (0, (0, (0, (0, (0, (0, (0, (0, (0, (0, (0, (0, (0, (0, (0, (0,
chemicalshift (-16.30,-16.00) (-16.30,-16.00) (-16.30,-16.00) (-7.72,-7.42) (-7.72,-7.42) (-2.65,-2.39) (-2.65,-2.39) (-9.76,-9.68) (-8.25,-8.17) (-0.5, 0.5) (2.94,2.96) (3.49,3.51) (4.81,4.83) (5.19,5.29) (6.22,6.26) (6.71,6.81)
linewidth (54.335, 61.911) (54.335, 61.911) (54.335, 61.911) (31.226, 33.327) (31.226, 33.327) (36.892, 41.157) (36.892, 41.157) (29.125, 35.619) (34.823, 46.155) (13.21, 17.603) (18.557, 21.359) (17.348, 20.849) (19.353, 22.727) (22.091, 39.725) (15.756, 24.16) (20.658, 24.605)
phase (-180, 180) (-180, 180) (-180, 180) (-180, 180) (-180, 180) (-180, 180) (-180, 180) (-180, 180) (-180, 180) (-180, 180) (-180, 180) (-180, 180) (-180, 180) (-180, 180) (-180, 180) (-180, 180)
g (0,1) (0,1) (0,1) (0,1) (0,1) (0,1) (0,1) (0,1) (0,1) (0,1) (0,1) (0,1) (0,1) (0,1) (0,1) (0,1)
# 2024/06/24 In Ren et al, the chemical shift range of BATP (0.1 ppm), AATP (0.04 ppm), and GATP (0.02 ppm) are smaller than the J-couplin range (0.125 - 0.25 ppm). NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN
# So, increase the chemical shift range NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN
NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN

  • Initial Fitting Parameter

[4]:

multiplet_obj.initialParams

[4]:
name value initial value min max vary expression
ak_BATP 1.41000000 1.41 0.00000000 inf True
freq_BATP -1938.00000 -1937.9999999999998 -1956.00000 -1920.00000 True
dk_BATP 182.589365 182.58936502663877 0.00000000 194.499143 True
phi_BATP 0.00000000 0.0 -3.14159265 3.14159265 True
g_BATP 0.00000000 0.0 0.00000000 1.00000000 False
ak_BATP2 0.70500000 0.705 0.00000000 inf False ak_BATP/2
freq_BATP2 -1953.00000 -1952.9999999999998 -1956.00000 -1920.00000 False freq_BATP-15
dk_BATP2 182.589365 182.58936502663877 0.00000000 194.499143 False dk_BATP
phi_BATP2 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_BATP2 0.00000000 0.0 0.00000000 1.00000000 False
ak_BATP3 0.70500000 0.705 0.00000000 inf False ak_BATP/2
freq_BATP3 -1923.00000 -1922.9999999999998 -1956.00000 -1920.00000 False freq_BATP+15
dk_BATP3 182.589365 182.58936502663877 0.00000000 194.499143 False dk_BATP
phi_BATP3 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_BATP3 0.00000000 0.0 0.00000000 1.00000000 False
ak_AATP 1.54500000 1.545 0.00000000 inf True
freq_AATP -898.800000 -898.8000000000001 -926.400000 -890.400000 True
dk_AATP 101.410611 101.41061085787852 0.00000000 104.699858 True
phi_AATP 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_AATP 0.00000000 0.0 0.00000000 1.00000000 False
ak_AATP2 1.54500000 1.545 0.00000000 inf False ak_AATP
freq_AATP2 -914.800000 -914.8000000000001 -926.400000 -890.400000 False freq_AATP-16
dk_AATP2 101.410611 101.41061085787852 0.00000000 104.699858 False dk_AATP
phi_AATP2 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_AATP2 0.00000000 0.0 0.00000000 1.00000000 False
ak_GATP 1.50000000 1.5 0.00000000 inf True
freq_GATP -295.200000 -295.2 -318.000000 -286.800000 True
dk_GATP 122.584945 122.58494534307374 0.00000000 129.298529 True
phi_GATP 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_GATP 0.00000000 0.0 0.00000000 1.00000000 False
ak_GATP2 1.50000000 1.5 0.00000000 inf False ak_GATP
freq_GATP2 -311.200000 -311.2 -318.000000 -286.800000 False freq_GATP-16
dk_GATP2 122.584945 122.58494534307374 0.00000000 129.298529 False dk_GATP
phi_GATP2 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_GATP2 0.00000000 0.0 0.00000000 1.00000000 False
ak_UDPG 0.08000000 0.08 0.00000000 inf True
freq_UDPG -1166.40000 -1166.4 -1171.20000 -1161.60000 True
dk_UDPG 101.693354 101.69335419670159 0.00000000 111.900389 True
phi_UDPG 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_UDPG 0.00000000 0.0 0.00000000 1.00000000 False
ak_NAD 0.41000000 0.41 0.00000000 inf True
freq_NAD -990.000000 -990.0 -990.000000 -980.400000 True
dk_NAD 127.203087 127.20308654385073 0.00000000 145.000209 True
phi_NAD 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_NAD 0.00000000 0.0 0.00000000 1.00000000 False
ak_PCr 4.37000000 4.37 0.00000000 inf True
freq_PCr 0.00000000 0.0 -60.0000000 60.0000000 True
dk_PCr 48.4119428 48.41194279181871 0.00000000 55.3014555 True
phi_PCr 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_PCr 0.00000000 0.0 0.00000000 1.00000000 False
ak_GPC 1.32000000 1.32 0.00000000 inf True
freq_GPC 354.000000 354.0 352.800000 355.200000 True
dk_GPC 62.7061894 62.70618936565227 0.00000000 67.1012775 True
phi_GPC 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_GPC 0.00000000 0.0 0.00000000 1.00000000 False
ak_GPE 0.80000000 0.8 0.00000000 inf True
freq_GPE 420.000000 420.0 418.800000 421.200000 True
dk_GPE 60.0044197 60.004419683565054 0.00000000 65.4990652 True
phi_GPE 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_GPE 0.00000000 0.0 0.00000000 1.00000000 False
ak_Pin 0.85000000 0.85 0.00000000 inf True
freq_Pin 578.400000 578.4000000000001 577.200000 579.600000 True
dk_Pin 66.0991094 66.09910943152924 0.00000000 71.3989762 True
phi_Pin 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_Pin 0.00000000 0.0 0.00000000 1.00000000 False
ak_Pex 0.30000000 0.3 0.00000000 inf True
freq_Pex 628.800000 628.8000000000001 622.800000 634.800000 True
dk_Pex 97.1066289 97.1066289224605 0.00000000 124.799768 True
phi_Pex 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_Pex 0.00000000 0.0 0.00000000 1.00000000 False
ak_PC 0.30000000 0.3 0.00000000 inf True
freq_PC 748.800000 748.8000000000001 746.400000 751.200000 True
dk_PC 62.7061894 62.70618936565227 0.00000000 75.9008785 True
phi_PC 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_PC 0.00000000 0.0 0.00000000 1.00000000 False
ak_PE 2.27000000 2.27 0.00000000 inf True
freq_PE 811.200000 811.1999999999999 805.200000 817.200000 True
dk_PE 71.0942418 71.09424175073701 0.00000000 77.2988872 True
phi_PE 0.00000000 0.0 -3.14159265 3.14159265 False phi_BATP
g_PE 0.00000000 0.0 0.00000000 1.00000000 False

Use a Single Value in the Constraint Cell to Fix the Corresponding Parameter (New after version 0.3.4)

[5]:

FixExampleObj = pyAMARES.initialize_FID(
    fid=None, priorknowledgefile="./attachment/Table1.csv", preview=True
)

Warning, fid is None!
Checking comment lines in the prior knowledge file
Comment: in line 13 # Index of JMRUI,Cr_3,Cr_3.9,Glu_2.3,Glx_3.7,Ins_3.5,Ins_3.6,Ins_4,NAA_2,NAA_2.5,NAA_2.6,Tau_3.4,Tau_3.2
../_images/notebooks_priorknowledge_11_1.png 
Printing the Prior Knowledge File ./attachment/Table1.csv
Cr_a Cr_b Glu Glx Ins Ins2 Ins_b NAA_a NAA NAA2 Tau Tau2
Index
Initial Values NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN
amplitude 2.5 16 5 6 2.55 Ins 1 4 5.25 NAA 7 Tau
chemicalshift 3.021495 3.92 2.346443 3.762504 3.523662 3.620098 4.042568 1.984933 2.499841 2.659735 3.259837 3.418482
linewidth 3 14.3 19 3.5 2.6 7.9 2.6 2.2 13 NAA 3.5 Tau
phase 0 0 0 0 0 0 0 0 0 0 180 180
g 0 0 0 0 0 0 0 0 0 0 0 0
Bounds NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN
amplitude (2.4, 2.6) (15.0, 17.0) (4.5, 5.5) (5.4, 6.6) (2.3, 2.8) (2.3, 2.8) (0.9, 1.1) (3.6, 4.4) (5.0, 5.5) (5.0, 5.5) (6.7, 7.3) (6.7, 7.3)
chemicalshift (3.02, 3.03) 3.92 2.35 3.75 3.52 (3.61, 3.62) (4.03, 4.04) (2.0, 2.01) (2.51, 2.52) (2.66, 2.67) (3.41, 3.42) (3.24, 3.25)
linewidth (12, 15) 20 20 (22,25) 20 20 20 (10, 18) (18.0, 22.0) (18.0, 22.0) 20 20
phase 0 0 0 0 0 0 0 180 0 0 180 180
g 0 0 0 0 0 0 0 0 0 0 0 0

  • In this prior knowledge spreadsheet, the phases are fixed at either 0 or 180, as determined by the single-value constraint cells. As shown in the initial fitting parameters below, all phase parameters are fixed (vary=False) and will not be fitted.

[6]:

loadedpk_pd = pyAMARES.parameters_to_dataframe(FixExampleObj.initialParams)
loadedpk_pd.loc[loadedpk_pd.name.str.startswith("phi")]

[6]:
name value min max vary expr
3 phi_Cr_a 0.000000 -inf inf False None
8 phi_Cr_b 0.000000 -inf inf False None
13 phi_Glu 0.000000 -inf inf False None
18 phi_Glx 0.000000 -inf inf False None
23 phi_Ins 0.000000 -inf inf False None
28 phi_Ins2 0.000000 -inf inf False None
33 phi_Ins_b 0.000000 -inf inf False None
38 phi_NAA_a 3.141593 -inf inf False None
43 phi_NAA 0.000000 -inf inf False None
48 phi_NAA2 0.000000 -inf inf False None
53 phi_Tau 3.141593 -inf inf False None
58 phi_Tau2 3.141593 -inf inf False None