📝 Update dvc section

Author: veit

.pre-commit-config.yaml

@@ -18,6 +18,7 @@ repos:
       types: [file]
       files: \.(yml|yaml|cff)$
     - id: check-added-large-files
+      args: ['--maxkb=2048']
     - id: check-json
       types: [file]  # override `types: [json]`
       files: \.(json|ipynb)$

docs/_static/images/HEAD_eval_plots_images_importance.png

@@ -5,12 +5,17 @@
 Pipelines anzeigen
 ==================
 
-Solche Datenpipelines lassen sich anzeigen oder als Abhängigkeitsgraph
-darstellen mit ``dvc dag``:
+DVC stellt eine Pipeline intern als gerichtete azyklische Graphen (engl.: :abbr:`DAG (directed acyclic graphs)` dar.
+
+.. seealso::
+   `DVC DAG <https://dvc.org/doc/user-guide/pipelines/running-pipelines#dag>`_
+
+Ihr könnt ``dvc dag`` verwenden, um Pipelines zu visualisieren oder zu
+exportieren:
 
   .. code-block:: console
 
-    $ dvc dag
+    $ uv run dvc dag
 
         +-------------------+
         | data/data.xml.dvc |
@@ -40,12 +45,6 @@ darstellen mit ``dvc dag``:
             | evaluate |
             +----------+
 
-    data/data.xml.dvc
-    prepare.dvc
-    featurize.dvc
-    train.dvc
-    evaluate.dvc
-
 * Mit ``dvc dag --dot`` kann auch eine ``.dot``-Datei für `Graphviz
   <https://www.graphviz.org>`_ generiert werden:
 
@@ -63,3 +62,37 @@ darstellen mit ``dvc dag``:
         "featurize" -> "evaluate";
         "train" -> "evaluate";
     }
+
+Mit ``dvc status`` könnt ihr euch anzeigen lassen, ob die Stufen oder lokale und
+entfernte Speicher geändert wurden:
+
+.. code-block:: console
+
+   $ uv run dvc status
+   evaluate:
+       changed deps:
+           modified:           src/dvc_example/evaluate.py
+       changed outs:
+           modified:           eval
+
+.. seealso::
+   `dvc status <https://man.dvc.org/status>`_
+
+In :doc:`CI-Jobs <../git/advanced/gitlab/ci-cd/index>` soll üblicherweise
+überprüft werden, ob die Pipeline auf dem neuesten Stand ist, ohne etwas
+abzurufen oder auszuführen. Mit ``dvc repro --dry`` erfahrt ihr, welche
+Pipeline-Stufen ausgeführt werden müssten. Wenn jedoch Daten fehlen, schlägt der
+Befehl fehl. Wenn fehlende Daten ignoriert werden sollen, könnt ihr ``dvc repro
+--dry --allow-missing`` verwenden.
+
+.. code-block:: console
+
+   $ uv run dvc repro --allow-missing --dry
+   'data/data.xml.dvc' didn't change, skipping
+   Stage 'prepare' didn't change, skipping
+   Stage 'featurize' didn't change, skipping
+   Stage 'train' didn't change, skipping
+   Stage 'evaluate' is cached - skipping run, checking out outputs
+   Running stage 'evaluate':
+   > uv run python src/dvc_example/evaluate.py model.pkl data/features
+   Use `dvc push` to send your updates to remote storage.

docs/_static/images/workspace_eval_plots_images_importance.png

