Merge pull request #44 from MobileTeleSystems/dev

Ambrosia 0.4.0

CHANGELOG.rst

@@ -1,51 +1,87 @@
 Release Notes
 =============
 
+Version 0.4.0 (21.04.2023)
+---------------------------
+
+* Documentation and usage examples have been substantially reworked and updated. 
+
+* The ``Designer`` class and design methods functionality is updated. 
+
+  * Empirical design now supports the choice of hypothesis alternative and group ratio parameter
+
+  * Look of resulting tables with calculated parameters is unified for all design methods
+
+  * Changed multiprocessing strategy for bootstrap criterion
+
+* The ``Tester`` class functionality is updated. 
+
+  * Spark data support for the ``Tester`` class is added. Independent t-test is available now
+
+  *  Bootstrap criterion can now return deterministic output using a ``random_seed`` parameter
+
+  * Paired bootstrap criterion is now available
+
+  * MHC now is optional and takes into account the number of passed metrics
+
+  *  ``first_errors`` parameter renamed to ``first_type_errors``
+
+* ``pyspark`` package now is optional and could be installed using ``pip`` extras.
+
+* Fixed a set of bugs.
+
+
 Version 0.3.0 (15.02.2023)
 ---------------------------
 
-|
-| The ``Designer`` class and design methods functionality is updated. 
-|
-- Theoretical design now supports the choice of hypothesis alternative and group ratio parameter. 
-  These calculations now use Statsmodels solvers.
-- Experimental parameters for binary data can now also be theoretically designed using both 
-  the asin variance-stabilizing transformation and the normal approximation.
-|
-| All preprocessor classes, except for the ``Preprocessor``, have changed their api and have updated functionality.
-|
-- Preprocessing classes now use ``fit`` and ``transform`` methods to get transformation parameters 
-  and apply transformation on pandas tables.
-- Fitted classes now can now be saved and loaded from json files.
-- Table column names used when fitting class instances are now strictly fixed in instance attributes.
-|
-| The ``Preprocessor`` class is updated.
-|
-- Added new transformation methods.
-- The executed transformation pipeline can now be saved and loaded from a json file. 
-  This can be used to store and load the entire experimental data processing pipeline.
-- The data handling methods of the class have changed some parameters to match the changes in the classes used.
-|
-| The ``IQRPreprocessor`` class now is available in ``ambrosia.preprocessing``.
-|
-- It can be used to remove outliers based on quartile and interquartile range estimates.
-|
-| The ``RobustPreprocessor`` class is updated.
-|
-- It now supports different types of tails for removal: ``both``, ``right`` or ``left``.
-- For each processed column, a separate alpha portion of the distribution can be passed.
-|
-| The ``BoxCoxTransformer`` class now is available in ``ambrosia.preprocessing``.
-|
-- It can be used for data distribution normalization.
-|
-| The ``LogTransformer`` class now is available in ``ambrosia.preprocessing``.
-|
-- It can be used to transform data for variance reduction.
-|
-| The ``MLVarianceReducer`` class is updated.
-|
-- Now it can store and load the selected ML model from a single specified path.
+* The ``Designer`` class and design methods functionality is updated. 
+
+  * Theoretical design now supports the choice of hypothesis alternative and group ratio parameter 
+
+  * These calculations now use Statsmodels solvers
+
+  * Experimental parameters for binary data can now also be theoretically designed using both 
+    the asin variance-stabilizing transformation and the normal approximation
+
+* All preprocessor classes, except for the ``Preprocessor``, have changed their api and have updated functionality
+
+  * Preprocessing classes now use ``fit`` and ``transform`` methods to get transformation parameters 
+    and apply transformation on pandas tables
+
+  * Fitted classes now can now be saved and loaded from json files
+
+  * Table column names used when fitting class instances are now strictly fixed in instance attributes
+
+* The ``Preprocessor`` class is updated.
+
+  * Added new transformation methods
+
+  * The executed transformation pipeline can now be saved and loaded from a json file. 
+    This can be used to store and load the entire experimental data processing pipeline
+
+  * The data handling methods of the class have changed some parameters to match the changes in the classes used
+
+* The ``IQRPreprocessor`` class now is available in ``ambrosia.preprocessing``.
+
+  * It can be used to remove outliers based on quartile and interquartile range estimates
+
+* The ``RobustPreprocessor`` class is updated.
+
+  * It now supports different types of tails for removal: ``both``, ``right`` or ``left``
+
+  * For each processed column, a separate alpha portion of the distribution can be passed.
+
+* The ``BoxCoxTransformer`` class now is available in ``ambrosia.preprocessing``
+
+  * It can be used for data distribution normalization.
+
+* The ``LogTransformer`` class now is available in ``ambrosia.preprocessing``
+
+  * It can be used to transform data for variance reduction.
+
+* The ``MLVarianceReducer`` class is updated.
+
+  * Now it can store and load the selected ML model from a single specified path
 
 Version 0.2.0 (22.11.2022)
 ---------------------------

CONTRIBUTING.rst

