Merge pull request #40 from ccb-hms/development

Merge v4.0.0 Release Candidate changes to main

.readthedocs.yaml

@@ -17,7 +17,7 @@ build:
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
-   configuration: docs/conf.py
+   configuration: docs/source/conf.py
 
 # Optionally build your docs in additional formats such as PDF and ePub
 # formats:

README-UI.md

@@ -0,0 +1,90 @@
+# ontology-mapper-ui
+The following information pertains to the text2term UI, which is written [here](https://github.com/ccb-hms/ontology-mapper-ui) and runs online [here](https://text2term.hms.harvard.edu/). It supports fewer features than the base package does, but provides a user interface for non-programmers.
+
+### Running Locally via Node + Python
+
+##### Requirements
+
+-   Node >= 16.0.0
+-   npm >= 8.0.0
+-   Python >= 3.9.0
+-   pip >= 21.0.0
+-   text2term >= 1.1.0
+
+**\*** These are the versions I have that work; while I know Python 3.9 or higher is necessary, the others may not strictly require the listed versions.
+
+**\*\*** If you are running this locally on Google Chrome, you will likely run into issues with CORS (Cross-Origin Requests) that I have been unable to completely resolve. I would recommend using a different browser, using the Docker method, or finding some way to disable CORS on Chrome while running this.
+
+#### Instructions
+
+##### Initial Setup
+
+When first cloned, run the command:
+
+
+```
+npm install
+```
+
+to install all necessary packages for the React frontend.
+
+Next, go into the `flask-api` folder (perhaps by running `cd flask-api`) and run
+
+```
+pip install -r requirements-flask.txt
+```
+
+to install necessary packages for the Flask api.
+
+##### Running
+
+To run, make sure you are in the root of the repository and run, in two separate command line instances, the command
+
+```
+npm start
+```
+
+to start the front-end, which can be seen at `localhost:3000`, and the command
+
+```
+npm run flask-api
+```
+
+to start the back-end, which can be interacted with at `localhost:5000`.
+
+### Running Locally via Docker
+
+#### Requirements
+
+-   Docker
+
+#### Instructions
+
+##### Initial Setup
+
+Before running, make sure you have the latest version of the repository built by running the command
+
+```
+docker-compose build
+```
+
+Docker should build two images:
+
+-   `ontology-mapper-api`: the Flask backend API
+-   `ontology-mapper-client`: the React frontend
+
+##### Running
+
+To run the website, run the command:
+
+```
+docker-compose up
+```
+
+Docker should build two containers corresponding to the two images.
+
+In a browser, navigate to `localhost:8602` to see the front-end.
+
+### Acknowledgements
+
+Initial setup of React and Flask and Dockerization aided by an [article series](https://blog.miguelgrinberg.com/post/how-to-dockerize-a-react-flask-project) by Miguel Grinberg.

README.md

@@ -65,22 +65,22 @@ text2term.map_terms(source_terms,
                    save_mappings=False, 
                    separator=',', 
                    use_cache=False,
-                   term_type='classes',
+                   term_type=OntologyTermType.CLASS,
                    incl_unmapped=False)
 
 ```
 NOTE: As of 3.0.0, the former three functions (`map_file`, `map_terms`, `map_tagged_terms`) have been condensed into one function. Users can now change the name of any function in old code to `map_terms` and it reads the input context to maintain the functionality of each one.
 
 ### Arguments
-For `map_terms`, the first argument can be any of the following: 1) a string that specifies a path to a file containing the terms to be mapped, 2) a list of the terms to be mapped, or 3)dictionary of terms to a list of tags, or a list of TaggedTerm objects (see below). 
+For `map_terms`, the first argument can be any of the following: 1) a string that specifies a path to a file containing the terms to be mapped, 2) a list of the terms to be mapped, or 3) a dictionary where the keys are the terms to be mapped, and values can be a list of tags or a list of TaggedTerm objects (see below). 
 Currently, the tags do not affect the mapping in any way, but they are added to the output dataframe at the end of the process. The exception is the Ignore tag, which causes the term to not be mapped at all, but still be outputted in the results if the incl_unmapped argument is True (see below).
 
 All other arguments are the same, and have the same functionality:
 
 `target_ontology` : str
-    Path or URL of 'target' ontology to map the source terms to. When the chosen mapper is BioPortal or Zooma,
-    provide a comma-separated list of ontology acronyms (eg 'EFO,HPO') or write 'all' to search all ontologies
-    As of version 2.3.0, passing a recognized acronym to `target_ontology` will generate the download link automatically. This is done using the `bioregistry` python package.
+    Path or URL or acronym of 'target' ontology to map the source terms to. When the chosen mapper is BioPortal or Zooma,
+    provide a comma-separated list of ontology acronyms (eg 'EFO,HPO') or write 'all' to search all ontologies. When the target ontology has been previously cached, provide the ontology name that was used to cache it.
+    As of version 2.3.0, it is possible to specify ontology acronyms as the `target_ontology` (eg "EFO" or "CL"), which is achieved using [bioregistry](https://bioregistry.io) to retrieve URLs for those acronyms.
 
 `base_iris` : tuple
     Map only to ontology terms whose IRIs start with one of the strings given in this tuple, for example:
@@ -116,16 +116,16 @@ All other arguments are the same, and have the same functionality:
     Save the generated mappings to a file (specified by `output_file`) 
 
 `seperator` : str
-    Character that seperates the source term values if a file input is given. Ignored if the input is not a file path.
+    Character that separates the source term values if a file input is given. Ignored if the input is not a file path.
 
 `use_cache` : bool
     Use the cache for the ontology. More details are below.
 
-`term_type` : str
-    Determines whether the ontology should be parsed for its classes (ThingClass), properties (PropertyClass), or both. Possible values are ['classes', 'properties', 'both']. If it does not match one of these values, the program will throw a ValueError.
+`term_type` : term.OntologyTermType
+    Specifies whether to map to ontology classes, properties or any of the two. Possible values are ['class', 'property', 'any'].
 
 `incl_unmapped` : bool
-    Include all unmapped terms in the output. If something has been tagged Ignore (see below) or falls below the `min_score` threshold, it is included without a mapped term at the end of the output. 
+    Include all unmapped terms in the output. If something has been tagged 'Ignore' (see below) or falls below the `min_score` threshold, it is included without a mapped term at the end of the output data frame. 
 
 All default values, if they exist, can be seen above.
 

docs/conf.py → docs/source/conf.py

@@ -23,5 +23,6 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
+html_theme = 'pyramid'
 html_static_path = ['_static']
+html_logo = "ccb_logo.jpg"

docs/index.rst → docs/source/index.rst

@@ -3,18 +3,26 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to text2term's documentation!
+.. .. image:: ccb_logo.jpg
+..    :alt: CCB's Logo
+..    :scale: 50 %
+..    :align: left
+
+Text2term
 =====================================
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+.. include:: ../../README-UI.md
+   :parser: myst_parser.sphinx_
 
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
+
+

requirements.txt

@@ -5,7 +5,7 @@ numpy~=1.24.2
 gensim~=4.3.0
 scipy~=1.10.1
 scikit-learn~=1.2.1
-setuptools~=67.6.0
+setuptools~=68.2.2
 requests~=2.31.0
 tqdm~=4.66.1
 sparse_dot_topn~=0.3.4