quick-start guide (DAT-971)

README.md

@@ -119,6 +119,14 @@ datamint-upload /path/to/dicoms \
 ```
 Use `--ai-model` when uploaded segmentation files should be linked to an existing deployed model by name. `--segmentation_names` accepts YAML mappings and ITK-SNAP label export CSV/TXT files.
 
+### Scaffold a New Project
+
+```bash
+datamint-init
+```
+
+Generates a numbered set of scripts (`01_upload_data.py` through `06_deploy.py`) for your task (detection, segmentation, or classification). Run it once in a new directory and follow the scripts in order.
+
 ### Configuration Management
 
 ```bash

docs/source/getting_started.rst

@@ -1,32 +1,23 @@
-Getting Started with Datamint Python API
+Quick Start
 =========================================
 
 This guide will help you set up and start using the Datamint Python API for your medical imaging projects.
 
-Prerequisites
-=============
-
-- **Python 3.10 or later** (earlier versions are not supported)
-- **pip** or **conda** for package management
-- A **Datamint account** with an API key (get one at `app.datamint.io <https://app.datamint.io/>`_)
-
 Installation
 ============
 
-Datamint requires Python 3.10+.
-Install/update Datamint and its dependencies using pip
+Datamint requires Python 3.10+ and a `Datamint account <https://app.datamint.io/>`_ with an API key.
 
 .. code-block:: bash
 
     pip install -U datamint
 
-We recommend that you install Datamint in a dedicated virtualenv, to avoid conflicting with your system packages.
-You can do this by running:
+We recommend a dedicated virtualenv to avoid conflicting with your system packages:
 
 .. code-block:: bash
 
     python3 -m venv datamint-env
-    source datamint-env/bin/activate  # In Windows, run datamint-env\Scripts\activate.bat
+    source datamint-env/bin/activate  # Windows: datamint-env\Scripts\activate.bat
     pip install -U datamint
 
 Verify your installation
@@ -35,10 +26,49 @@ Verify your installation
 .. code-block:: bash
 
     python -c "import datamint; print(datamint.__version__)"
-    datamint-config --help
 
 .. include:: setup_api_key.rst
 
+Scaffold your first project
+===========================
+
+``datamint-init`` generates a ready-to-run set of numbered scripts tailored to your task
+(detection, segmentation, or classification):
+
+.. code-block:: bash
+
+    datamint-init
+
+It asks for a project name and task type, then writes six scripts into a new directory
+(upload data, explore, build a dataset, train, evaluate, and deploy), so you can follow
+them in order without writing boilerplate.
+
+Your first API call
+===================
+
+Once installed and configured, verify everything works end-to-end:
+
+.. code-block:: python
+
+    from datamint import Api
+
+    api = Api()
+    for project in api.projects.get_all():
+        print(project.name)
+
+.. tip::
+
+    Want to see full end-to-end examples? Browse our :doc:`tutorial notebooks <tutorials>` —
+    they cover real datasets, training workflows, and deployment from scratch.
+
+Next Steps
+----------
+
+- Master the command-line interface: :ref:`command_line_tools`
+- Check out our Python API documentation: :ref:`client_python_api`
+- Our PyTorch, Lightning and MLflow integration: :ref:`pytorch_integration`
+- Use the built-in Trainer API and custom model integration patterns: :ref:`trainer_api`
+
 Troubleshooting
 ---------------
 
@@ -66,14 +96,3 @@ Troubleshooting
     .. code-block:: bash
 
         datamint-config
-
-Next Steps
-----------
-
-Now that you have the basics set up, explore these advanced topics:
-
-- Master the command-line interface: :ref:`command_line_tools`
-- Check out our Python API documentation: :ref:`client_python_api`
-- Our PyTorch, Lightning and MLflow integration: :ref:`pytorch_integration`
-- Use the built-in Trainer API and custom model integration patterns: :ref:`trainer_api`
-- Browse tutorial notebooks: :doc:`tutorials`

docs/source/tutorials.rst

@@ -1,33 +1,53 @@
 Tutorials
 =========
 
-This section lists the various tutorial notebooks available in the `datamint-python-api GitHub repository <https://github.com/SonanceAI/datamint-python-api/tree/main/notebooks>`_. You can run these Jupyter Notebooks locally to learn how to use the Datamint Python API in different scenarios.
+The notebooks below are available in the `notebooks/ directory <https://github.com/SonanceAI/datamint-python-api/tree/main/notebooks>`_
+of the GitHub repository. Run them locally to learn how to use the Datamint Python API across different scenarios.
 
-Data Management
+Getting Started
 ---------------
 