@@ -0,0 +1,68 @@
+Contributing Guide 
+===================
+
+`Ambrosia` is an open source project and there are many ways to contribute, from writing tutorials or blog posts, 
+improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated 
+into `Ambrosia` itself.
+
+Bug reports
+-----------
+
+If you think you have found a bug in `Ambrosia`, first make sure that you are testing against 
+the latest version of package - your issue may already have been fixed. If not, 
+search our issues list on GitHub in case a similar issue has already been opened.
+
+It is very helpful if you can prepare a reproduction of the bug. 
+In other words, provide a small test case which we can run to confirm your bug. 
+It makes it easier to find the problem and to fix it. 
+
+Provide as much information as you can. The easier it is for us to recreate your problem,
+the faster it is likely to be fixed.
+
+Feature requests
+----------------
+
+If you find yourself wishing for a feature that doesn't exist in `Ambrosia`, you can open an issue 
+on our `issues list   <https://github.com/MobileTeleSystems/Ambrosia/issues>`_ on GitHub 
+which describes the feature you would like to see, why you need it, and how it should work.
+
+
+Contributing code and documentation changes
+-------------------------------------------
+
+If you have a bugfix or new feature that you would like to contribute to `Ambrosia`, 
+please find or open an issue about it first. Talk about what you would like to do. 
+It may be that somebody is already working on it, 
+or that there are particular issues that you should know about before implementing the change.
+
+There are many approaches to fixing a problem and it is important to find the best approach 
+before writing too much code.
+
+Branching
+---------
+
+Those users with Contributor permissions can directly clone the repository and work on a branch within it.
+
+Those without Contibutor permissions will need to fork the main repository to work on your changes. 
+Simply navigate to our GitHub page and click the “Fork” button at the top. 
+Once you have forked the repository, you can clone your new repository and start making edits.
+
+When using git, it is best to isolate each topic or feature into a “topic branch”. 
+Branches are a great way to group commits related to one feature together, 
+or to isolate different efforts when you might be working on multiple topics at the same time.
+
+While it takes some experience to get the right feel about how to break up commits, 
+a topic branch should be limited in scope to a single issue. If you are working on multiple issues, 
+please create multiple branches and submit them for review separately.
+
+Pull Request Guidelines
+-----------------------
+
+Create a pull request for preliminary review or merging into the project when you are ready.
+
+If you need to make any adjustments to your pull request, just push the updates to your branch. 
+Your pull request will automatically track the changes on your development branch and update.
+
+You may merge the Pull Request in once you have the sign-off of two other developers, 
+or if you do not have permission to do that, you may request the second reviewer to merge it for you. 
+We expect to have a minimum of one approval from someone else on the core team.

Makefile

@@ -28,6 +28,7 @@ reports:
 .venv:
 	@echo "Creating virtualenv...\t\t"
 	poetry install --no-root
+	poetry install --all-extras
 	@echo "[Installed]"
 
 install: .venv reports

README.rst

@@ -31,35 +31,22 @@ Ambrosia
 
 .. title
 
-**Ambrosia** is a Python library for A/B tests design, split and effect 
-measurement. It provides rich set of methods for conducting full 
-A/B test pipeline. 
+*Ambrosia* is a Python library for A/B tests design, split and effect measurement. 
+It provides rich set of methods for conducting full A/B testing pipeline. 
 
-An experiment design stage is performed using metrics historical data 
-which could be processed in both forms of pandas and spark dataframes 
-with either theoretical or empirical approach. 
-
-Group split methods support different strategies and multi-group split, 
-which allows to quickly create control and test groups of interest. 
-
-Final effect measurement stage is conducted via testing tools that 
-are able to return relative and absolute effects and construct corresponding 
-confidence intervalsfor continious and binary variables. 
-Testing tools as well as design ones support significant number of 
-statistical criteria, like t-test, non-parametric, and bootstrap. 
-
-For additional A/B tests support library provides features and tools 
-for data preproccesing and experiment acceleration.
+The project is intended for use in research and production environments 
+based on data in pandas and Spark format.
 
 .. functional
 
 Key functionality
 -----------------
 
-* Pilots design ✈
+* Pilots design 🛫
 * Multi-group split 🎳
 * Matching of new control group to the existing pilot 🎏
-* Getting the experiments result evaluation as p-value, point estimate of effect and confidence interval 🎞
+* Experiments result evaluation as p-value, point estimate of effect and confidence interval 🎞
+* Data preprocessing ✂️
 * Experiments acceleration 🎢
 
 .. documentation
@@ -75,21 +62,33 @@ and `Tutorials <https://github.com/MobileTeleSystems/Ambrosia/tree/main/examples
 Installation
 ------------
 
+You can always get the newest *Ambrosia* release using ``pip``.
 Stable version is released on every tag to ``main`` branch. 
 
 .. code:: bash
     
     pip install ambrosia 
 
-**Ambrosia requires Python 3.7+**
+Starting from version ``0.4.0``, the ability to process PySpark data is optional and can be enabled 
+using ``pip`` extras during the installation.
+
+.. code:: bash
+    
+    pip install ambrosia[pyspark]
 
 .. usage
 
 Usage
 -----
 
-Designer 
-~~~~~~~~
+The main functionality of *Ambrosia* is contained in several core classes and methods, 
+which are autonomic for each stage of an experiment and have very intuitive interface. 
+
+|
+
+Below is a brief overview example of using a set of three classes to conduct some simple experiment.
+
+**Designer**
 
 .. code:: python
 
@@ -98,8 +97,7 @@ Designer
     designer.run('size') 
 
 
-Splitter
-~~~~~~~~
+**Splitter**
 
 .. code:: python
 
@@ -108,8 +106,7 @@ Splitter
     splitter.run(groups_size=500, method='simple') 
 
 
-Tester 
-~~~~~~
+**Tester**
 
 .. code:: python
 
@@ -162,8 +159,8 @@ To remove virtual environment run
 
 .. contributors
 
-Communication
--------------
+Authors
+-------
 
 **Developers and evangelists**:
 

ambrosia/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0