From a416537c3fe8a83ba7b7856ba962f2a019035e85 Mon Sep 17 00:00:00 2001 From: beckynevin Date: Wed, 7 Feb 2024 09:08:41 -0700 Subject: [PATCH] updating install directions --- README.md | 95 ++++++++++--------------------------------------------- 1 file changed, 16 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index ede5eb6..54ecbaa 100644 --- a/README.md +++ b/README.md @@ -10,26 +10,15 @@ DeepDiagnostics is a package for diagnosing the posterior from an inference meth ![Workflow overview](images/deepd_overview.png) ## Installation -Information about install. -We recommend publishing to pypi using a poetry package management system (described below) but we also provide instructions for using python virtual environments and showyourwork with conda integration. -Example of what your installation instructions should look like: +### Clone this repo +First, cd to where you'd like to put this repo and type: +> git clone https://github.com/deepskies/DeepDiagnostics.git -To install with pip: -> pip install git+https://github.com/DeepSkies/science_template.git -> -This will set up a virtual environment, which can b e run with on mac or linux -> source venv/bin/activate -> -Or on windows with -> venv\Scripts\activate.bat +Then, cd into the repo: +> cd DeepDiagnostics -Verify installation is functional is all tests are passing -> pytest - -Additionally, include how to install from source (via git clone) and associated setup. - -### poetry +### Install and use poetry to set up the environment Poetry is our recommended method of handling a package environment as publishing and building is handled by a toml file that handles all possibly conflicting dependencies. Full docs can be found [here](https://python-poetry.org/docs/basic-usage/). @@ -38,76 +27,24 @@ Install instructions: Add poetry to your python install > pip install poetry +Then, from within the DeepDiagnostics repo, run the following: + Install the pyproject file > poetry install -To add another package to your environment -> poetry add (package name) +Begin the environment +> poetry shell -To run within your environment ->poetry run (file).py - -If you wish to start from scratch: -> pip install poetry -> poetry init - -### virtual environment -At the bare minimum, project dependencies must be contained and strictly defined and shared for replication purposes. -The easiest way to do this is to use a python virtual environment. -Full instructions are found [here.](https://docs.python.org/3/library/venv.html) - -To initialize an environment: -> python3 -m venv /path/to/env -> -To activate it: -Linux and Mac: -> source venv/bin/activate -> -Windows: -> venv\Scripts\activate.bat - -And use pip as normal to install packages. - -In order to produce a file to share with your version of dependencies, produce a requirements.txt. -This can later be installed in full to a new system using `pip install -r requirements.txt`. -Note that this does not manage any versioning conflicts and can very quickly become depreciated. -> pip freeze >requirements.txt - -### show your work with conda -We also supply a ["show your work"](https://github.com/showyourwork/showyourwork) workflow to use with a conda venv which can compile the example tex file in `DeepTemplate-Science/src/tex/ms.tex` - -To execute this workflow: ->showyourwork build - -This will build your project and install the conda venv associated with the project (or just compile the document if you haven't been using it) and output the document as a pdf. -If you would like to integrate with overleaf to push your work remotely, you can do that by adding the following lines to your showyourwork.yml file: -> -> overleaf: -> -> id: URL identifying your project -> push: -> - src/tex/figures -> - src/tex/output -> pull: -> - src/tex/ms.tex -> - src/tex/bib.bib - -And adding the system variables `$OVERLEAF_EMAIL` and `$OVERLEAF_PASSWORD` with your credentials. -To do this, use a bash terminal to input the command `export OVERLEAF_EMAIL='youremail@server.org`, and do the same for your password. -To verify these are set correctly, run `echo $OVERLEAF_EMAIL`and `echo $OVERLEAF_PASSWORD`. -To complete this setup, run `showyourwork build` as if you were compiling a project. -The above snippet of the yaml file will then push anything in the `src/tex/figures` and `src/tex/output` folders to the remote, under the `images` folder. - -The existing yaml file is set up to modify the [template project](*https://www.overleaf.com/read/fsjwntpjmdzw). -The differences in the ID in the template and the url you'll see is due to the fact that only project owners have access to that ID (even if I want to share). -This limits the person who can build the project to the person that owns the overleaf page, at least until Latex sets up token authentication. -The workaround for this is account sharing, but this is not recommended. - -For more information please see the [showyourwork page on the topic](https://show-your.work/en/latest/overleaf/). +### Verify it is installed +After following the installation instructions, verify installation is functional is all tests are passing by running the following in the root directory: +> pytest ## Quickstart + +**Fill this in is TBD** + Description of the immediate steps to replicate your results, pointing to a script with cli execution. You can also point to a notebook if your results are highly visual and showing plots in line with code is desired.