-* `upload_data.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/upload_data.ipynb>`_: A comprehensive guide on uploading data to Datamint.
-* `exploring_data_tutorial.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/exploring_data_tutorial.ipynb>`_: Learn how to explore and query resources in Datamint.
-* `project_scoped_splits_tutorial.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/project_scoped_splits_tutorial.ipynb>`_: Assign project-scoped train/val/test splits, inspect split records, and replay historical split snapshots in datasets.
-* `volume_dataset_tutorial.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/volume_dataset_tutorial.ipynb>`_: Tutorial on working with volume datasets in Datamint.
+* `01_upload_data.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/01_getting_started/01_upload_data.ipynb>`_: Upload images, DICOMs, and other resources to a Datamint project.
+* `02_explore_data.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/01_getting_started/02_explore_data.ipynb>`_: Query and explore resources already in a project.
 
 Annotations
 -----------
 
-* `upload_annotations.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/upload_annotations.ipynb>`_: Guide on how to import and manage simple annotations like image or frame categories.
-* `geometry_annotations.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/geometry_annotations.ipynb>`_: Covers integrating and uploading lines, bounding boxes, and other geometry annotations.
+* `01_upload_annotations.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/02_annotations/01_upload_annotations.ipynb>`_: Import and manage image-level and frame-level classification annotations.
+* `02_geometry_annotations.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/02_annotations/02_geometry_annotations.ipynb>`_: Upload bounding boxes, lines, and other geometry annotations.
 
-Machine Learning & Deployment
------------------------------
+Datasets
+--------
 
-* `mlflow_manual_logging.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/mlflow_manual_logging.ipynb>`_: Explains how to log models and experiments manually to MLflow via Datamint.
-* `deploy_model_demo.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/deploy_model_demo.ipynb>`_: Basic demonstration on deploying a Datamint model.
-* `external_model_deployment_tutorial.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/external_model_deployment_tutorial.ipynb>`_: Tutorial for adapting and deploying an externally-trained model in Datamint.
+* `01_project_scoped_splits.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/03_datasets/01_project_scoped_splits.ipynb>`_: Assign project-scoped train/val/test splits, inspect split records, and replay historical snapshots.
+* `02_patient_wise_splits.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/03_datasets/02_patient_wise_splits.ipynb>`_: Split datasets by patient to avoid data leakage between train and test sets.
+* `03_build_dataset.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/03_datasets/03_build_dataset.ipynb>`_: Build and configure a PyTorch dataset from a Datamint project.
+* `04_volume_dataset.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/03_datasets/04_volume_dataset.ipynb>`_: Work with 3D volume datasets (NIfTI, DICOM series).
 
-Use Cases & End-to-End Examples
--------------------------------
+Experiment Tracking
+-------------------
 
-These notebooks provide complete, end-to-end workflows located in the `use_cases directory <https://github.com/SonanceAI/datamint-python-api/tree/main/notebooks/use_cases>`_:
+* `01_mlflow_manual_logging.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/04_experiment_tracking/01_mlflow_manual_logging.ipynb>`_: Log models and experiments manually to MLflow via Datamint.
 
-* `fracatlas_classification.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/use_cases/fracatlas_classification.ipynb>`_: End-to-end classification pipeline for the FracAtlas dataset.
-* `segmentation_2d_trainer_BUSI_tutorial.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/use_cases/segmentation_2d_trainer_BUSI_tutorial.ipynb>`_: Train a 2D segmentation model on the BUSI dataset with ``UNetPPTrainer`` and see how to plug a custom external segmentation model,.
+Deployment
+----------
+
+* `01_deploy_registered_model.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/05_deployment/01_deploy_registered_model.ipynb>`_: Deploy a model registered in MLflow as a managed Datamint endpoint.
+* `02_deploy_external_model.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/05_deployment/02_deploy_external_model.ipynb>`_: Adapt and deploy an externally-trained model in Datamint.
+* `03_validate_model.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/05_deployment/03_validate_model.ipynb>`_: Validate a model before promoting it to production.
+
+End-to-End Examples
+-------------------
+
+Complete workflows from data upload to deployment.
+
+**Slice-based (2D)**
+
+* `01_fracatlas_classification.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/06_end_to_end/slice_based/01_fracatlas_classification.ipynb>`_: End-to-end classification pipeline on the FracAtlas dataset.
+* `02_busi_segmentation.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/06_end_to_end/slice_based/02_busi_segmentation.ipynb>`_: Train a 2D segmentation model on the BUSI dataset with ``UNetPPTrainer``, including custom model integration.
+* `03_bccd_detection.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/06_end_to_end/slice_based/03_bccd_detection.ipynb>`_: Object detection pipeline on the BCCD blood cell dataset.
+
+**Full 3D**
+
+* `01_synapse_unetrpp.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/06_end_to_end/full_3d/01_synapse_unetrpp.ipynb>`_: Volumetric segmentation on the Synapse dataset using UNETR++.
+* `02_synapse_nnunet.ipynb <https://github.com/SonanceAI/datamint-python-api/blob/main/notebooks/06_end_to_end/full_3d/02_synapse_nnunet.ipynb>`_: Volumetric segmentation on the Synapse dataset using nnUNet.