Sample size planning using the VPVC

This software provides a package for sample size planning based on the variation of the posterior variance criterion (VPVC), introduced in [1]. It comes with a graphical user interface (GUI), see [2] for a guide.

Installation

This section will guide you through the installation of the sample size package, which is written in Python. No foreknowledge of Python is required.
The section is split in four parts

• How to install Python (using the Anaconda environment)
• How to install the Python package of this repository
• How to launch the GUI included in this package
• How to delete the package

For the second step a (single) command has to be entered in a terminal. As such a step is often less common in a Windows working routine, some extra details are provided for Microsoft Windows. Otherwise, the instructions below are also valid for Unix-like operating systems such as macOS or GNU/Linux.

Prerequisites: Install Python (Anaconda)

The easiest and most convenient way to install python including all packages needed for this program is to install Anaconda. Download the individual edition under:

https://www.anaconda.com/products/individual

and run the installer, which will take a couple of minutes. Use an installation directory you have writing access to (in Windows any folder of the shape C:\Users\<your-username>\...) otherwise the installation and the operations below will have to be done with admin rights. Besides this, the proposed settings will do for each step in the installation process and you will only have to keep pressing Next, Finish, etc.

Installation of the package

Arguably the most effective way to install packages in Anaconda is the Anaconda shell: On Windows press the Windows Key, enter Anaconda Prompt or Anaconda Powershell Prompt and hit enter. On Unix-like systems open a terminal emulator of your choice and run conda activate. In both cases you should now see a prompt starting with (base) (advanced Python users probably want to use a virtual environment).

The package can now be installed by entering a single command in the Anaconda shell, which depends on the format of the file containing the package

1. From a zipped folder (Ending .zip or .tar.gz): First, copy the location of the zipped folder. On Windows you can do this by opening the directory containing the zipped folder in the Explorer, holding the shift key, right-clicking the zipped folder with your mouse and selecting "Copy as path" in the drop-down menu.
   In the Anaconda shell then type the following command, with <path-to-zipped-folder> replaced by the just copied location, and hit enter:

    pip install <path-to-zipped-folder>

2. From source: Proceed as in 1. but use the path to the source folder, in the following called <path-to-source-folder>, instead:

    pip install <path-to-source-folder>

3. From the repository (not enabled yet): Insert the following in the Anaconda shell and hit enter (if you are behind proxy server you might have to add after install the option --proxy=<proxy-url>:<port-number> with <proxy-url> and <port-number> replaced accordingly.):

    pip install git+https://gitlab1.ptb.de/JoergMartin/sample_size_program.git

If the installation succeeded you can now start the GUI by running in the Anaconda shell

python -m vpvc_gui

Running the GUI:

Once installed the program can always be run everywhere in the Anaconda shell by running

python -m vpvc_gui

To leave the Anaconda shell once the program is finished type exit and hit enter. Alternatively, you can use conda deactivate if you want to leave the terminal open.

Creating an executable to click (for Windows)

If you are on Windows and you want a simple executable which you can launch by clicking on, create a new, plain textfile (for example on your desktop, by right clicking > New > text document), open it and include one line as follows:

<path-to python-interpreter> -m vpvc_gui

where <path-to-python-interpreter> should be replaced by the first output line of where.exe python within the Anaconda shell. Save the file and close it.
Then rename the file and replace the .txt ending by .bat - you can rename it for instance to vpvc_sample_size.bat. If a warning pops up that this will change the functionality of the file, click Yes.

Deleting the program

If you delete the whole Anaconda installation, the installed sample size program will also be removed. If you want to keep Anaconda, but only delete the sample size program run the following within the Anaconda shell

pip uninstall vpvc-sample-size

When asked if you really want to remove, press y. If you created a .bat file on Windows in the last section you might also want to delete it.

For advanced Python users

Avoiding Anaconda

The advantage of using Anaconda is that all scientific packages (those needed here are: matplotlib, numpy, scipy) come pre-installed and will, if all goes well, work out of the box. However, as a full environment it might be too bloated for some users. If you want to use your own python interpreter you only have to ensure that matplotlib, numpy and scipy are or can be installed by the pip command above, which on some OS (like Windows) can require you to install a C++ building tool. Once you are sure that the packages for scientific computing are or can be installed you can proceed as above. If you are thinking of using the default python interpreter of your system you probably want to create a virtual environment using the venv module, especially if you are on a Unix-like system.

Using just the algorithm without the GUI

The package vpvc_algorithm can be used as a standalone package for sample size planning based on the VPVC without a GUI. The algorithm itself is implemented in the module vpvc_algorithm.ssd_framework and its dependencies. The classes poi_ssd_framework and normal_ssd_framework are behind the computations done in the GUI. If you want to implement a custom sample size planning environment (for instance for another data distribution and/or a different prior) inherit a class from generic_ssd_framework following the instructions of its docstring.

License

copyright: Jörg Martin(PTB), 2020.

This software is licensed under the BSD-like license:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

References

[1] Martin, Jörg, and Clemens Elster. "The variation of the posterior variance and Bayesian sample size determination." Statistical Methods & Applications (2020): 1-21.

[2] Martin, Jörg and Clemens Elster. "A guide for sample size planning using the VPVC", in preparation