Merge pull request #25 from statonlab/v1.2_docs

V1.2 docs

.github/ISSUE_TEMPLATE.md

@@ -1,29 +1,9 @@
 <!--
-  PLEASE DON'T DELETE THIS TEMPLATE UNTIL YOU HAVE READ THE FIRST SECTION.
+Thanks for your interest in Tripal Alchemist!
+If you are filing a bug report or seeking help, please fill out the below template. Otherwise, feel free to delete the template.
 -->
 
-### Issue Type
-
-<!--
-Please choose one of the below options.
-Please name your issue so that your choice is included in brackets at hte beginning.
-For example, a bug report would be [bug]-Chado properties give me an sql error
-IF FILING A BUG REPORT, PLEASE FILL OUT THE ENTIRE TEMPLATE.
---->
-* Bug Report [bug]  
-* Question [question]
-* Discussion [discussion]
-* Feature Request [request]
-
 ## Bug report info
-### Environment
-
-<!--
-The more information you include here, the easier it will be for us to help.
--->
-* PHP version - 
-* Tripal version - 
-* Postgres version - 
 
 ### Steps to Reproduce
 
@@ -38,24 +18,7 @@ The more information you include here, the easier it will be for us to help.
 2.
 3.
 
-### Expected Behavior
-
+### Behavior
 <!--
-  How did you expect your code or site to behave?
-  It’s fine if you’re not sure your understanding is correct.
-  Just write down what you thought would happen.
--->
-
-(Write what you thought would happen.)
-
-### Actual Behavior and output
-
-<!--
-  Did something go wrong?
-  Is there an error message?
-  Is something broken, or not behaving as you expected?
-  Describe this section in detail, and attach screenshots if possible.
-  Don't just say "it doesn't work"!
--->
-
-(Write what happened. Add screenshots!)
+  Please describe the problem.  Screenshots and error messages are very helpful.
+  -->

README.md

@@ -1,14 +1,13 @@
-Tripal Alchemist allows you to **transmute** (convert) entities from one type to another.
+Tripal Alchemist allows you to **transform**  entities from one type to another.
+
 
 ![Tripal Alchemist Hearthstone Card](docs/img/Tripal_Alchemist_hearthstone_logo.png)
 
 ## Background 
 
 Tripal 3 provides migrations for most base Chado content types.  Some content types (namely Analysis) convert all nodes to a single bundle type.  This is not great if you make heavy use of submodules that define their own node type: in the case of analysis, this includes analysis_expression, analysis_unigene, etc.  You also might decide later down the road that you want to redefine some of your `mrna` features as `mrna_contig`, for example.
 
-In both cases, Tripal Alchemist provides a simple interface to easily convert entities from one bundle to another, provided that the destination bundle exists, has the same base table as the source bundle, and the destination bundle was defined with the `type column` and `property value` properly set.
-
-This module is under active development, and is released as v0.1.
+This module is under active development, and is released as v0.2.
 
 ## Features
 
@@ -17,19 +16,61 @@ This module is under active development, and is released as v0.1.
 * Trying to convert a large but specific subset of entities?  Create a collection, then convert the entities in that collection
 
 ## Usage
-**Notice:** The alchemist interface has changed: the below guide is accurate for **Automatic** conversion.  **Manual** conversion is a new feature which allows you to manually select which entities to convert, regardless of their existing properties.  The guide will be updated to reflect this for the v0.2 release.
-
 
 * Define a destination bundle that is the same base table as your source bundle.  [You can follow this guide to learn how to define new bundles](docs/defining_a_new_bundle.md).  
-* Navigate to the transmuter, located at `/admin/tripal/extension/tripal_alchemist`.
+* Navigate to the transformer, located at `/admin/tripal/extension/tripal_alchemist`.
+* Select a transformation type.  Alchemist currently has three modes:
+  - **Automatic**.  Only entities whose properties currently match the destination bundle will be converted.
+  - **Manual**.  A select table will allow you to pick which entities are converted, regardless of their Chado type property.
+  - **Collection**.  Use a Tripal collection to determine which entities will be converted, regardless of their Chado type property.
 * Select a source bundle.  This is the current content type, and qualifying entities from this type will be transformed.
 * Select a destination bundle.  This is what you want to turn your content into.
-* Run **Transmute**.
+* Run **Transform**.
 * You're done!
 
->![The Tripal Alchemist Transmutation form](docs/img/tripal_alchemist_screen_1.png)
+>![The Tripal Alchemist Transmutation form](docs/img/tripal_alchemist_main_menu.png)
 > The Tripal Alchemist Transmutation form.  If any entities qualify for your new bundle type from the selected bundle type, they will appear in the table at the bottom of the form.
 