@@ -0,0 +1,98 @@
+.. SPDX-FileCopyrightText: 2020 Veit Schiele
+..
+.. SPDX-License-Identifier: BSD-3-Clause
+
+Daten verwalten
+===============
+
+Daten und Verzeichnisse hinzufügen
+----------------------------------
+
+Mit DVC könnt ihr Dateien, ML-Modelle, Verzeichnisse und Zwischenergebnisse mit
+Git speichern und versionieren, ohne dass der Dateiinhalt in Git eingecheckt
+werden muss:
+
+.. code-block:: console
+
+    $ uv run dvc get https://github.com/iterative/dataset-registry \
+        get-started/data.xml -o data/data.xml
+    $ uv run dvc add data/data.xml
+
+Dies fügt die Datei :file:`data/data.xml` in :file:`data/.gitignore` hinzu und
+schreibt die Meta-Angaben in :file:`data/data.xml.dvc`.
+
+.. seealso::
+   `.dvc Files <https://dvc.org/doc/user-guide/project-structure/dvc-files>`_
+
+Um nun verschiedene Versionen eurer Projektdaten mit Git verwalten zu können,
+fügt ihr nur :file:`data/.gitignore` und :file:`data/data.xml.dvc` hinzu:
+
+.. code-block:: console
+
+    $ git add data/.gitignore data/data.xml.dvc
+    $ git commit -m ":monocle_face: Add data to dvc"
+
+.. seealso::
+   `External Dependencies and Outputs
+   <https://dvc.org/doc/user-guide/pipelines/external-dependencies-and-outputs>`_
+
+Daten speichern und abrufen
+---------------------------
+
+Die Daten können vom Arbeitsverzeichnis eures Git-Repository auf den entfernten
+Speicherplatz kopiert werden mit
+
+.. code-block:: console
+
+    $ uv run dvc push
+
+Falls ihr aktuellere Daten abrufen wollt, könnt ihr dies mit
+
+.. code-block:: console
+
+    $ uv run dvc pull
+
+Daten importieren und aktualisieren
+-----------------------------------
+
+Alternativ zu ``dvc get`` könnt ihr auch Daten und Modelle aus einem anderen
+Projekts mit ``dvc import`` importieren, :abbr:`z. B. (zum Beispiel)`:
+
+.. code-block:: console
+
+   $ uv run dvc import https://github.com/iterative/dataset-registry  get-started/data.xml -o data/data.xml
+   Importing 'get-started/data.xml (https://github.com/iterative/dataset-registry)' -> 'data/data.xml'
+
+Dies lädt die Datei aus der `dataset-registry
+<https://github.com/iterative/dataset-registry>`_ in unser
+:file:`data`-Verzeichnis, fügt sie :file:`.gitignore` hinzu und erstellt
+:file:`data.xml.dvc`.
+
+Mit ``dvc update`` könnt ihr diese Datenquellen aktualisieren, bevor ihr eine
+Pipeline reproduziert, die von diesen Datenquellen abhängt, :abbr:`z. B. (zum
+Beispiel)`:
+
+.. code-block:: console
+
+   $ uv run dvc update data/data.xml.dvc
+   'data/data.xml.dvc' didn't change, skipping
+
+.. seealso::
+   * `Discovering and accessing data
+     <https://dvc.org/doc/user-guide/data-management/discovering-and-accessing-data>`_
+   * `External Data
+     <https://dvc.org/doc/user-guide/data-management/importing-external-data>`_
+
+Daten löschen
+-------------
+
+Wenn ihr Dateien oder Verzeichnisse aus der Verwaltung von DVC entfernen
+möchtet, könnt ihr dies mit `dvc remove
+<https://dvc.org/doc/command-reference/remove>`_:
+
+.. code-block::
+
+   $ uv run dvc remove data/data.xml.dvc
+
+Anschließend könnt ihr ``dvc gc -w`` verwenden, um alle Dateien und ihre
+früheren Versionen aus dem Cache zu löschen.

docs/productive/dvc/dag.rst

