Skip to content

Commit 6e1d72d

Browse files
Adrian WälchliBorda
Adrian Wälchli
and
Borda
authored
Improved docs for Loggers (Lightning-AI#1484)
* improve __init__ * improve logger base * improve comet logger docs * improved docs for mlflow * improved nepune logger docs * fix matplotlib import issue * improve tensorboard docs * improve docs for test tube * improved trains logger docs * improve wandb logger docs * improved docs in experiment_logging.rst * added MLflow to the list of loggers * fix too long lines * fix trains doctest * fix neptune doctest * fix mlflow doctest * Apply suggestions from code review Co-Authored-By: Jirka Borovec <Borda@users.noreply.github.com> * Apply suggestions from code review * fix whitespace * try bypass mode for neptune (fix doctest api key error) * try "test" as api key * Revert "try "test" as api key" This reverts commit fd77db2. * try test as api key * update neptune docs * bump neptune minimal version * revert unnecessary bypass code * test if CI runs doctests in .rst files * Revert "test if CI runs doctests in .rst files" This reverts commit a45aeb4. * add doctest directive * neptune demo links * added tutorial link for W&B * fix line too long * fix merge error * fix merge error * add instructions how to install loggers * add instructions how to install the loggers * hide _abc_impl property from docs * review Borda, 4 spaces * indentation in example sections * blank Co-authored-by: Jirka Borovec <Borda@users.noreply.github.com>
1 parent 3c549e8 commit 6e1d72d

File tree

12 files changed

+776
-638
lines changed

12 files changed

+776
-638
lines changed

‎docs/source/conf.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -385,7 +385,7 @@ def find_source():
385385
'methods': None,
386386
# 'attributes': None,
387387
'special-members': '__call__',
388-
# 'exclude-members': '__weakref__',
388+
'exclude-members': '_abc_impl',
389389
'show-inheritance': True,
390390
'private-members': True,
391391
'noindex': True,

‎docs/source/experiment_logging.rst

+189-119
Original file line numberDiff line numberDiff line change
@@ -1,201 +1,271 @@
11
Experiment Logging
2-
===================
2+
==================
33

44
Comet.ml
55
^^^^^^^^
66

77
`Comet.ml <https://www.comet.ml/site/>`_ is a third-party logger.
8-
To use CometLogger as your logger do the following.
8+
To use :class:`~pytorch_lightning.loggers.CometLogger` as your logger do the following.
9+
First, install the package:
10+
11+
.. code-block:: bash
12+
13+
pip install comet-ml
14+
15+
Then configure the logger and pass it to the :class:`~pytorch_lightning.trainer.trainer.Trainer`:
16+
17+
.. doctest::
18+
19+
>>> import os
20+
>>> from pytorch_lightning import Trainer
21+
>>> from pytorch_lightning.loggers import CometLogger
22+
>>> comet_logger = CometLogger(
23+
... api_key=os.environ.get('COMET_API_KEY'),
24+
... workspace=os.environ.get('COMET_WORKSPACE'), # Optional
25+
... save_dir='.', # Optional
26+
... project_name='default_project', # Optional
27+
... rest_api_key=os.environ.get('COMET_REST_API_KEY'), # Optional
28+
... experiment_name='default' # Optional
29+
... )
30+
>>> trainer = Trainer(logger=comet_logger)
31+
32+
The :class:`~pytorch_lightning.loggers.CometLogger` is available anywhere except ``__init__`` in your
33+
:class:`~pytorch_lightning.core.lightning.LightningModule`.
34+
35+
.. doctest::
36+
37+
>>> from pytorch_lightning import LightningModule
38+
>>> class MyModule(LightningModule):
39+
... def any_lightning_module_function_or_hook(self):
40+
... some_img = fake_image()
41+
... self.logger.experiment.add_image('generated_images', some_img, 0)
942

1043
.. seealso::
1144
:class:`~pytorch_lightning.loggers.CometLogger` docs.
1245

13-
.. code-block:: python
46+
MLflow
47+
^^^^^^
1448

15-
from pytorch_lightning.loggers import CometLogger
49+
`MLflow <https://mlflow.org/>`_ is a third-party logger.
50+
To use :class:`~pytorch_lightning.loggers.MLFlowLogger` as your logger do the following.
51+
First, install the package:
1652

17-
comet_logger = CometLogger(
18-
api_key=os.environ["COMET_KEY"],
19-
workspace=os.environ["COMET_WORKSPACE"], # Optional
20-
project_name="default_project", # Optional
21-
rest_api_key=os.environ["COMET_REST_KEY"], # Optional
22-
experiment_name="default" # Optional
23-
)
24-
trainer = Trainer(logger=comet_logger)
53+
.. code-block:: bash
2554
26-
The CometLogger is available anywhere except ``__init__`` in your LightningModule
55+
pip install mlflow
2756
28-
.. code-block:: python
57+
Then configure the logger and pass it to the :class:`~pytorch_lightning.trainer.trainer.Trainer`:
2958

30-
class MyModule(pl.LightningModule):
59+
.. doctest::
3160

32-
def any_lightning_module_function_or_hook(self, ...):
33-
some_img = fake_image()
34-
self.logger.experiment.add_image('generated_images', some_img, 0)
61+
>>> from pytorch_lightning import Trainer
62+
>>> from pytorch_lightning.loggers import MLFlowLogger
63+
>>> mlf_logger = MLFlowLogger(
64+
... experiment_name="default",
65+
... tracking_uri="file:/."
66+
... )
67+
>>> trainer = Trainer(logger=mlf_logger)
68+
69+
.. seealso::
70+
:class:`~pytorch_lightning.loggers.MLFlowLogger` docs.
3571

3672
Neptune.ai
3773
^^^^^^^^^^
3874

3975
`Neptune.ai <https://neptune.ai/>`_ is a third-party logger.
40-
To use Neptune.ai as your logger do the following.
76+
To use :class:`~pytorch_lightning.loggers.NeptuneLogger` as your logger do the following.
77+
First, install the package:
4178

42-
.. seealso::
43-
:class:`~pytorch_lightning.loggers.NeptuneLogger` docs.
79+
.. code-block:: bash
4480
45-
.. code-block:: python
81+
pip install neptune-client
4682
47-
from pytorch_lightning.loggers import NeptuneLogger
83+
Then configure the logger and pass it to the :class:`~pytorch_lightning.trainer.trainer.Trainer`:
4884

49-
neptune_logger = NeptuneLogger(
50-
project_name="USER_NAME/PROJECT_NAME",
51-
experiment_name="default", # Optional,
52-
params={"max_epochs": 10}, # Optional,
53-
tags=["pytorch-lightning","mlp"] # Optional,
54-
)
55-
trainer = Trainer(logger=neptune_logger)
85+
.. doctest::
5686

57-
The Neptune.ai is available anywhere except ``__init__`` in your LightningModule
87+
>>> from pytorch_lightning import Trainer
88+
>>> from pytorch_lightning.loggers import NeptuneLogger
89+
>>> neptune_logger = NeptuneLogger(
90+
... api_key='ANONYMOUS', # replace with your own
91+
... project_name='shared/pytorch-lightning-integration',
92+
... experiment_name='default', # Optional,
93+
... params={'max_epochs': 10}, # Optional,
94+
... tags=['pytorch-lightning', 'mlp'], # Optional,
95+
... )
96+
>>> trainer = Trainer(logger=neptune_logger)
5897

59-
.. code-block:: python
98+
The :class:`~pytorch_lightning.loggers.NeptuneLogger` is available anywhere except ``__init__`` in your
99+
:class:`~pytorch_lightning.core.lightning.LightningModule`.
60100

61-
class MyModule(pl.LightningModule):
101+
.. doctest::
62102

63-
def any_lightning_module_function_or_hook(self, ...):
64-
some_img = fake_image()
65-
self.logger.experiment.add_image('generated_images', some_img, 0)
103+
>>> from pytorch_lightning import LightningModule
104+
>>> class MyModule(LightningModule):
105+
... def any_lightning_module_function_or_hook(self):
106+
... some_img = fake_image()
107+
... self.logger.experiment.add_image('generated_images', some_img, 0)
108+
109+
.. seealso::
110+
:class:`~pytorch_lightning.loggers.NeptuneLogger` docs.
66111

67112
allegro.ai TRAINS
68113
^^^^^^^^^^^^^^^^^
69114

70115
`allegro.ai <https://github.com/allegroai/trains/>`_ is a third-party logger.
71-
To use TRAINS as your logger do the following.
72-
73-
.. seealso::
74-
:class:`~pytorch_lightning.loggers.TrainsLogger` docs.
75-
76-
.. code-block:: python
116+
To use :class:`~pytorch_lightning.loggers.TrainsLogger` as your logger do the following.
117+
First, install the package:
77118

78-
from pytorch_lightning.loggers import TrainsLogger
119+
.. code-block:: bash
79120
80-
trains_logger = TrainsLogger(
81-
project_name="examples",
82-
task_name="pytorch lightning test"
83-
)
84-
trainer = Trainer(logger=trains_logger)
121+
pip install trains
85122
86-
The TrainsLogger is available anywhere in your LightningModule
123+
Then configure the logger and pass it to the :class:`~pytorch_lightning.trainer.trainer.Trainer`:
87124

88-
.. code-block:: python
125+
.. doctest::
89126

90-
class MyModule(pl.LightningModule):
127+
>>> from pytorch_lightning import Trainer
128+
>>> from pytorch_lightning.loggers import TrainsLogger
129+
>>> trains_logger = TrainsLogger(
130+
... project_name='examples',
131+
... task_name='pytorch lightning test',
132+
... ) # doctest: +ELLIPSIS
133+
TRAINS Task: ...
134+
TRAINS results page: ...
135+
>>> trainer = Trainer(logger=trains_logger)
91136

92-
def __init__(self, ...):
93-
some_img = fake_image()
94-
self.logger.log_image('debug', 'generated_image_0', some_img, 0)
137+
The :class:`~pytorch_lightning.loggers.TrainsLogger` is available anywhere in your
138+
:class:`~pytorch_lightning.core.lightning.LightningModule`.
95139

96-
Tensorboard
97-
^^^^^^^^^^^
140+
.. doctest::
98141

99-
To use `Tensorboard <https://pytorch.org/docs/stable/tensorboard.html>`_ as your logger do the following.
142+
>>> from pytorch_lightning import LightningModule
143+
>>> class MyModule(LightningModule):
144+
... def __init__(self):
145+
... some_img = fake_image()
146+
... self.logger.experiment.log_image('debug', 'generated_image_0', some_img, 0)
100147

101148
.. seealso::
102-
:class:`~pytorch_lightning.loggers.TensorBoardLogger` docs.
149+
:class:`~pytorch_lightning.loggers.TrainsLogger` docs.
103150

104-
.. code-block:: python
151+
Tensorboard
152+
^^^^^^^^^^^
105153

106-
from pytorch_lightning.loggers import TensorBoardLogger
154+
To use `TensorBoard <https://pytorch.org/docs/stable/tensorboard.html>`_ as your logger do the following.
107155

108-
logger = TensorBoardLogger("tb_logs", name="my_model")
109-
trainer = Trainer(logger=logger)
156+
.. doctest::
110157

111-
The TensorBoardLogger is available anywhere except ``__init__`` in your LightningModule
158+
>>> from pytorch_lightning import Trainer
159+
>>> from pytorch_lightning.loggers import TensorBoardLogger
160+
>>> logger = TensorBoardLogger('tb_logs', name='my_model')
161+
>>> trainer = Trainer(logger=logger)
112162

113-
.. code-block:: python
163+
The :class:`~pytorch_lightning.loggers.TensorBoardLogger` is available anywhere except ``__init__`` in your
164+
:class:`~pytorch_lightning.core.lightning.LightningModule`.
114165

115-
class MyModule(pl.LightningModule):
166+
.. doctest::
116167

117-
def any_lightning_module_function_or_hook(self, ...):
118-
some_img = fake_image()
119-
self.logger.experiment.add_image('generated_images', some_img, 0)
168+
>>> from pytorch_lightning import LightningModule
169+
>>> class MyModule(LightningModule):
170+
... def any_lightning_module_function_or_hook(self):
171+
... some_img = fake_image()
172+
... self.logger.experiment.add_image('generated_images', some_img, 0)
120173

174+
.. seealso::
175+
:class:`~pytorch_lightning.loggers.TensorBoardLogger` docs.
121176

122177
Test Tube
123178
^^^^^^^^^
124179

125-
`Test Tube <https://github.com/williamFalcon/test-tube>`_ is a tensorboard logger but with nicer file structure.
126-
To use TestTube as your logger do the following.
180+
`Test Tube <https://github.com/williamFalcon/test-tube>`_ is a
181+
`TensorBoard <https://pytorch.org/docs/stable/tensorboard.html>`_ logger but with nicer file structure.
182+
To use :class:`~pytorch_lightning.loggers.TestTubeLogger` as your logger do the following.
183+
First, install the package:
127184

128-
.. seealso::
129-
:class:`~pytorch_lightning.loggers.TestTubeLogger` docs.
185+
.. code-block:: bash
130186
131-
.. code-block:: python
187+
pip install test_tube
132188
133-
from pytorch_lightning.loggers import TestTubeLogger
189+
Then configure the logger and pass it to the :class:`~pytorch_lightning.trainer.trainer.Trainer`:
134190

135-
logger = TestTubeLogger("tb_logs", name="my_model")
136-
trainer = Trainer(logger=logger)
191+
.. doctest::
137192

138-
The TestTubeLogger is available anywhere except ``__init__`` in your LightningModule
193+
>>> from pytorch_lightning.loggers import TestTubeLogger
194+
>>> logger = TestTubeLogger('tb_logs', name='my_model')
195+
>>> trainer = Trainer(logger=logger)
139196

140-
.. code-block:: python
197+
The :class:`~pytorch_lightning.loggers.TestTubeLogger` is available anywhere except ``__init__`` in your
198+
:class:`~pytorch_lightning.core.lightning.LightningModule`.
141199

142-
class MyModule(pl.LightningModule):
200+
.. doctest::
143201

144-
def any_lightning_module_function_or_hook(self, ...):
145-
some_img = fake_image()
146-
self.logger.experiment.add_image('generated_images', some_img, 0)
202+
>>> from pytorch_lightning import LightningModule
203+
>>> class MyModule(LightningModule):
204+
... def any_lightning_module_function_or_hook(self):
205+
... some_img = fake_image()
206+
... self.logger.experiment.add_image('generated_images', some_img, 0)
147207

148-
Wandb
149-
^^^^^
208+
.. seealso::
209+
:class:`~pytorch_lightning.loggers.TestTubeLogger` docs.
150210

151-
`Wandb <https://www.wandb.com/>`_ is a third-party logger.
152-
To use Wandb as your logger do the following.
211+
Weights and Biases
212+
^^^^^^^^^^^^^^^^^^
153213

154-
.. seealso::
155-
:class:`~pytorch_lightning.loggers.WandbLogger` docs.
214+
`Weights and Biases <https://www.wandb.com/>`_ is a third-party logger.
215+
To use :class:`~pytorch_lightning.loggers.WandbLogger` as your logger do the following.
216+
First, install the package:
156217

157-
.. code-block:: python
218+
.. code-block:: bash
158219
159-
from pytorch_lightning.loggers import WandbLogger
220+
pip install wandb
160221
161-
wandb_logger = WandbLogger()
162-
trainer = Trainer(logger=wandb_logger)
222+
Then configure the logger and pass it to the :class:`~pytorch_lightning.trainer.trainer.Trainer`:
163223

164-
The Wandb logger is available anywhere except ``__init__`` in your LightningModule
224+
.. doctest::
165225

166-
.. code-block:: python
226+
>>> from pytorch_lightning.loggers import WandbLogger
227+
>>> wandb_logger = WandbLogger()
228+
>>> trainer = Trainer(logger=wandb_logger)
167229

168-
class MyModule(pl.LightningModule):
230+
The :class:`~pytorch_lightning.loggers.WandbLogger` is available anywhere except ``__init__`` in your
231+
:class:`~pytorch_lightning.core.lightning.LightningModule`.
169232

170-
def any_lightning_module_function_or_hook(self, ...):
171-
some_img = fake_image()
172-
self.logger.experiment.add_image('generated_images', some_img, 0)
233+
.. doctest::
173234

235+
>>> from pytorch_lightning import LightningModule
236+
>>> class MyModule(LightningModule):
237+
... def any_lightning_module_function_or_hook(self):
238+
... some_img = fake_image()
239+
... self.logger.experiment.log({
240+
... "generated_images": [wandb.Image(some_img, caption="...")]
241+
... })
242+
243+
.. seealso::
244+
:class:`~pytorch_lightning.loggers.WandbLogger` docs.
174245

175246
Multiple Loggers
176247
^^^^^^^^^^^^^^^^
177248

178-
PyTorch-Lightning supports use of multiple loggers, just pass a list to the `Trainer`.
249+
Lightning supports the use of multiple loggers, just pass a list to the
250+
:class:`~pytorch_lightning.trainer.trainer.Trainer`.
179251

180-
.. code-block:: python
252+
.. doctest::
181253

182-
from pytorch_lightning.loggers import TensorBoardLogger, TestTubeLogger
183-
184-
logger1 = TensorBoardLogger("tb_logs", name="my_model")
185-
logger2 = TestTubeLogger("tt_logs", name="my_model")
186-
trainer = Trainer(logger=[logger1, logger2])
254+
>>> from pytorch_lightning.loggers import TensorBoardLogger, TestTubeLogger
255+
>>> logger1 = TensorBoardLogger('tb_logs', name='my_model')
256+
>>> logger2 = TestTubeLogger('tb_logs', name='my_model')
257+
>>> trainer = Trainer(logger=[logger1, logger2])
187258

188-
The loggers are available as a list anywhere except ``__init__`` in your LightningModule
189-
190-
.. code-block:: python
191-
192-
class MyModule(pl.LightningModule):
193-
194-
def any_lightning_module_function_or_hook(self, ...):
195-
some_img = fake_image()
196-
197-
# Option 1
198-
self.logger.experiment[0].add_image('generated_images', some_img, 0)
199-
200-
# Option 2
201-
self.logger[0].experiment.add_image('generated_images', some_img, 0)
259+
The loggers are available as a list anywhere except ``__init__`` in your
260+
:class:`~pytorch_lightning.core.lightning.LightningModule`.
261+
262+
.. doctest::
263+
264+
>>> from pytorch_lightning import LightningModule
265+
>>> class MyModule(LightningModule):
266+
... def any_lightning_module_function_or_hook(self):
267+
... some_img = fake_image()
268+
... # Option 1
269+
... self.logger.experiment[0].add_image('generated_images', some_img, 0)
270+
... # Option 2
271+
... self.logger[0].experiment.add_image('generated_images', some_img, 0)

0 commit comments

Comments
 (0)