|
1 | 1 | <div className="prose"> |
2 | 2 | <div className="hero"> |
3 | 3 | <h1 className="heroTitle">Getting Started</h1> |
4 | | - <p className="heroSubtitle">Install Metbit from PyPI and run your first analysis.</p> |
| 4 | + <p className="heroSubtitle">Install metbit, prepare your data, and run the first PCA or OPLS-DA model.</p> |
5 | 5 | </div> |
6 | 6 |
|
7 | 7 | <div className="callout info"> |
8 | | - <strong>Requirements:</strong> Python 3.9+ (3.10/3.11 recommended), pip or conda/mamba with pip. |
| 8 | + <strong>Requirements:</strong> Python 3.10+ is recommended. The package depends on the scientific Python stack, Plotly, Dash, nmrglue, and pybaselines. |
9 | 9 | </div> |
10 | 10 |
|
11 | 11 | <h2>Install</h2> |
|
15 | 15 | <summary><b>Use a virtual environment</b></summary> |
16 | 16 | <pre><code>{`python -m venv .venv |
17 | 17 | source .venv/bin/activate # Windows: .venv\\Scripts\\activate |
| 18 | +python -m pip install --upgrade pip |
18 | 19 | pip install metbit`}</code></pre> |
19 | 20 | </details> |
20 | 21 |
|
21 | | - <h2>Minimal Example</h2> |
| 22 | + <h2>Import public APIs</h2> |
| 23 | + <p>Most commonly used classes and functions are exported from the package root.</p> |
| 24 | + <pre><code>{`from metbit import ( |
| 25 | + nmr_preprocessing, |
| 26 | + Normalization, |
| 27 | + Normalise, |
| 28 | + pca, |
| 29 | + opls_da, |
| 30 | + STOCSY, |
| 31 | +)`}</code></pre> |
| 32 | + |
| 33 | + <h2>Option 1: Start from a feature table</h2> |
| 34 | + <p>Use this route when your spectra are already represented as a table where rows are samples and columns are spectral variables.</p> |
22 | 35 | <div className="twoCol"> |
23 | 36 | <div> |
24 | 37 | <ol className="steps"> |
25 | | - <li>Load your data (X = features, y = classes)</li> |
26 | | - <li>Fit OPLS‑DA and compute VIP scores</li> |
27 | | - <li>Visualize important features</li> |
| 38 | + <li>Load a CSV file with a class or group column.</li> |
| 39 | + <li>Separate <code>X</code> features from <code>y</code> labels.</li> |
| 40 | + <li>Normalize the feature table.</li> |
| 41 | + <li>Fit PCA for exploration or OPLS-DA for binary class modeling.</li> |
28 | 42 | </ol> |
29 | 43 | </div> |
30 | 44 | <div> |
31 | 45 | <pre><code>{`import pandas as pd |
32 | | -from metbit.metbit import opls_da |
| 46 | +from metbit import Normalization, pca, opls_da |
| 47 | +
|
| 48 | +df = pd.read_csv("spectra.csv") |
| 49 | +y = df["Group"] |
| 50 | +X = df.drop(columns=["Group"]) |
| 51 | +features = X.columns.astype(float) |
33 | 52 |
|
34 | | -df = pd.read_csv('your_data.csv') |
35 | | -y = df['Group'] |
36 | | -X = df.drop(columns=['Group']) |
| 53 | +X_norm = Normalization.pqn_normalization(X) |
| 54 | +
|
| 55 | +pca_model = pca( |
| 56 | + X=X_norm, |
| 57 | + label=y, |
| 58 | + features_name=features, |
| 59 | + n_components=2, |
| 60 | + scaling_method="pareto", |
| 61 | +) |
| 62 | +pca_model.fit() |
| 63 | +pca_model.plot_pca_scores().show() |
37 | 64 |
|
38 | | -model = opls_da( |
39 | | - X, y, |
40 | | - features_name=list(X.columns), n_components=2, |
41 | | - scaling_method='pareto', kfold=3, |
42 | | - estimator='opls', random_state=94, auto_ncomp=True |
| 65 | +opls_model = opls_da( |
| 66 | + X=X_norm, |
| 67 | + y=y, |
| 68 | + features_name=features, |
| 69 | + n_components=2, |
| 70 | + scaling_method="pareto", |
| 71 | + kfold=3, |
| 72 | + estimator="opls", |
| 73 | + auto_ncomp=True, |
43 | 74 | ) |
44 | | -model.fit() |
45 | | -fig = model.vip_plot(threshold=1.0) |
46 | | -fig.show()`}</code></pre> |
| 75 | +opls_model.fit() |
| 76 | +opls_model.plot_oplsda_scores().show() |
| 77 | +opls_model.vip_plot(threshold=1.0).show()`}</code></pre> |
47 | 78 | </div> |
48 | 79 | </div> |
49 | 80 |
|
50 | | - <h2>Preprocessing (optional)</h2> |
51 | | - <div className="callout"> |
52 | | - Use Metbit utilities to prepare spectra before modeling. |
53 | | - </div> |
54 | | - <pre><code>{`from metbit.nmr_preprocess import nmr_preprocessing |
55 | | -from metbit.utility import Normalise |
| 81 | + <h2>Option 2: Start from Bruker FID folders</h2> |
| 82 | + <p>Use <code>nmr_preprocessing</code> when your input is a Bruker project folder containing one or more sample directories with <code>fid</code> files.</p> |
| 83 | + <pre><code>{`from metbit import nmr_preprocessing, Normalization |
| 84 | +
|
| 85 | +nmr = nmr_preprocessing( |
| 86 | + data_path="path/to/bruker_project", |
| 87 | + bin_size=0.0005, |
| 88 | + auto_phasing=True, |
| 89 | + fn_="acme", |
| 90 | + baseline_correction=True, |
| 91 | + baseline_type="corrector", |
| 92 | + calibration=True, |
| 93 | + calib_type="tsp", |
| 94 | + align=False, |
| 95 | +) |
| 96 | +
|
| 97 | +X = nmr.get_data() |
| 98 | +ppm = nmr.get_ppm() |
| 99 | +metadata = nmr.get_metadata() |
56 | 100 |
|
57 | | -prep = nmr_preprocessing(...) |
58 | | -X = prep.X # DataFrame`}</code></pre> |
| 101 | +X_norm = Normalization.pqn_normalization(X)`}</code></pre> |
59 | 102 |
|
60 | | - <h2>Next Steps</h2> |
61 | | - <p> |
62 | | - <a className="btn" href="/docs/api">Browse Full API →</a> |
63 | | - <span style={{ marginLeft: 8 }} /> |
64 | | - <a className="btn secondary" href="/docs/overview">Explore Overview</a> |
65 | | - </p> |
| 103 | + <h2>Recommended project structure</h2> |
| 104 | + <pre><code>{`project/ |
| 105 | + data/ |
| 106 | + raw_bruker/ |
| 107 | + processed/ |
| 108 | + notebooks/ |
| 109 | + results/ |
| 110 | + figures/ |
| 111 | + tables/ |
| 112 | + scripts/ |
| 113 | + run_preprocessing.py |
| 114 | + run_models.py`}</code></pre> |
66 | 115 |
|
| 116 | + <h2>Common next steps</h2> |
67 | 117 | <ul> |
68 | | - <li>nmr_preprocess: <a href="/docs/api/nmr_preprocess">/docs/api/nmr_preprocess</a></li> |
69 | | - <li>Modeling (opls_da, pca): <a href="/docs/api/metbit">/docs/api/metbit</a></li> |
70 | | - <li>Utilities (Normalise, UnivarStats): <a href="/docs/api/utility">/docs/api/utility</a></li> |
| 118 | + <li>Preprocessing and Bruker import: <a href="/docs/api/nmr_preprocess">/docs/api/nmr_preprocess</a></li> |
| 119 | + <li>Normalization: <a href="/docs/api/spec_norm">/docs/api/spec_norm</a></li> |
| 120 | + <li>PCA and OPLS-DA: <a href="/docs/api/metbit">/docs/api/metbit</a></li> |
| 121 | + <li>STOCSY exploration: <a href="/docs/api/STOCSY">/docs/api/STOCSY</a></li> |
| 122 | + <li>Dash apps: <a href="/docs/api/ui_stocsy">/docs/api/ui_stocsy</a> and <a href="/docs/api/ui_picky_peak">/docs/api/ui_picky_peak</a></li> |
71 | 123 | </ul> |
72 | 124 | </div> |
0 commit comments