Added time series generation example

Author: famura

Diff for: .gitignore

@@ -128,5 +128,5 @@ dmypy.json
 # CI/ CD
 exported/
 
-# Trained models
-examples/model.pt
+# Results from the example scripts
+examples/*.pt

Diff for: README.md

@@ -19,6 +19,21 @@ It's main characteristic is the lateral in-/exhibition of neurons though their a
 Due to its simplicity and expressiveness, Amari’s work was highly influential and led to several follow-up papers such
 as [2-6] to only name a few.
 
+## Support
+
+If you use code or ideas from this repository for your projects or research, **please cite it**.
+
+```
+@misc{Muratore_neuralfields,
+  author = {Fabio Muratore},
+  title = {neuralfields - A type of potential-based recurrent neural networks implemented with PyTorch},
+  year = {2023},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  howpublished = {\url{https://github.com/famura/neuralfields}}
+}
+```
+
 ## Features
 
 * There are two variants of the neural fields implemented in this repository: one called `NeuralField` that matches
@@ -36,20 +51,11 @@ as [2-6] to only name a few.
   sim-to-real transfer. However, the goal of this repository is to make the implementation **as general as possible**,
   such that it could for example be used as generative model.
 
-## Support
-
-If you use code or ideas from this repository for your projects or research, **please cite it**.
+### Time series learning example
+![](examples/time_series_learning.png) ![](exported/examples/time_series_learning.png)
 
-```
-@misc{Muratore_neuralfields,
-  author = {Fabio Muratore},
-  title = {neuralfields - A type of potential-based recurrent neural networks implemented with PyTorch},
-  year = {2023},
-  publisher = {GitHub},
-  journal = {GitHub repository},
-  howpublished = {\url{https://github.com/famura/neuralfields}}
-}
-```
+### Time series generation example
+![](examples/time_series_generation.png) ![](exported/examples/time_series_generation.png)
 
 ## Getting Started
 

Diff for: examples/time_series_generation.png

@@ -1,3 +1,5 @@
+import warnings
+
 import matplotlib.pyplot as plt
 import seaborn
 import torch
@@ -11,9 +13,11 @@
     # Configure.
     torch.manual_seed(0)
     num_samples = 5
-    len_time_series = 50
-    random_inputs = True  # if False, the inputs will be zero for every sample (vary via the hidden state)
-    default_hidden = False  # if True, the hidden state will be initialized with zeroes by the net (vary via the inputs)
+    use_test_inputs = True  # if False, the inputs will be zero for every sample (vary via the hidden state)
+    default_hidden = True  # if True, the hidden state will be initialized with zeroes by the net (vary via the inputs)
+    if not use_test_inputs and default_hidden:
+        warnings.warn("All generated sequences will be the same. Please change the scripts configuration.")
+    len_time_series = 800 if use_test_inputs else 10
 
     # Load the model previously trained with the time_series_learning.py example script.
     try:
@@ -27,18 +31,22 @@
 
     # Use the model to generate several time series. This could either be done by providing inputs that are different
     # along the first dimension of the tensor, or by varying the initial hidden state.
-    inputs = torch.zeros(num_samples, len_time_series, model.input_size)
-    if random_inputs:
-        inputs[:, len_time_series // 2 :, :] = (
-            torch.linspace(0, 8, len_time_series // 2)  # start and end of the linspace are arbitrary
-            .view(1, -1, 1)
-            .repeat(num_samples, 1, model.input_size)
-        )
-        inputs[:, len_time_series // 2 :, :] += torch.randn(num_samples, len_time_series // 2, model.input_size)
+    if use_test_inputs:
+        try:
+            inputs = torch.load(EXAMPLES_DIR / "data_tst.pt").unsqueeze(0).repeat(num_samples, 1, 1)
+        except FileNotFoundError:
+            raise FileNotFoundError(
+                "There was no file called 'data_tst.pt' found in neuralfields' example directory. Most likely, you "
+                "need to run the 'time_series_learning.py' script first."
+            )
+        inputs = inputs[:, :len_time_series, :]
+        inputs[1:] += torch.randn(num_samples - 1, len_time_series, model.input_size) / 50
+    else:
+        inputs = torch.zeros(num_samples, len_time_series, model.input_size)
     if default_hidden:
         hidden = None
     else:
-        hidden = torch.randn(num_samples, model.hidden_size) * 5
+        hidden = torch.randn(num_samples, model.hidden_size) * 10
     with torch.no_grad():
         generated, _ = model(inputs, hidden)
 
@@ -47,4 +55,6 @@
     for idx_ts, gen_ts in enumerate(generated):
         plt.plot(gen_ts.numpy(), label=f"sample {idx_ts}")
     axs.legend(bbox_to_anchor=(0, 1.02, 1, 0.2), loc="lower left", mode="expand", borderaxespad=0, ncol=inputs.size(0))
+    axs.set_xlabel("months")
+    axs.set_ylabel("spot count")
     plt.show()

Diff for: examples/time_series_generation.py

@@ -39,6 +39,14 @@ def create_figure(dataset_name: str) -> plt.Figure:
     return fig
 
 
+def plot_results(fig: plt.Figure) -> None:
+    axs = fig.get_axes()
+    axs[0].plot(predictions_trn, label="predictions")
+    axs[1].plot(predictions_tst, label="predictions")
+    axs[0].legend(loc="upper right", ncol=2)
+    axs[1].legend(loc="upper right", ncol=2)
+
+
 def simple_training_loop(
     model: torch.nn.Module,
     packed_inputs: torch.Tensor,
@@ -79,8 +87,8 @@ def simple_training_loop(
     # Configure.
     torch.manual_seed(0)
     use_simplification = False  # switch between models
-    normalize_data = False  # scales the data to be in [-1, 1]
-    dataset_name = "mackey_glass"  # monthly_sunspots or mackey_glass
+    normalize_data = True  # scales the data to be in [-1, 1]
+    dataset_name = "monthly_sunspots"  # monthly_sunspots or mackey_glass
 
     # Get the data.
     data, data_trn, data_tst = load_and_split_data(dataset_name, normalize_data)
@@ -135,13 +143,11 @@ def simple_training_loop(
         predictions_tst, _ = model(data_tst[:-1].unsqueeze(0), hidden=None)
         predictions_tst = predictions_tst.squeeze(0).detach().numpy()
 
-    # Safe the model.
+    # Safe the model and the associated data.
     torch.save(model, EXAMPLES_DIR / "model.pt")
+    torch.save(data_trn, EXAMPLES_DIR / "data_trn.pt")
+    torch.save(data_tst, EXAMPLES_DIR / "data_tst.pt")
 
     # Plot the results.
-    axs = fig.get_axes()
-    axs[0].plot(predictions_trn, label="predictions")
-    axs[1].plot(predictions_tst, label="predictions")
-    axs[0].legend(loc="upper right", ncol=2)
-    axs[1].legend(loc="upper right", ncol=2)
+    plot_results(fig)
     plt.show()

Diff for: examples/time_series_learning.png

@@ -270,6 +270,9 @@ sequence = [
   { cmd = "genbadge tests --input-file pytest.xml --output-file docs/exported/tests/badge.svg" },
   { cmd = "pip-licenses --format markdown --with-authors --with-urls --with-description --output-file docs/exported/third_party_licenses.md" },
   { shell = "poe --help > docs/exported/poe_options.txt" },
+  { shell = "mkdir -p docs/exported/examples" },
+  { shell = "cp examples/time_series_learning.png docs/exported/examples/time_series_learning.png" },
+  { shell = "cp examples/time_series_generation.png docs/exported/examples/time_series_generation.png" },
 ]
 help = "Get the git change log to. Next, create the badges. Finally, fetch all thrid party licenses and add them to the documentation."