@@ -0,0 +1,104 @@
+.. SPDX-FileCopyrightText: 2020 Veit Schiele
+..
+.. SPDX-License-Identifier: BSD-3-Clause
+
+Experimente
+===========
+
+Wenn ihr jetzt in der :file:`params.yaml`-Datei die Parameter ändert, könnt ihr
+euer aktuelles Arbeitsverzeichnis mit dem letzten Commit (``HEAD``) vergleichen:
+
+.. code-block:: console
+
+   $ uv run dvc params diff
+   Path         Param                   HEAD    workspace
+   params.yaml  featurize.max_features  100     200
+   params.yaml  featurize.ngrams        1       2
+
+.. code-block:: console
+
+   $ uv run dvc metrics diff
+   Path               Metric          HEAD     workspace    Change
+   eval/metrics.json  avg_prec.test   0.9014   0.925        0.0236
+   eval/metrics.json  avg_prec.train  0.95704  0.97437      0.01733
+   eval/metrics.json  roc_auc.test    0.93196  0.94602      0.01406
+   eval/metrics.json  roc_auc.train   0.97743  0.98667      0.00924
+
+.. code-block:: console
+
+   $ uv run dvc plots diff
+   file:///Users/veit/dvc-example/dvc_plots/index.html
+
+.. raw:: html
+   :file: plots-diff.html
+
+``dvc exp``
+-----------
+
+Mit `dvc exp <https://dvc.org/doc/command-reference/exp>`_ könnt ihr die
+Parameter auch in der Kommandozeile setzen, :abbr:`z. B. (zum Beispiel)`:
+
+.. code-block:: console
+
+   $ uv run dvc exp run \
+       --set-param 'featurize.max_features=200'
+
+Ihr könnt mit einem Aufruf auch mehrere Parameter ändern:
+
+.. code-block:: console
+
+   $ uv run dvc exp run \
+       -S 'featurize.max_features=200' \
+       -S 'featurize.ngrams=2'
+
+Mit ``--queue`` lassen sich auch mehrere Werte für einen Parameter angeben:
+
+.. code-block:: console
+
+   $ uv run dvc exp run --queue \
+       -S 'featurize.max_features=200,300,400' \
+       -S 'featurize.ngrams=2,3,4'
+   Queueing with overrides '{'params.yaml': ['featurize.max_features=200', 'featurize.ngrams=2']}'.
+   Queued experiment 'sober-name' for future execution.
+   Queueing with overrides '{'params.yaml': ['featurize.max_features=200', 'featurize.ngrams=3']}'.
+   Queued experiment 'erect-loir' for future execution.
+   Queueing with overrides '{'params.yaml': ['featurize.max_features=200', 'featurize.ngrams=4']}'.
+   Queued experiment 'tonic-hood' for future execution.
+   Queueing with overrides '{'params.yaml': ['featurize.max_features=300', 'featurize.ngrams=2']}'.
+    ...
+
+Um die Experimente besser identifizieren zu können, könnt ihr auch noch
+``--name`` angeben:
+
+.. code-block:: console
+
+   $ uv run dvc exp run --name 'feature-matrix' --queue \
+       -S 'featurize.max_features=200,300,400' \
+       -S 'featurize.ngrams=2,3,4'
+   Queueing with overrides '{'params.yaml': ['featurize.max_features=200', 'featurize.ngrams=2']}'.
+   Queued experiment 'feature-matrix-1' for future execution.
+   Queueing with overrides '{'params.yaml': ['featurize.max_features=200', 'featurize.ngrams=3']}'.
+   Queued experiment 'feature-matrix-2' for future execution.
+   ...
+
+Sobald ihr einige Experimente in die Queue gestellt habt, könnt ihr alle mit
+folgendem Befehl ausführen:
+
+.. code-block:: console
+
+   $ uv run dvc exp run --run-all
+
+Mit dem ``job``-Flag von ``dvc queue start`` könnt ihr auch mehrere Worker für
+die Experimente verwenden:
+
+.. code-block:: console
+
+   $ uv run dvc queue start --job 8
+   Started '8' new experiments task queue workers.
+
+.. seealso::
+   * `Get Started: Experimenting Using Pipelines
+     <https://dvc.org/doc/start/experiments/experiment-pipelines>`_
+   * `Running Experiments
+     <https://dvc.org/doc/user-guide/experiment-management/running-experiments#the-experiments-queue>`_
+   * `dvc queue <https://dvc.org/doc/command-reference/queue>`_

docs/productive/dvc/data.rst

@@ -2,8 +2,8 @@
 ..
 .. SPDX-License-Identifier: BSD-3-Clause
 
-Daten verwalten mit ``DVC``
-===========================
+Daten verwalten mit DVC
+=======================
 
 Für Datenanalysen und vor allem bei Machine Learning ist es äußerst wertvoll,
 verschiedene Versionen von Analysen, die mit verschiedenen Datensätzen und
@@ -18,29 +18,10 @@ entfernten Datenspeicher übertragen können. Hierdurch vereinfacht sich der Abr
 bestimmter Versionen von Daten um eine Analyse zu reproduzieren.
 
 DVC wurde entwickelt, um :abbr:`ML (Machine Learning)`-Modelle und Datensätze
