maxrousseau/pfla

pfla: Python Facial Landmark Analysis

pfla's Issues

JOSS - Add Community Guidelines

Can you provide a Contribution.md file with clear guidelines for how someone can

1. Contribute to the software
2. Report issues or problems with the software
3. Seek support

See example guide here:
https://help.github.com/articles/setting-guidelines-for-repository-contributors/

JOSS: Review install guideline

Couple of points to address:

• I don't think that you depend on argparse since it is in the standard library.
• You should as well mention that you support Python 3.5+
• Is there a reason for the package to not work cross-platform. All packages installed with conda should work under MacOS and Windows.
• I would remove the install_requires from the setup.py since the opencv package will be installed from pip even if it was installed with conda. You can instead create a requirements.txt for the PyPi folks.
• The statement Place the downloaded ... is not correct for all environment and depending of the way that you installed the software.

JOSS - Missing API documentation

The readme points to documentation link here https://pfla.readthedocs.io/en/latest/overview.html.
However, I don't see any API documentation of the core functions implemented in face_detect.py and annotate.py. These strike me as the core functionality.

https://github.com/maxrousseau/pfla/blob/master/pfla/fcn/annotate.py
https://github.com/maxrousseau/pfla/blob/master/pfla/fcn/face_detect.py

I would ensure that the classes and key functions support additional documentation give both a few sentences about its purpose, input and output arguments. Use an example from scikit-learn such as http://scikit-learn.org/stable/modules/generated/sklearn.feature_extraction.image.extract_patches_2d.html#sklearn.feature_extraction.image.extract_patches_2d as a guide.

JOSS - Problem of install with conda

I cannot install the package out-of-the-box on linux using conda:

(base) ✘-2 /tmp 
16:45 $ conda create --name pfla python=3
Solving environment: done

## Package Plan ##

  environment location: /home/lemaitre/miniconda3/envs/pfla

  added / updated specs: 
    - python=3


The following packages will be downloaded:

    package                    |            build
    ---------------------------|-----------------
    libgcc-ng-8.2.0            |       hdf63c60_0         7.6 MB
    certifi-2018.8.13          |           py37_0         139 KB
    setuptools-40.0.0          |           py37_0         551 KB
    libstdcxx-ng-8.2.0         |       hdf63c60_0         2.9 MB
    ------------------------------------------------------------
                                           Total:        11.2 MB

The following NEW packages will be INSTALLED:

    ca-certificates: 2018.03.07-0           
    certifi:         2018.8.13-py37_0       
    libedit:         3.1.20170329-h6b74fdf_2
    libffi:          3.2.1-hd88cf55_4       
    libgcc-ng:       8.2.0-hdf63c60_0       
    libstdcxx-ng:    8.2.0-hdf63c60_0       
    ncurses:         6.1-hf484d3e_0         
    openssl:         1.0.2p-h14c3975_0      
    pip:             10.0.1-py37_0          
    python:          3.7.0-hc3d631a_0       
    readline:        7.0-ha6073c6_4         
    setuptools:      40.0.0-py37_0          
    sqlite:          3.24.0-h84994c4_0      
    tk:              8.6.7-hc745277_3       
    wheel:           0.31.1-py37_0          
    xz:              5.2.4-h14c3975_4       
    zlib:            1.2.11-ha838bed_2      

Proceed ([y]/n)? y


Downloading and Extracting Packages
libgcc-ng-8.2.0      | 7.6 MB    | ########################################## | 100% 
certifi-2018.8.13    | 139 KB    | ########################################## | 100% 
setuptools-40.0.0    | 551 KB    | ########################################## | 100% 
libstdcxx-ng-8.2.0   | 2.9 MB    | ########################################## | 100% 
Preparing transaction: done
Verifying transaction: done
Executing transaction: done
#
# To activate this environment, use
#
#     $ conda activate pfla
#
# To deactivate an active environment, use
#
#     $ conda deactivate

(base) ✔ /tmp 
16:46 $ conda activate pfla
(pfla) ✔ /tmp 
16:46 $ pip install pfla
Collecting pfla
  Downloading https://files.pythonhosted.org/packages/bb/8b/af02451e1cc9d9521d8ee3f81818d8f8dec48b1683c32853d9d265f4ac02/pfla-0.1.6-py3-none-any.whl (1.9MB)
    100% |████████████████████████████████| 1.9MB 4.1MB/s 
