diff --git a/README.md b/README.md index baf53ce..c1d3404 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Learn more at https://face-rhythm.readthedocs.io/ # Installation -#### 0. Requirements
+### 0. Requirements
- Operating system: - Ubuntu >= 18.04 (other linux versions usually okay but not actively maintained) - Windows >= 10 @@ -20,17 +20,23 @@ Learn more at https://face-rhythm.readthedocs.io/ - The below commands should be run in the terminal (Mac/Linux) or Anaconda Prompt (Windows).
-#### 1. Clone this repo
+### 1. Clone this repo
+This will create a folder called **face-rhythm** in your current directory. This repository folder contains the source code AND the interactive notebooks needed to run the pipeline.
**`git clone https://github.com/RichieHakim/face-rhythm/`**
**`cd face-rhythm`**
-#### 2. Create a conda environment +### 2. Create a conda environment +This will also install the **face-rhythm** package and all of its dependencies into the environment.
**`conda env create --file environment.yml`**
-In either case, this step will create a conda environment named face-rhythm. Activate it: +Activate the environment:
**`conda activate face_rhythm`**
-#### 3. Run the set up script
+### Optional Direct installation
+You can also directly install the **face-rhythm** package from PyPI into the environment of your choice. Note that you will still need to download/clone the repository for the notebooks.
+##### Option 1: Install from PyPI
+**`pip install face-rhythm`**
+##### Option 2: Install from source
**`pip install -e .`**

@@ -38,25 +44,14 @@ In either case, this step will create a conda environment named face-rhythm. Act # Usage -#### 1. Create a "project directory" where we will save intermediate files, videos, and config files.
-This project directory should ideally be outside of the repo, and you'll create a new one each time -you analyze a new dataset. You may want to save a copy of the .ipynb file you use for the run there. -**`cd directory/where/you/want/to/save/your/project`**
-**`mkdir face_rhythm_run`**
+#### Notebooks +The easiest way to use **face-rhythm** is through the interactive notebooks. They are found in the following directory: `face-rhythm/notebooks/`.
+- The `interactive_pipeline_basic.ipynb` notebook contains the main pipeline and instructions on how to use it.
+- The `interactive_set_ROIs_only.ipynb` notebook is useful for when you want to run a batch job of many videos/sessions and need to set the ROIs for each video/session ahead of time.
-#### 2. Copy the interactive notebook to your project directory -We recommend copying the interactive notebook from your face-rhythm repository to your project folder each time you make a new project. This will allow you to have one notebook per project, which will keep your analyses from potentially conflicting if you run different datasets through the same notebooks. -**`cp /path to face-rhythm repo/face-rhythm/notebooks/interactive_pipeline_basic.ipynb /path to project/face_rhythm_run/`**
+#### Command line +The basic pipeline in the interactive notebook is also provided as a function within the `face_rhythm/pipelines.py` module. In the `scripts` folder, you'll find a script called `run_pipeline_basic.py` that can be used to run the pipeline from the command line. An example `params.json` file is also in that folder to use as a template for your runs.
-`interactive_pipeline_basic.ipynb` is a basic demo notebook that runs through the entire pipeline. -See the `notebooks/other` folder for some notebooks demonstrating other kinds of analyses. These are more experimental and are subject to change as we develop new analyses. - -#### 3. Open up jupyter notebook! The plots display better using Jupyter Notebook than Jupyter Lab or VSCode.
-**`jupyter notebook`**
-If you run into a kernel error at this stage and are a Windows user, check out: -https://jupyter-notebook.readthedocs.io/en/stable/troubleshooting.html#pywin32-issues - -Navigate to your folder containing your interactive notebook and launch it by clicking on it!
@@ -66,7 +61,7 @@ Navigate to your folder containing your interactive notebook and launch it by cl face-rhythm ├── notebooks <- Jupyter notebooks containing the main pipeline and some demos. | ├── basic_face_rhythm_notebook.ipynb <- Main pipeline notebook. - | └── demo_align_temporal_factors.ipynb <- Demo notebook for aligning temporal factors. + | └── interactive_set_ROIs_only.ipynb <- Notebook for setting ROIs only. | ├── face-rhythm <- Source code for use in this project. │   ├── project.py <- Contains methods for project directory organization and preparation diff --git a/environment.yml b/environment.yml index 5eaa6d3..a770321 100644 --- a/environment.yml +++ b/environment.yml @@ -5,5 +5,4 @@ dependencies: - python=3.11 - pip - pip: - # install from requirements.txt - - -r requirements.txt \ No newline at end of file + - face-rhythm \ No newline at end of file diff --git a/face_rhythm/__init__.py b/face_rhythm/__init__.py index 682fc84..556667b 100644 --- a/face_rhythm/__init__.py +++ b/face_rhythm/__init__.py @@ -23,4 +23,4 @@ for pkg in __all__: exec('from . import ' + pkg) -__version__ = '0.2.0' \ No newline at end of file +__version__ = '0.2.1' \ No newline at end of file diff --git a/scripts/params_pipeline_basic.json b/scripts/params_pipeline_basic.json index 4b020dd..bc83f5a 100644 --- a/scripts/params_pipeline_basic.json +++ b/scripts/params_pipeline_basic.json @@ -10,6 +10,7 @@ "directory_project": "/path/to/new/project/directory/", "overwrite_config": false, "update_project_paths": true, + "random_seed": null, "initialize_visualization": false, "verbose": 2 }, @@ -140,6 +141,7 @@ "n_iter_max": 200, "init": "random", "svd": "truncated_svd", + "random_state": null, "tol": 1e-09, "verbose": true },