Merge pull request #699 from njtierney/update-installation-notes

Update installation notes

Author: njtierney

R/install_greta_deps.R

@@ -4,14 +4,15 @@
 #'   these are TF 2.15.0, TFP 0.23.0, and Python 3.10. These Python modules
 #'   will be installed into a conda environment named "greta-env-tf2".
 #'
-#'   To see install notes or errors, there isn't an argument to specify,
+#'   To see installation notes or errors, there isn't an argument to specify,
 #'     instead you will need to specify and environment variable,
 #'     `GRETA_INSTALLATION_LOG`, with
 #'     `Sys.setenv('GRETA_INSTALLATION_LOG'='path/to/logfile.html')`. Or use
 #'     [greta_set_install_logfile()] to set the path, e.g.,
 #'     `greta_set_install_logfile('path/to/logfile.html')`. You can also skip
-#'     the restarting of R and use [write_greta_install_log()], which
-#'     installation notes will indicate how to use if you haven't specified.
+#'     the restarting of R and use [write_greta_install_log()]. If you have
+#'     not specified the `GRETA_INSTALLATION_LOG` environmental variable, the
+#'     installation notes will indicate how to use [write_greta_install_log()].
 #'
 #' @param python_deps object created with [greta_python_deps()] where you
 #'   specify python, TF, and TFP versions. By default these are TF 2.15.0,
@@ -42,10 +43,11 @@
 #'  package versions, and forcibly switch over to using that conda environment.
 #'
 #'  If you don't want to use conda or the "greta-env-tf2" conda environment, you
-#'  can install these specific versions of tensorflow (version 2.6.0), and
-#'  tensorflow-probability (version 0.14.1), and ensure that the python
-#'  environment that is initialised in this R session has these versions
-#'  installed. This is now always straightforward, so we recommend installing
+#'  can install versions that you like, e.g., using [reticulate::py_install()].
+#'  If you want to see which versions of TF, TFP, and Python work with each
+#'  other (at least according to information from tensorflows website), see the
+#'  data `greta_deps_tf_tfp`, which is provided with greta. Managing your own
+#'  installation is not always straightforward, so we recommend installing
 #'  the python packages using `install_greta_deps()` for most users.
 #'
 #' @name install_greta_deps