-gemeinsam nutzen zu können und nachvollziehbar zu verwalten. Es arbeitet zwar
-mit verschiedenen Versionsverwaltungen zusammen, benötigt diese jedoch nicht. Im
-Gegensatz :abbr:`z.B. (zum Beispiel)` zu `DataLad
-<https://www.datalad.org/>`_/`git-annex <https://git-annex.branchable.com/>`_
-ist es auch nicht auf Git als Versionsverwaltung beschränkt, sondern kann
-:abbr:`z.B (zum Beispiel)` auch zusammen mit Mercurial verwendet werden, siehe
-`github.com/crobarcro/dvc/dvc/scm.py
-<https://github.com/crobarcro/dvc/blob/master/dvc/scm.py>`_. Zudem nutzt es
-ein eigenes System zum Speichern der Dateien mit Unterstützung :abbr:`u.a.
-(unter anderem)` für :abbr:`SSH (Secure Shell)` und :abbr:`HDFS (Hadoop
-Distributed File System)`.
-
-DataLad konzentriert sich hingegen mehr auf die Entdeckung und Verwendung von
-Datasets, die dann einfach mit Git verwaltet werden. DVC hingegen speichert
-jeden Schritt der Pipeline in einer separaten ``.dvc``-Datei, die dann durch
-Git verwaltet werden kann.
-
-Diese ``.dvc``-Dateien erlauben jedoch praktische Tools zur Manipulation und
-Visualisierung von DAGs, siehe :abbr:`z.B. (zum Beispiel)` die
-:doc:`Visualisierung der DAGs <pipeline>`.
-
-Schließlich lassen sich mit :ref:`dvc remote <dvc-remote>` auch externe
-Abhängigkeiten angeben.
+gemeinsam nutzen zu können und nachvollziehbar zu verwalten. Es nutzt ein
+eigenes System zum Speichern der Dateien mit Unterstützung :abbr:`u.a. (unter
+anderem)` für :abbr:`SSH (Secure Shell)` und :abbr:`HDFS (Hadoop Distributed
+File System)`.
 
 .. tip::
    `cusy Seminar: Code und Daten versioniert und reproduzierbar speichern
@@ -51,6 +32,36 @@ Abhängigkeiten angeben.
    * `Documentation <https://dvc.org/doc>`_
    * `Git Repository <https://github.com/iterative/dvc>`_
 
+Vergleich mit verwandten Technologien
+-------------------------------------
+
+git-annex
+~~~~~~~~~
+
+`git-annex <https://git-annex.branchable.com/>`_ konzentriert sich mehr auf die
+Entdeckung und Verwendung von Datensätzen, die dann einfach mit Git verwaltet
+werden. DVC hingegen speichert die Daten, die bei jeden Schritt der Pipeline
+erzeugt werden, in :file:`.dvc`-Dateien, die dann durch Git verwaltet werden
+kann. DVC stellt zudem praktische Tools zur Manipulation und Visualisierung von Daten-Pipelines bereit, siehe :abbr:`z.B. (zum Beispiel)` :doc:`dvc status
+<dag>`. Schließlich lassen sich mit :ref:`dvc remote <dvc-remote>` auch externe
+Abhängigkeiten angeben.
+
+Workflow-Management-Systeme wie Airflow und Luigi
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DVC konzentriert sich auf Data-Science-Workflows und Modellierung; daher sind
+DVC-Pipelines sehr viel leichtgewichtiger, einfacher zu erstellen und zu ändern
+als bei `Airflow <https://airflow.incubator.apache.org>`_ und `Luigi
+<https://luigi.readthedocs.io/en/stable/>`_. Allerdings fehlen DVC erweiterte
+Funktionen wie die Überwachung der Ausführung, Optimierung und Fehlertoleranz.
+Auch ist DVC ein reines Befehlszeilen-Tool ohne grafische Benutzeroberfläche und
+es führt auch keine Daemons oder Server aus. `CML <https://cml.dev>`_ versucht
+hier, einige der Lücken leichtgewichtig mit GitHub, GitLab oder Bitbucket zu
+schließen. DVC und CML eignen sich jedoch gut für iterative
+Machine-Learning-Prozesse; und wenn mit den beiden ein gutes Modell gefunden
+wurde, steht euch immer noch frei, die Pipeline in Luigi oder Airflow zu
+integrieren.
+
 Installation
 ------------
 
@@ -83,9 +94,11 @@ Alternativ kann DVC auch über andere Paketmanager installiert werden:
    :hidden:
 
    init
+   data
    pipeline
    params
    metrics
+   experiments
    dag
    reproduce
    integration