diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5f6d65df..3718e28e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,50 +6,38 @@ If you have a suggestion, please open an issue describing in detail the change y If you would like to contribute code, please: -1. Fork the repository +1. Install PyProBE with [developer settings](https://congenial-adventure-mz797n5.pages.github.io/installation.html) -2. Install the development requirements: +2. Open an issue to detail the change/addition you wish to make, unless one already exists -```bash -$ source .venv/bin/activate -$ pip install -r requirements-dev.txt -``` +3. Create a feature branch and make your changes -3. Install the git pre-commit hooks: - -```bash -$ pre-commit install -``` - -4. Open an issue to detail the change/addition you wish to make, unless one already exists - -5. Create a feature branch and make your changes - -6. Follow [Google's docstring style](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings) and ensure that the [documentation builds](#viewing-the-api-documentation) successfully: +4. Follow [Google's docstring style](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings) and ensure that the [documentation builds](#viewing-the-api-documentation) successfully: ```bash $ cd docs $ make html ``` -7. Ensure that all tests pass: +5. Ensure that all tests pass: ```bash $ pytest ``` -8. Open a pull request. In the pull request description, please describe in detail the changes your feature branch introduces, and reference the associated issue. +6. Open a pull request. In the pull request description, please describe in detail the changes your feature branch introduces, and reference the associated issue. -## Packages and dependencies -You are welcome to suggest and add new dependencies, if required for your functionality. There are two limits to this: +## PyProBE structure +Additions to the code should be made in accordance with the structure of PyProBE, to +maximise compatibility and ensure it is a maintainable package. Guidance for writing +code for PyProBE includes: 1. DataFrame operations should only be done using polars expressions. Data should be kept by default in polars LazyFrame format and only converted to DataFrame if needed for a particular operation. -2. Input variables to methods should be 1-Dimensional numpy arrays. +2. Method classes should be written in the format described in the [documentation]( + https://congenial-adventure-mz797n5.pages.github.io/creating_a_new_method.html +). ## Viewing the API documentation API documentation is built in html format, and stored locally in docs/build/html/. This can be viewed in your browser at docs/build/html/index.html. -The documentation is also continuously deployed via GitHub Actions, and can be viewed [here](https://congenial-adventure-mz797n5.pages.github.io). - -## Viewing benchmark performance -The results run on every push to the main branch can be viewed [here](https://congenial-adventure-mz797n5.pages.github.io/dev/bench/index.html) \ No newline at end of file +The documentation is also continuously deployed via GitHub Actions, and can be viewed [here](https://congenial-adventure-mz797n5.pages.github.io). \ No newline at end of file diff --git a/docs/source/creating_a_new_method.rst b/docs/source/creating_a_new_method.rst index 78982824..0b8656e5 100644 --- a/docs/source/creating_a_new_method.rst +++ b/docs/source/creating_a_new_method.rst @@ -1,4 +1,71 @@ .. _creating_a_new_method: Creating a New Method -===================== \ No newline at end of file +===================== +In PyProBE :class:`Methods ` are classes that +perform further analysis of the data. They can be peformed on any +:class:`~pyprobe.rawdata.RawData` or :class:`~pyprobe.result.Result` object. + +This document describes the standard format to be used for all PyProBE methods. +Constructing your method in this way ensures compatibility with the rest of the +PyProBE package, while keeping your code clean and easy to read. + +Start by creating your class, and an __init__ method. This is where all of the +variable assignement is performed: +1. Define the input variables to the method using the + :meth:`~pyprobe.methods.basemethod.BaseMethod.variable` method. +2. Perform the calculations using the input variables and any other functions defined + inside this method class. +3. Assign the results to the class attributes, which allows them to be read as + :class:`~pyprobe.result.Result` objects. + +Then you can add any additional functions to perform your calculations. Keep these +simple, defining all inputs as numpy arrays with minimal dimensionality. For instance, +in the example below, current and time are both 1D numpy arrays. The code could have +performed the same calculations using a single 2D array with a column for each variable, +however this would have made the code less readable. + +.. code-block:: python + + from pyprobe.methods.basemethod import BaseMethod + + class CoulombCounter(BaseMethod): + """"A method for calculating the charge passed."""" + + def __init__(self, input_data: Result): + """Initialise the coulomb counter method. + + Args: + data: The input data to the method. + """ + # define input variables to the method + self.current = self.variable("Current [A]") + self.time = self.variable("Time [s]") + + # perform the calculations + self.charge = self.coulomb_count(self.current, self.time) + + # assign the results, by calling the assign_outputs method on a dictionary + # of the results of your method + self.result = self.assign_outputs({"Charge [C]": self.charge}) + + def coulomb_count(self, current, time): + """Calculate the charge passed. + + Args: + current: The current data. + time: The time data. + + Returns: + The charge passed. + """ + return np.trapz(current, time) + +The result of the method above can be accessed as a result object by calling: + +.. code-block:: python + + result = CoulombCounter(data).result + +Which can be passed to any other Method or used in the :class:`~pyprobe.plot.Plot` +class. \ No newline at end of file diff --git a/docs/source/developer_guide.rst b/docs/source/developer_guide.rst index a5a72de2..e932fc4b 100644 --- a/docs/source/developer_guide.rst +++ b/docs/source/developer_guide.rst @@ -4,5 +4,5 @@ Developer Guide .. toctree:: :maxdepth: 2 - installation + developer_installation creating_a_new_method \ No newline at end of file diff --git a/docs/source/developer_installation.rst b/docs/source/developer_installation.rst new file mode 100644 index 00000000..21f2978f --- /dev/null +++ b/docs/source/developer_installation.rst @@ -0,0 +1,65 @@ +Installation +============ + +To install PyProBE you must be running Python 3.11 or later. It is recommended to use a +virtual environment to install PyProBE, for example venv or conda. + +The steps to install PyProBE wih developer settings are as follows: + +1. Enter a directory in which you wish to install PyProBE: + + .. code-block:: bash + + cd /path/to/your/directory + +2. Clone the repository to your local machine. This can be done either from the + main PyProBE repository or your own fork. This creates a directory called PyProBE. + + .. code-block:: bash + + git clone https://github.com/ImperialCollegeLondon/PyProBE.git + cd PyProBE + +3. Create and activate a virtual environment. + + .. tabs:: + .. tab:: venv + + In your working directory: + + .. code-block:: bash + + python -m venv venv + source .venv/bin/activate + + .. tab:: conda + + In any directory: + + .. code-block:: bash + + conda create -n pyprobe python=3.12 + conda activate pyprobe + +3. Install PyProBE as a package into your virtual environment: + + .. code-block:: bash + + cd /path/to/your/directory/PyProBE + pip install -e . + + The :code:`-e` flag installs in "editable" mode, which means changes that you + make to the code will be automatically reflected in the package inside your + virtual environment. + +4. Install the developer dependencies: + + .. code-block:: bash + + pip install -r requirements-dev.txt + +5. Install the pre-commit hooks: + + .. code-block:: bash + + pre-commit install \ No newline at end of file