Migrate examples to notebooks

.github/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing Guidelines
+
+Thanks for your interest in contributing an example to k-wave-python!
+
+##  Issues
+
+### Create a new issue
+
+If you would like to contribute to this project, search to see if a related issue already exists. If a related issue doesn't exist, you can open a new issue using a relevant issue form.
+
+### Solve an open issue
+
+Have a look through our existing issues to find one that interests you.
+You can narrow down the search using labels as filters.
+If you find an issue to work on, you are welcome to open a PR with a fix.
+
+## Make changes
+
+Fork k-wave-python and make changes you would like to contribute to your fork.
+
+## Open a Pull-Request
+
+* Complete the "Ready for review" template so that we can review your PR. This template helps reviewers understand your changes and the purpose of your pull request.
+
+* [Link PR to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) if you are solving one.
+
+* Don't forget to click the checkbox to [allow maintainer edits](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so you PR can be updated before a merge.
+
+

.github/workflows/test_example.yml

@@ -20,7 +20,7 @@ jobs:
           pip install -e '.[example]'
       - name: Run example script
         run: |
-          python3 examples/bmode_reconstruction_example.py
+          python3 examples/us_bmode_linear_transducer/us_bmode_linear_transducer.py
       - name: Upload example results
         uses: actions/upload-artifact@v3
         with:

.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+- repo: https://github.com/srstevenson/nb-clean.git
+  rev: 3.2.0
+  hooks:
+  - id: nb-clean
+    name: nb-clean
+    entry: nb-clean clean
+    language: python
+    types_or: [jupyter]
+    minimum_pre_commit_version: 2.9.2
+# - repo: https://github.com/pre-commit/pre-commit-hooks
+#   rev: v4.5.0  # Use the ref you want to point at
+#   hooks:
+#   -   id: trailing-whitespace
+# - repo: https://github.com/nbQA-dev/nbQA
+#   rev: 1.7.1
+#   hooks:
+#   - id: nbqa-ruff
+#     name: nbqa-ruff
+#     entry: nbqa ruff
+#     language: python
+#     types_or: [jupyter]
+#     minimum_pre_commit_version: 2.9.2

docs/README.md

@@ -33,7 +33,7 @@ git clone https://github.com/waltsims/k-wave-python
 cd k-wave-python
 git checkout v0.3.0
 pip install '.[example]' 
-python3 examples/bmode_reconstruction_example.py
+python3 examples/us_bmode_linear_transducer/us_bmode_linear_transducer.py
 ```
 
 This example file steps through the process of:

examples/README.md

@@ -0,0 +1,29 @@
+# Examples
+
+Many examples from k-wave-python are Python mirrors of the [large collection of great examples](http://www.k-wave.org/documentation/k-wave_examples.php) from the original k-wave project.
+All examples are included as python files or notebooks in a subdirectory of the example directory.
+Every example has a short readme.md file which briefly describes the purpose of the example.
+
+## List of Examples
+
+- [Array as a sensor](at_array_as_sensor/) ([original example](http://www.k-wave.org/documentation/example_at_array_as_sensor.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/migrate-examples-to-notebooks/examples/at_array_as_sensor/at_array_as_sensor.ipynb))
+- [Array as a source](at_array_as_source/) ([original example](http://www.k-wave.org/documentation/example_at_array_as_source.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/migrate-examples-to-notebooks/examples/at_array_as_source/at_array_as_source.ipynb))
+- [Linear array transducer](at_linear_array_transducer/)
+([original example](http://www.k-wave.org/documentation/example_at_linear_array_transducer.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/migrate-examples-to-notebooks/examples/at_linear_array_transducer/at_linear_array_transducer.ipynb))
+- [Photoacoustic Waveforms](ivp_photoacoustic_waveforms/) ([original example](http://www.k-wave.org/documentation/example_ivp_photoacoustic_waveforms.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/migrate-examples-to-notebooks/examples/ivp_photoacoustic_waveforms/ivp_photoacoustic_waveforms.ipynb))
+- [Linear transducer B-mode](us_bmode_linear_transducer/) ([original example](http://www.k-wave.org/documentation/example_us_bmode_linear_transducer.php), [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/waltsims/k-wave-python/blob/migrate-examples-to-notebooks/examples/us_bmode_linear_transducer/us_bmode_linear_transducer.ipynb))    
+
+## Contributing new examples
+
+When adding a new example notebook, follow these steps:
+
+1. Search the open issues to see if a related example has already been requested. If not add an example issue and assign yourself to the issue.
+3. Fork and clone the repository and create a branch for your new example.
+2. Create an example sub-directory using the name from the hyperlink of the origional k-wave example if it exists (e.g. for http://www.k-wave.org/documentation/example_ivp_loading_external_image.php name the directory "ivp_loading_external_image).
+3. Add your example notebook or files to your example directory.
+4. Add a README.md file to your example directory briefly describing the concept or principle the example is meant to display and linking to the origonal k-wave example page if it exists.
+5. Include a link in the readme.md in the examples directory to a colab notebook for your example.
+6. Add a your example to the list on this readme.md and add a colab badge [using html](https://openincolab.com/) OR copy the pure markdown version above.
+7. Open a pull request that [closes the open issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) from your forked example branch and name pull request "[Example] \<name of your example\>".
+
+Thanks for contributing to k-wave-python!

examples/at_array_as_sensor/README.md

@@ -0,0 +1,5 @@
+# Defining A Sensor Using An Array Transducer Example
+
+This example provides a demonstration of using the kWaveArray class to define an array transducer with 20 arc-shaped elements which is then used as a receiver array. It builds on the Defining A Source Using An Array Transducer Example.
+
+To read more, visit the [original example page](http://www.k-wave.org/documentation/example_at_array_as_sensor.php)