@@ -201,17 +203,44 @@ restart_or_not <- function(restart){
 
 #' Specify python dependencies for greta
 #'
-#' A helper function for specifying versions of Tensorflow (TF), Tensorflow Probability (TFP), and Python.
+#' A helper function for specifying versions of Tensorflow (TF), Tensorflow
+#'   Probability (TFP), and Python. Defaulting to 2.15.0, 0.23.0, and 3.10.
+#'   You can specify the version that you want to install, but it will check
+#'   if these are compatible. That is, if you specify versions of TF/TFP/Python
+#'   which do not work with each other, it will error and give a suggested
+#'   version to install. It does this by using a dataset, `greta_deps_tf_tfp`,
+#'   to check if the versions of TF, TFP, and Python specified are compatible
+#'   on your operating system. You can inspect this  dataset with
+#'   `View(greta_deps_tf_tfp)`.
 #'
-#' @param tf_version Character. Tensorflow (TF) version in format major.minor.patch. Default is "2.15.0".
-#' @param tfp_version Character.Tensorflow probability (TFP) version major.minor.patch. Default is "0.23.0".
-#' @param python_version Character. Python version in format major.minor.patch. Default is "3.10".
+#' @param tf_version Character. Tensorflow (TF) version in format
+#'   major.minor.patch. Default is "2.15.0".
+#' @param tfp_version Character.Tensorflow probability (TFP) version
+#'   major.minor.patch. Default is "0.23.0".
+#' @param python_version Character. Python version in format major.minor.patch.
+#'   Default is "3.10".
 #'
-#' @return list of dependencies
+#' @return data frame of valid dependencies
 #' @export
 #'
 #' @examples
 #' greta_python_deps()
+#' greta_python_deps(tf_version = "2.15.0")
+#' greta_python_deps(tf_version = "2.15.0", tfp_version = "0.23.0")
+#' greta_python_deps(tf_version = "2.15.0", python_version = "3.10")
+#' greta_python_deps(
+#'   tf_version = "2.15.0",
+#'   tfp_version = "0.23.0",
+#'   python_version = "3.10"
+#'   )
+#' # this will fail
+#' \dontrun{
+#' greta_python_deps(
+#'   tf_version = "2.11.0",
+#'   tfp_version = "0.23.0",
+#'   python_version = "3.10"
+#'   )
+#'   }
 greta_python_deps <- function(tf_version = "2.15.0",
                               tfp_version = "0.23.0",
                               python_version = "3.10"){

R/reinstallers.R

@@ -3,14 +3,17 @@
 #' This can be useful when debugging greta installation to get to "clean slate".
 #'   There are four functions:
 #'
-#'   - `remove_greta_env()` removes the 'greta-env-tf2' conda environment
-#'   - `remove_miniconda()` removes miniconda installation
-#'   - `reinstall_greta_env()` remove 'greta-env-tf2' and reinstall it using `greta_create_conda_env()` (which is used internally).
-#'   - `reinstall_miniconda()` removes miniconda and reinstalls it using `greta_install_miniconda()` (which is used internally)
+#'   - [remove_greta_env()] removes the 'greta-env-tf2' conda environment
+#'   - [remove_miniconda()] removes miniconda installation
+#'   - [reinstall_greta_env()] remove 'greta-env-tf2' and reinstall it
+#'     using [greta_create_conda_env()] (which is used internally).
+#'   - [reinstall_miniconda()] removes miniconda and reinstalls it using
+#'     [greta_install_miniconda()] (which is used internally)
 #'
 #' @return invisible
 #' @export
 #' @name reinstallers
+#' @seealso [destroy_greta_deps()]
 #'
 #' @examples
 #' \dontrun{

R/write-logfiles.R

@@ -1,7 +1,7 @@
 #' Set logfile path when installing greta
 #'
 #' To help debug greta installation, you can save all installation output
-#' to a single logfile.
+#'   to a single logfile.
 #'
 #' @param path valid path to logfile - should end with `.html` so you
 #'   can benefit from the html rendering.

README.md

@@ -40,19 +40,21 @@ devtools::install_github("greta-dev/greta")
 
 # Installing Python Dependencies
 
-The `install_greta_deps()` function helps install the Python dependencies (Google's [TensorFlow](https://www.tensorflow.org/) version 1.14.0, and  [tensorflow-probability](https://github.com/tensorflow/probability) version 0.7.0).
+The `install_greta_deps()` function helps install the Python dependencies (Google's [TensorFlow](https://www.tensorflow.org/) and [tensorflow-probability](https://github.com/tensorflow/probability)). 
 
-This helper function, `install_greta_deps()`, installs the exact pythons package versions needed. It also places these inside a "greta-env" conda environment. This isolates these exact python modules from other python installations, so that only `greta` will see them. This helps avoids installation issues, where previously you might update tensorflow on your computer and overwrite the current version needed by `greta`. Using this "greta-env" conda environment means installing other python packages should not be impact the Python packages needed by `greta`.
+By default, `install_greta_deps()` installs versions TF 2.15.0, and TFP version 0.23.0, using python 3.10. To change the versions of TF, TFP, or python that you want to use, you specify the `python_deps` argument of `install_greta_deps()`, which used `greta_python_deps()`. See `?install_greta_deps()` or `?greta_python_deps()` for more information.
+
+This helper function, `install_greta_deps()`, installs the exact pythons package versions needed. It also places these inside a conda environment, "greta-env-tf2". This isolates these exact python modules from other python installations, so that only `greta` will see them. This helps avoids installation issues, where previously you might update tensorflow on your computer and overwrite the current version needed by `greta`. Using this "greta-env-tf2" conda environment means installing other python packages should not be impact the Python packages needed by `greta`.
 
 If these python modules aren't yet installed, when `greta` is used, it provides instructions on how to install them for your system. If in doubt follow those. 
 
 <!-- badges: start -->
 [![Codecov test coverage](https://codecov.io/gh/greta-dev/greta/branch/master/graph/badge.svg)](https://app.codecov.io/gh/greta-dev/greta?branch=master)
 [![R-CMD-check](https://github.com/greta-dev/greta/workflows/R-CMD-check/badge.svg)](https://github.com/greta-dev/greta/actions)
-[![cran
-version](http://www.r-pkg.org/badges/version/greta)](https://CRAN.R-project.org/package=greta)
+[![cran version](http://www.r-pkg.org/badges/version/greta)](https://CRAN.R-project.org/package=greta)
 [![license](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/license/apache-2-0)
 [![doi](https://zenodo.org/badge/73758247.svg)](https://zenodo.org/badge/latestdoi/73758247)
 [![joss](https://joss.theoj.org/papers/10.21105/joss.01601/status.svg)](https://joss.theoj.org/papers/10.21105/joss.01601)
 ![](logos/bottom_banner.png)
+[![greta status badge](https://greta-dev.r-universe.dev/badges/greta)](https://greta-dev.r-universe.dev/greta)
 <!-- badges: end -->