+### Transmutation modes
+
+#### Automatic
+
+Automatic mode will effect **all** source entities whose chado records qualify them for the destination bundle.  This might be the case if your entity was published as a base type, and later split into multiple types.  Alternatively, you can modify the properties of select entries manually or using SQL, making them elligible for automatic transformation.
+
+#### Manual
+
+The manual transmutation mode is for quickly transforming a small subset of entities.  Unlike automatic mode, manual transformation can convert any source entity, **regardless of its Chado property**.  This means that an entity whose type qualifies it as a source bundle can be converted to the destination bundle, with its Chado type property rewritten.  Note that the select table is limited to 500 entries.  If you need to manually convert more entries, consider creating a **collection** instead.
+
+>![The Tripal Alchemist manual transformation table](docs/img/manual_transmutation.png)
+> Manual transformation.  Check the box next to an entity to transform it into the destination type.
+
+#### Collections
+
+If you are transforming a large set of entities that are not elligible for automatic transformation, you can create a collection containing those entities.  Tripal Alchemist will transform all of the entities in the collection from the **selected base entity type** to the destination type.  Like manual transformation, collections allow you to convert entities whose Chado properties don't yet match the destination bundle. 
+
+>![collection transformation](docs/img/tripal_alchemist_collections.png)
+> Transforming a collection.  Creating a collection elsewhere (IE elasticsearch) allows you to easily select the entities you want to transform.
+
+Tripal Alchemist will only display collections that contain entities from the select source bundle type.
+
+## FAQ
+
+### How do I create a destination bundle type?
+
+Please check out my [guide on defining a bundle](/docs/deining_a_new_bundle.md).
+
+### How are entities converted?
+Tripal allows multiple entities to be mapped to the same base table.  It distinguishes these via a type_id, which is stored either directly in the base table, or in a connected prop table.  
+Tripal Alchemist changes those properties for you to match the selected destination bundle.  Tripal Alchemist then migrates the entities from the sosource to the destination `Chado_bio_data` table, and updates the `Tripal_Entity` table.
+
+### Why do my source and destination bundles need the same Chado base table?
+
+Alchemist only alters the type property of the underlying Chado record.  Transforming records from one Chado table to another would be difficult or impossible, as the required fields would all be different.
+
+### Can Alchemist convert entities that are not Chado entities?
+
+No.  As of the current release, Tripal Alchemist can only convert Tripal Entities with Chado storage backends.
+
 ## License and Contributing
 
 Tripal Alchemist is open source and provided under the [GPL-3.0 license](https://github.com/statonlab/tripal_alchemist/blob/master/LICENSE).  It was created by Bradford Condon and Meg Staton from the University of Tennessee Knoxville.  Tripal Alchemist doesn't do everything I wish it did.  If you have feature requests, bug reports, or contributions, please head to the issues queue and create an issue.  If you would like to make a contribution, simply fork the repo and make a pull request from there.

includes/tripal_alchemist_converter.form.inc

@@ -17,14 +17,14 @@ function tripal_alchemist_converter_form($form, &$form_state) {
   }
 
   $form['instructions'] = [
-    '#markup' => '<p>Welcome to Tripal Alchemist. This module is designed to convert Tripal Entities from one type to another (a process called "transmutation" in classical alchemy).  Your destination bundle must already exist before transmuting.</p><p>Please note that Tripal Alchemist will only convert <b>Tripal 3 Entities</b>.  Tripal 2 content types (nodes) must be migrated.</p>
+    '#markup' => '<p>Welcome to Tripal Alchemist. This module is designed to transform Tripal Entities from one type to another (a process called "transmutation" in classical alchemy).  Your destination bundle must already exist before transforming.</p><p>Please note that Tripal Alchemist will only convert <b>Tripal 3 Entities</b>.  Tripal 2 content types (nodes) must be migrated.</p>
         <p>Full documentation of this module is available on <a href = "https://github.com/statonlab/tripal_alchemist/">the projects Github page.</a></p>
         ',
   ];
 
   $form['transmutation_type'] = [
     '#type' => 'radios',
-    '#title' => 'Transmutation Method',
+    '#title' => 'Transformation Method',
     '#description' => 'Tripal Alchemist can automatically convert all entities from a source bundle to a destination bundle, if those entities already meet the criteria for the destination bundle.  This typically means that a type_id column or property is already set.  You can instead choose to manually select entities to convert. Alternatively, you can create a collection, and convert the entities within that collection.',
     '#options' => [
       'Automatic' => 'Automatic',
@@ -164,7 +164,7 @@ function tripal_alchemist_converter_form($form, &$form_state) {
 
   $form['div2']['submit'] = [
     '#type' => 'submit',
-    '#value' => t('Transmute (Submit)'),
+    '#value' => t('Transform (Submit)'),
   ];
 
   return $form;
@@ -192,7 +192,7 @@ function tripal_alchemist_converter_form_submit($form, &$form_state) {
 
   if ($transmutation_type == 'Automatic') {
     tripal_alchemist_convert_all_entities($job_args);
-    tripal_set_message("Transmutation successful!", TRIPAL_INFO);
+    tripal_set_message("Transformation successful!", TRIPAL_INFO);
   }
   if ($transmutation_type == 'Manual') {
     $source_entities = $form_state['values']['manual_entity_select'];