TIMESS WEB APP V 0.1 (20_02_23) README FILE 

Time and Space Sampling power tool (TIMESS)
Self executable to conduct power analysis to estimate the number of locations and repeated measurements 
of a mosquito survey when mosquitoes have seasonal patterns and are spatially clustered.

FUNDING

This work was funded by the Bill and Melinda Gates Foundation under the UCSF Malaria Elimination Initiative
project ‘Equipping countries for evidence-based malaria intervention strategies’. 
Luigi Sedda is also supported by the Wellcome Trust NIHR–Wellcome Partnership for Global Health Research Collaborative Award, 
CEASE (220870/Z/20/Z). 
The funders had no role in study design and analysis, decision to publish, or preparation of the software.

Project principal investigator (BMGF): Allison Tatarsky (MEI)
Project principal investigator (Wellcome Trust): Martin Donnelly (LSTM)

CREATORS
Function creator: Dr Luigi Sedda
Wep app developer: Dr Russ Cain
Luigi Sedda and Russ Cain are part of the Lancaster Ecology and Epidemiology Group (LEEG),
at Lancaster Medical School, Lancaster University, UK.

INTRODUCTION

TIMESS is a power test tool that evaluates optimal number of locations and repeated measurements
for a fixed effect size, power, significance level, seasonality and spatial clustering.
The function allows for user-defined temporal autocorrelation between repeated measurements (seaonality described by
the mosquito population growth) and level of spatial clustering, the latter expressed as proportion of variance 
within sites and variance between sites to the overall variance (therefore a 
low level of clustering means that a greater part of the variance is explained by between sites variation instead of 
within site variation). 

USAGE

Enter values in the form on the left, then you can examine the graph to learn how sensitive the required number 
of repeated measurments and sites are to the input values you've provided.
All inputs are required and the change of one input automatically produce the new graph.
Help file is provided within the tool.

The graph is intended to provide you with a nice visual aid of how sensitive the required number of sites and repeated 
measurements are to the input parameter values. The upper plot shows the seasonal curve.
The main plot is the power and sample size graph.
The y-axis (vertical) of the graph is the number of repeated measurements, and the x-axis (horizontal) the number of sites (locations). 
The plot reports the power curves for 0.6,0.65,0.7,0.75,0.8,0.85,0.9,0.95, and each of them has different combinations of optimal 
repeated measurements and number of sites. However for the specific seasonality and spatial clustering the optimal is shown where the 
two dotted lines intersect at the power curve defined by the user. 
The calculator always round up the calculated sample size to the nearest whole number, which may create a "step" pattern in the graph.

The legend on the upper right corner for the main graph shows the colours of each power curve starting from the one identified by the user,
while the optimal number of repeated measurements and number of sites is shown as the main title of the graph.

Data can be dowload, e.g. the matrix of optimal number of location at different number of repeated measures and powers; and 
the summary results. Summary results report the optimal number of repeated measurements and locations, the total sampling in 
terms of number of mosquitoes that need to be collected when considering temporal correlation and clustering and when collections 
are considered independent (total sampling for independent data). Finally, the variance ratio (VR) indicates the amount of variance 
of the test with correlated repeated measurements, i.e. 1 – VR is the reduction in variance in comparison with a test with two 
independent means (Morgan and Case 2013).

TIMESS APP

TIMESS WEB APP is a stand-alone framework which provides a web-interface between the user and the
original TIMESS R code using the DesktopDeployR framework developed by HJ Lee. It requires
javascript and Shiny web app development tools to compile  the original R code within an 
independent R distribution (R Portable).

MINIMUM SYSTEM REQUIREMENTS:
1. Windows 10  
2. 1GHZ Pentium Atom processor or equivalent
3. 4GB RAM
4. JAVA V.16 
5. 2GB Hard drive space

Please extract the entire folder before starting. A folder called TIMES_DEPLOYABLE_20_06_22 is created.

QUICKSTART:
1. Open the folder TIMESS_DEPLOYABLE_20_06_22 and double-click on TIMESS.bat. If you have linux or a MAC please run the bat file
   from R-studio.
2. Input/select the parameters as required. 
3. You can save the figures and download the tables.


TROUBLESHOOTING:
1. Please ensure you have an up-to-date version of Java installed.
2. Please ensure the package is unzipped before running.
3. Google Chrome and MS Edge are tested browsers. Please try using these browsers. 

CREDITS:
Function coded in R by Luigi Sedda.
DesktopDeployR framework developed by HJLee (https://github.com/wleepang/DesktopDeployR)
TIMESS WEB produced by Dr Russell Cain. 

CONTACTS:
Dr Luigi Sedda (Lancaster University): l.sedda@lancaster.ac.uk


LICENSE:
Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)
The third-parties copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.