Skip to content

Commit c9b6ea7

Browse files
mkumar73mkumar73
committed
docs(getting_started): add v1 to v2 migration guide
1 parent 7a6733b commit c9b6ea7

5 files changed

Lines changed: 221 additions & 2 deletions

File tree

‎docs/getting_started/faq.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ You only pass the configs you want to change; `MambularClassifier()` uses sensib
3535
v2.0 is not backward compatible with v1, and v1 is no longer maintained. If you need to stay on v1, pin `deeptab<2.0`, but note that the v1 branch receives no bug fixes or security updates.
3636
```
3737

38+
For a step-by-step upgrade walkthrough, see [Migrating from v1 to v2](migration).
39+
3840
See the [Overview](overview) for the full v2 data API, and the [homepage](../index) for the complete list of new features.
3941

4042
### Which model should I use?

‎docs/getting_started/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ trained model, and answer the most common questions along the way.
1111
- **[Installation](installation)**: Setup, GPU support, and optional kernels
1212
- **[Quickstart](quickstart)**: Train your first models in a few minutes
1313
- **[FAQ](faq)**: Common questions, v1 support, and troubleshooting
14+
- **[Migrating from v1 to v2](migration)**: Upgrade an existing v1 codebase

‎docs/getting_started/migration.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# Migrating from v1 to v2
2+
3+
DeepTab v2 keeps the part of v1 you use most, the `fit` / `predict` / `evaluate`
4+
workflow, and rebuilds everything around it. The package layout, the configuration
5+
objects, and a handful of import paths changed, so existing v1 code needs a few
6+
edits before it runs on v2. This page walks through each change and shows the
7+
before and after side by side.
8+
9+
```{warning}
10+
**v2 is not backward compatible with v1, and v1 is no longer maintained.** The v1
11+
branch receives no bug fixes or security updates. If you are not ready to upgrade,
12+
pin `deeptab<2.0` for now and plan the move when you can.
13+
```
14+
15+
## Before you upgrade
16+
17+
Pin the major version you are testing against so an upgrade never surprises a
18+
running pipeline:
19+
20+
```bash
21+
pip install "deeptab>=2.0,<3.0"
22+
```
23+
24+
Most projects only touch two things: how the estimator is constructed, and a few
25+
import lines. If your code only ever called `Model().fit(...)` and `predict(...)`
26+
with default settings, the change is small. If you reached into internal modules,
27+
read the [Import paths](import-paths) section closely.
28+
29+
## The change almost every project needs: split configs
30+
31+
In v1, architecture, preprocessing, and training options were all flat keyword
32+
arguments on the estimator. In v2 those same options live in three focused config
33+
objects, so you can tune one concern without disturbing the others.
34+
35+
```python
36+
# v1: every option flat on the estimator
37+
from deeptab.models import MambularClassifier
38+
39+
model = MambularClassifier(
40+
d_model=128,
41+
n_layers=4,
42+
numerical_preprocessing="ple",
43+
lr=1e-3,
44+
)
45+
```
46+
47+
```python
48+
# v2: options grouped by concern
49+
from deeptab.models import MambularClassifier
50+
from deeptab.configs import MambularConfig, PreprocessingConfig, TrainerConfig
51+
52+
model = MambularClassifier(
53+
model_config=MambularConfig(d_model=128, n_layers=4), # architecture
54+
preprocessing_config=PreprocessingConfig(numerical_preprocessing="ple"), # features
55+
trainer_config=TrainerConfig(lr=1e-3), # training
56+
)
57+
```
58+
59+
Each option moves to the config that owns its concern:
60+
61+
| Where the v1 argument went | Lives in v2 on | Typical fields |
62+
| -------------------------- | --------------------- | ---------------------------------------------------------------- |
63+
| Neural architecture | `<Model>Config` | `d_model`, `n_layers`, `n_heads`, `dropout`, `layer_sizes` |
64+
| Feature handling | `PreprocessingConfig` | `numerical_preprocessing`, `categorical_preprocessing`, `n_bins` |
65+
| Training and optimizer | `TrainerConfig` | `max_epochs`, `batch_size`, `lr`, `patience`, `optimizer_type` |
66+
67+
```{important}
68+
The flat keyword arguments from v1 are no longer accepted. Passing them, for
69+
example `MambularClassifier(d_model=128)`, now raises a `TypeError`. Move every
70+
setting into the matching config object.
71+
```
72+
73+
```{tip}
74+
All three configs are optional. `MambularClassifier()` with no arguments uses
75+
sensible defaults for architecture, preprocessing, and training, so you only build
76+
the configs whose defaults you actually want to change.
77+
```
78+
79+
For the full field reference and which config owns each setting, see the
80+
[Config System](../core_concepts/config_system) guide.
81+
82+
## Config class renames
83+
84+
The configuration classes dropped their `Default` prefix. The rename is mechanical,
85+
so a find and replace across your codebase covers it.
86+
87+
| v1 | v2 |
88+
| ---------------------------- | --------------------- |
89+
| `DefaultMambularConfig` | `MambularConfig` |
90+
| `DefaultFTTransformerConfig` | `FTTransformerConfig` |
91+
| `Default<Arch>Config` | `<Arch>Config` |
92+
93+
```python
94+
# v1
95+
from deeptab.models import DefaultMambularConfig
96+
97+
# v2
98+
from deeptab.configs import MambularConfig
99+
```
100+
101+
```{note}
102+
Config classes now live under `deeptab.configs`, not alongside the models. Importing
103+
them from `deeptab.configs` is the supported path going forward.
104+
```
105+
106+
(import-paths)=
107+
108+
## Import paths
109+
110+
The internal package layout was reorganised under the `deeptab` namespace. The
111+
high-level estimators are still imported from `deeptab.models`, but supporting
112+
pieces moved to dedicated subpackages:
113+
114+
| What you import | v2 location |
115+
| ---------------------------------------------------------------- | ----------------------- |
116+
| Estimators (`MambularClassifier`, ...) | `deeptab.models` |
117+
| Config objects | `deeptab.configs` |
118+
| Data layer | `deeptab.data` |
119+
| Distributions for `LSS` | `deeptab.distributions` |
120+
| Metrics | `deeptab.metrics` |
121+
| Top-level helpers (`InferenceModel`, `set_seed`, `seed_context`) | `deeptab` |
122+
123+
```{tip}
124+
If an import fails after upgrading, check whether you were importing from an
125+
internal v1 module. Code that only used the public estimator and config imports
126+
above needs the least work.
127+
```
128+
129+
## Data layer renames
130+
131+
The data modules were renamed to give the pipeline a clear, typed contract:
132+
133+
| v1 | v2 |
134+
| ------------------------------- | ------------------- |
135+
| `Mambular*` data module aliases | `TabularDataModule` |
136+
| `Mambular*` dataset aliases | `TabularDataset` |
137+
138+
The v2 data layer also adds `FeatureSchema`, an inspectable description of the
139+
columns a model expects, their order, and their types. You rarely build these by
140+
hand; DeepTab constructs them from your data during `fit` and stores the schema
141+
inside saved artifacts. The old `Mambular*` aliases are deprecated.
142+
143+
## Saving, loading, and serving
144+
145+
Persistence in v2 goes through a single self-describing `.deeptab` artifact that
146+
bundles the architecture, feature schema, preprocessing, task type, and package
147+
versions alongside the weights. A saved model therefore carries everything it needs
148+
to reload itself.
149+
150+
```python
151+
# Save a fitted estimator
152+
clf.save("churn_model.deeptab")
153+
154+
# Load it back as a full estimator
155+
from deeptab.models import MambularClassifier
156+
clf = MambularClassifier.load("churn_model.deeptab")
157+
158+
# Or load a read-only serving surface
159+
from deeptab import InferenceModel
160+
served = InferenceModel.from_path("churn_model.deeptab")
161+
predictions = served.predict(X_new)
162+
```
163+
164+
```{note}
165+
`InferenceModel` exposes only prediction and input-validation methods. Training is
166+
deliberately absent, so a served model cannot be re-fitted by accident. See
167+
[Inference](../core_concepts/inference) for the full serving surface.
168+
```
169+
170+
## Experimental models
171+
172+
The experimental models, ModernNCA, Tangos, and Trompt, import from a separate
173+
namespace so their less stable status is explicit:
174+
175+
```python
176+
from deeptab.models.experimental import ModernNCAClassifier, TangosRegressor, TromptClassifier
177+
```
178+
179+
```{warning}
180+
Experimental models may change in minor releases. Pin an exact version, for example
181+
`deeptab==2.0.0`, if you depend on one in production.
182+
```
183+
184+
## What did not change
185+
186+
The day-to-day modeling surface is intentionally stable:
187+
188+
- `fit`, `predict`, `predict_proba`, and `evaluate` behave exactly as in v1.
189+
- DeepTab is still scikit-learn compatible, including use inside `GridSearchCV`.
190+
- Every architecture still ships as a classifier, a regressor, and a distributional
191+
(`LSS`) variant sharing one interface.
192+
- Automatic preprocessing and feature-type detection still run for you.
193+
194+
## Upgrade checklist
195+
196+
Use this as a quick pass over a v1 codebase:
197+
198+
1. Pin `deeptab>=2.0,<3.0` and install into a clean environment.
199+
2. Move flat estimator arguments into `MambularConfig` / `PreprocessingConfig` /
200+
`TrainerConfig` (or the config for your model).
201+
3. Rename `Default<Arch>Config` to `<Arch>Config` and import it from
202+
`deeptab.configs`.
203+
4. Update imports: estimators from `deeptab.models`, configs from `deeptab.configs`,
204+
data classes from `deeptab.data`.
205+
5. Replace any `Mambular*` data module or dataset references with
206+
`TabularDataModule` and `TabularDataset`.
207+
6. Run your training script. A `TypeError` on the estimator constructor almost
208+
always means a setting still needs to move into a config object.
209+
210+
```{seealso}
211+
The [FAQ](faq) answers common upgrade questions and the v1 support policy. The
212+
[Config System](../core_concepts/config_system) guide is the authoritative field
213+
reference for the three config objects.
214+
```

‎docs/homepage.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,9 @@ things changed that affect existing code:
5555
`Mambular*` aliases are deprecated.
5656
5757
If you need to stay on v1 for now, pin `deeptab<2.0`. Note that the v1 branch receives
58-
no bug fixes or security updates. See the [FAQ](getting_started/faq) for the full
59-
support policy and migration notes.
58+
no bug fixes or security updates. See the [migration guide](getting_started/migration)
59+
for a step-by-step upgrade walkthrough, and the [FAQ](getting_started/faq) for the
60+
full support policy.
6061
```
6162

6263
The high-level `fit`/`predict`/`evaluate` workflow is unchanged. In most cases only

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
getting_started/installation
1212
getting_started/quickstart
1313
getting_started/faq
14+
getting_started/migration
1415

1516
.. toctree::
1617
:caption: Core Concepts

0 commit comments

Comments
 (0)