Collecting dlib (from pfla)
  Downloading https://files.pythonhosted.org/packages/df/aa/6a9bb2a763107bb2606d6ee1aa65fcd3b51375a9ef6436e9c9280b0dd63c/dlib-19.15.0.tar.gz (3.3MB)
    100% |████████████████████████████████| 3.3MB 3.3MB/s 
Collecting progress (from pfla)
  Downloading https://files.pythonhosted.org/packages/e9/ff/7871f3736dc6707435b2a2f217c46b5a5bc6ea7e0a9a443cd69146a1afd1/progress-1.4.tar.gz
Collecting opencv-python (from pfla)
  Downloading https://files.pythonhosted.org/packages/8f/8f/a5d2fa3a3309c4e4aa28eb989d81a95b57c63406b4d439758a1a0a810c77/opencv_python-3.4.2.17-cp37-cp37m-manylinux1_x86_64.whl (25.0MB)
    100% |████████████████████████████████| 25.0MB 980kB/s 
Collecting rpy2 (from pfla)
  Downloading https://files.pythonhosted.org/packages/f1/98/c7652cc9d7fc0afce74d2c30a52b9c9ac391713a63d037e4ab8feb56c530/rpy2-2.9.4.tar.gz (194kB)
    100% |████████████████████████████████| 204kB 7.5MB/s 
    Complete output from command python setup.py egg_info:
    Error: Tried to guess R's HOME but no command 'R' in the PATH.
    
    ----------------------------------------
Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-install-8cv6gq93/rpy2/

JOSS - Incomplete Software Paper

Hello,

Some enhancements to https://github.com/maxrousseau/pfla/blob/master/paper/paper.md are needed.

Can you also provide a laymen's description of what types of inputs/outputs your toolbox provides? Despite knowing something about statistical shape analysis, I'm not able to follow exactly what the software can do for me. If you can add a small figure, even better! Some important information is buried in the middle. On pg. 2 you describe M_patient and V_patient. I would try to make this section even simpler/clearer.

Can you add references to the specific solvers and algorithms used for Generalized Procrustes Analysis in your software?
Fix the references for Dryden 2017 to point to the specific package url
https://cran.r-project.org/web/packages/shapes/shapes.pdf

And the corresponding book that discusses the algorithms
e Dryden, I.L. and Mardia, K.V. (2016). Statistical shape analysis,
with Applications in R (2nd Edition), John Wiley and Sons.

JOSS - package install

Could you provide directly on the documentation the install commands instead of redirecting to the GitHub page. Some users might be lost to land on source code page

JOSS Unit tests

I have some issues with the tests:

• The test should be run using pytest instead of just python
• The unit test are making some appriori on where the data are:

for p in sys.path:                                                                   
    if 'packages' in p:                                                              
        mod_path = p                                                                 
mod_path = mod_path + "/pfla"  

It will not work in the package is installed in developer mode (pip install -e .)

You need to use something like dirname(__file__) to get the current path and relatively find the testing data.

JOSS - Fix DOIs

Can you fix the missing dois for some references in the software paper. I think Psychometrika and JRSSB references are missing DOIs.

Example in the documentation

While there is the section Usage in the README, I cannot see it on the documentation (website).
Could you duplicate this is entry in the Installation and usage page.

JOSS - release version

The version mentioned in JOSS is 0.1.4. However, I think that the PiPy is now 0.1.6. You should probably update something in the submission in JOSS.
Also, you will need to create a GitHub release.

Might want to not use the Lena image

See discussion here: scikit-image/scikit-image#1855

JOSS - Improve example usage

Currently the README provides the following usage example
https://github.com/maxrousseau/pfla#usage

However, it doesn't clearly show how the data/images need to be organized in order for this to work. Is there an example dataset that comes with the package? If so, can you modify the usage example to clearly explain

• How the input data is expected to be organized using your example dataset
• Incorporate the example dataset into the usage example

JOSS - Large file location

It is user unfriendly to ask to copy some specific data which moreover would be placed at different location depending of the system and the way the package is installed.

A solution for this is to write a fetcher which will fetch the data from a location (you can use zenodo to host the data for instance) and download the data to a package home folder.

For instance, scikit-learn create by default a ~/scikit_learn_data which can be set to another location by the user as well. It will make the package more flexible. For instance, you can refer to:
https://github.com/scikit-learn/scikit-learn/blob/master/sklearn/datasets/california_housing.py