From 17937f43b6995c614c9823aba8e7c8c7b7c25f0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jaquier=20Aur=C3=A9lien=20Tristan?= Date: Thu, 22 Jun 2023 15:09:54 +0200 Subject: [PATCH 1/3] Turn readme from .md into .rst --- README.md => README.rst | 154 +++++++++++++++++++++------------------- 1 file changed, 79 insertions(+), 75 deletions(-) rename README.md => README.rst (56%) diff --git a/README.md b/README.rst similarity index 56% rename from README.md rename to README.rst index 300ee1e..9f58254 100644 --- a/README.md +++ b/README.rst @@ -2,67 +2,70 @@ ----------------- -# BluePyEfe: Blue Brain Python E-feature extraction - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Latest Release - - latest release - -
Documentation - - latest documentation - -
License - - license - -
Build Status - - Actions build status - -
DOI - - DOI - -
Gitter - - - -
Coverage - - coverage - -
+BluePyEfe: Blue Brain Python E-feature extraction +================================================= + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Latest Release + + latest release + +
Documentation + + latest documentation + +
License + + license + +
Build Status + + Actions build status + +
DOI + + DOI + +
Gitter + + + +
Coverage + + coverage + +
Introduction ============ @@ -70,24 +73,24 @@ Introduction BluePyEfe aims at easing the process of reading experimental recordings and extracting batches of electrical features from these recordings. To do so, it combines trace reading -functions and features extraction functions from the [eFel library](https://github.com/BlueBrain/eFEL). +functions and features extraction functions from the `eFel library `_. BluePyEfe outputs protocols and features files in the format used -by [BluePyOpt](https://github.com/BlueBrain/BluePyOpt) for neuron electrical +by `BluePyOpt `_ for neuron electrical model building. How to cite =========== -This software is citable using a [DOI generated by Zenodo](https://zenodo.org/record/3728192). +This software is citable using a `DOI generated by Zenodo `_. Requirements ============ -* [Python 3.8+](https://www.python.org/downloads/release/python-380/) -* [eFEL eFeature Extraction Library](https://github.com/BlueBrain/eFEL) (automatically installed by pip) -* [Numpy](http://www.numpy.org) (automatically installed by pip) -* [Scipy](https://www.scipy.org/) (automatically installed by pip) -* [Neo](https://neo.readthedocs.io/en/stable/) (automatically installed by pip) +* `Python 3.8+ `_ +* `eFEL eFeature Extraction Library `_ (automatically installed by pip) +* `Numpy `_ (automatically installed by pip) +* `Scipy `_ (automatically installed by pip) +* `Neo `_ (automatically installed by pip) * The instruction below are written assuming you have access to a command shell on Linux / UNIX / MacOSX / Cygwin @@ -96,17 +99,18 @@ Installation To install BluePyEfe run: -```bash -pip install bluepyefe -``` +.. code-block:: bash + + pip install bluepyefe + Quick Start and Operating Principle =========== -For a hands-on introduction to BluePyEfe, have a look at the notebook [examples/example_of_extraction.ipynb](examples/example_of_extraction.ipynb) +For a hands-on introduction to BluePyEfe, have a look at the notebook `examples/example_of_extraction.ipynb `_ The goal of the present package is to extract meaningful electrophysiological features (e-features) from voltage time series. -The e-features considered in the present package are the one implemented in the [eFEL python library](https://github.com/BlueBrain/eFEL). See [this pdf](https://bluebrain.github.io/eFEL/efeature-documentation.pdf) for a list of available e-features. +The e-features considered in the present package are the one implemented in the `eFEL python library `_. See `this pdf `_ for a list of available e-features. The present package makes one major assumption: E-features are more meaningful if they are coming from a set of traces rather than a single trace. And they are even more meaningful if these traces come from different cells of the same cellular type. This assumption dictates the organisation of the package and has several consequences: @@ -129,7 +133,7 @@ Each of these steps are parametrized by a number of settings, therefore we recom Coming from the legacy version =============================== The legacy version (v0.4*) is moved to the legacy branch. -Changes introduced in v2.0.0 are listed in the [CHANGELOG.rst](CHANGELOG.rst). +Changes introduced in v2.0.0 are listed in the `CHANGELOG.rst `_. That is the only file you need to look at for the changes as the future changes will also be noted there. Funding From f93ea5d1ee989a6ad220f2436defa8588318bc88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jaquier=20Aur=C3=A9lien=20Tristan?= Date: Thu, 22 Jun 2023 15:11:34 +0200 Subject: [PATCH 2/3] fix banner --- README.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 9f58254..749832a 100644 --- a/README.rst +++ b/README.rst @@ -1,4 +1,4 @@ - +|banner| ----------------- @@ -140,3 +140,4 @@ Funding ======= This work has been partially funded by the European Union Seventh Framework Program (FP7/2007­2013) under grant agreement no. 604102 (HBP), and by the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreements No. 720270 (Human Brain Project SGA1) and No. 785907 (Human Brain Project SGA2) and by the EBRAINS research infrastructure, funded from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 945539 (Human Brain Project SGA3). +.. |banner| image:: docs/source/logo/BluePyEfeBanner.jpg From d18a98d0cdfc6defa3362c53b2611e2bb0889efc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jaquier=20Aur=C3=A9lien=20Tristan?= Date: Thu, 22 Jun 2023 15:14:51 +0200 Subject: [PATCH 3/3] style fixes in README.rst --- README.rst | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/README.rst b/README.rst index 749832a..e25bf5c 100644 --- a/README.rst +++ b/README.rst @@ -71,13 +71,11 @@ Introduction ============ BluePyEfe aims at easing the process of reading experimental recordings and extracting -batches of electrical features from these recordings. To do so, it combines - trace reading +batches of electrical features from these recordings. To do so, it combines trace reading functions and features extraction functions from the `eFel library `_. BluePyEfe outputs protocols and features files in the format used -by `BluePyOpt `_ for neuron electrical - model building. +by `BluePyOpt `_ for neuron electrical model building. How to cite =========== @@ -91,13 +89,12 @@ Requirements * `Numpy `_ (automatically installed by pip) * `Scipy `_ (automatically installed by pip) * `Neo `_ (automatically installed by pip) -* The instruction below are written assuming you have access to a command shell -on Linux / UNIX / MacOSX / Cygwin +* The instruction below are written assuming you have access to a command shell on Linux / UNIX / MacOSX / Cygwin Installation ============ -To install BluePyEfe run: +To install BluePyEfe, run: .. code-block:: bash @@ -120,14 +117,14 @@ The efeatures extracted through the package will always be averaged over the tra A large part of the present software is therefore dedicated to averaging the features across set of "equivalent" recordings. To be able to average e-features across different cells in a meaningful way, an equivalence must be established between the traces coming from these different cells. It would not make sense to average the mean firing frequency obtain cell A on a 1s long step protocol with the one obtain for cell B on a ramp protocol that lasts for 500ms. We chose to define recordings as equivalent based on two criteria: (1) They have the same name and (2) they are of the same amplitude when the amplitude is expressed as a percentage of the rheobase of the cell. A pseudo-code for the main function of the package (bluepyefe.extract.extract_efeatures) could look as follows: -``` -1. Load the data to memory by reading all the files containing the traces -2. Extract the required e-features for all the traces -3. Compute the rheobases of the cells based on one or several protocols -4. Use these rheobases to associate to each protocol an amplitude expressed in % of the rheobase -5. Compute the mean and standard deviations for the e-features across traces having the same amplitude -6. Save the results and plot the traces and e-features -``` + +#. Load the data to memory by reading all the files containing the traces +#. Extract the required e-features for all the traces +#. Compute the rheobases of the cells based on one or several protocols +#. Use these rheobases to associate to each protocol an amplitude expressed in % of the rheobase +#. Compute the mean and standard deviations for the e-features across traces having the same amplitude +#. Save the results and plot the traces and e-features + Each of these steps are parametrized by a number of settings, therefore we recommend that you read carefully the docstring of the function. Coming from the legacy version