#!/usr/bin/env python
# coding: utf-8

# # Loading Text-Fabric (Nestle1904GBI)
# 
# **Work in progress**

# ## Table of content <a class="anchor" id="TOC"></a>
# * <a href="#bullet1">1 - Introduction</a>
#     * <a href="#bullet1x1">1.1 - Text-Fabric data versions</a>
# * <a href="#bullet2">2 - Preparation / installation</a>
#     * <a href="#bullet2x1">2.1 - Install Python</a>
#     * <a href="#bullet2x2">2.2 - Install Text-Fabric</a>
#     * <a href="#bullet2x3">2.3 - Raise rate limit on Github</a>
# * <a href="#bullet3">3 - Load Text-Fabric into memory</a>
#     * <a href="#bullet3x1">3.1 - Load the code</a>
#     * <a href="#bullet3x2">3.2 - Load the app and data</a>
#     * <a href="#bullet3x3">3.3 - Load the style sheets</a>
# * <a href="#bullet4">4 - Add additional features</a>
#     * <a href="#bullet4x1">4.1 - The official method</a>
#     * <a href="#bullet4x2">4.2 - The unofficial method</a>
#     * <a href="#bullet4x3">4.3 - Additional dataset</a>
#     * <a href="#bullet4x4">4.4 - Further reference</a>
# * <a href="#bullet5">5 - Using multiple Text-Fabric corpora</a>

# # 1 - Introduction <a class="anchor" id="bullet1"></a>
# ##### [back to TOC](#TOC)
# 
# Basic instructions on loading the Text-Fabric and start using it on your system. It will provide examples of the various ways you can invoke Text-Fabric.

# ### 1.1 - Text-Fabric data versions <a class="anchor" id="bullet1x1"></a>
# 
# Some discussion related to versions

# ## 2 - Preparation / installation<a class="anchor" id="bullet2"></a>
# ##### [back to TOC](#TOC)
# 
# The instructions in this section are only required once to be executed. This will result in the Text-Fabric code being available for loading into memory of your system.

# ### 2.1 - Install Python <a class="anchor" id="bullet2x1"></a>
# 
# You need to have Python on your system. Most systems have it out of the box,but alas, that is python2 and we need at least python **3.6**.
# 
# Install it from [python.org](https://www.python.org) or from
# [Anaconda](https://www.anaconda.com/products/distribution).

# ### 2.2 - Install Text-Fabric <a class="anchor" id="bullet2x2"></a>
# 
# (if not yet installed) 
#  
# **TF itself**
# 
#     pip3 install text-fabric
#     
# **When using Jupyter notebook**
# 
# You need [Jupyter](http://jupyter.org) or a platform like [Anaconda](https://www.anaconda.com/products/distribution) which includes Jupyter.
# 
# If it is not already installed:
# 
#     pip3 install jupyter
# 

# ### 2.3 - Raise rate limit on Github <a class="anchor" id="bullet2x3"></a>
# ##### [back to TOC](#TOC)
# 
# It may be required to increase rate limit for GitHub. [See instructions](https://annotation.github.io/text-fabric/tf/advanced/repo.html#increase-the-rate-limit) on aquiring and setting the GHPERS variable. 
# See [here](https://www.howtogeek.com/789660/how-to-use-windows-cmd-environment-variables/#autotoc_anchor_2) if you want to set the varibale on windows using the command prompt.

# ## 3 - Load Text-Fabric into memory <a class="anchor" id="bullet3"></a>
# ##### [back to TOC](#TOC)
# 
# The instructions in this section are  required once to be executed each time you want to use Text_Fabric. It will load the Text-Fabric code and data into memory.

# ### 3.1 - Load the code <a class="anchor" id="bullet3x1"></a>
# ##### [back to TOC](#TOC)

# In[1]:


get_ipython().run_line_magic('load_ext', 'autoreload')
get_ipython().run_line_magic('autoreload', '2')


# In[1]:


# Loading the Text-Fabric code
# Note: it is assumed Text-Fabric is installed in your environment
from tf.fabric import Fabric
from tf.app import use


# ### 3.2 - Load app and data <a class="anchor" id="bullet3x2"></a>
# ##### [back to TOC](#TOC)
# 
# The following invocation of function [`use`](https://annotation.github.io/text-fabric/tf/about/usefunc.html) loads all features of the corpus (and extra modules, see <a href="#bullet4">section 4</a>). It creates an variable (in this example `N1904GBI`) with its associated methods and function, the 'Advanced API'. In the 'cheat sheet' there are many references to `A.*something*`. In this notebook they should be read as `N1904GBI`. 

# In[2]:


# load the app and data
N1904GBI = use ("tonyjurg/Nestle1904GBI", version="0.4", hoist=globals())


# ### 3.3 - Load the style sheets<a class="anchor" id="bullet3x3"></a>
# ##### [back to TOC](#TOC)
# 
# This step is stricly speaking not required when using Text-Fabric only localy. However, when making it available for tools like nbviewer, including this statement will show very handy since it ensures proper formatting. It is using function [`getCss`](https://annotation.github.io/text-fabric/tf/advanced/display.html#tf.advanced.display.getCss) to obtain all style information and uses function [`dh`](https://annotation.github.io/text-fabric/tf/advanced/helpers.html#tf.advanced.helpers.dh) to push it as HTML towards the Jupyter NoteBook.

# In[4]:


# The following will push the Text-Fabric stylesheet to this notebook (to facilitate proper display with notebook viewer)
N1904GBI.dh(N1904GBI.getCss())


# # 4 - Add additional features<a class="anchor" id="bullet4"></a>
# ##### [back to TOC](#TOC)
# 
# 
# **The following is optional.**
# 

# ## 4.1 - The official method<a class="anchor" id="bullet4x1"></a>
# ##### [back to TOC](#TOC)
# 
# Still to be done: find good example

# In[6]:


# load the app and data with ad
N1904GBIMOD = use ("tonyjurg/Nestle1904GBI", version="0.4", mod=f"annotation/banks/sim/tf" hoist=globals())


# ## 4.2 - The unofficial method<a class="anchor" id="bullet4x2"></a>
# ##### [back to TOC](#TOC)
# 
# Warning: to use this method it is critical to verify that **ALL** the following match:
# * most importantly, the Text-Fabric dataset should be based upon the same corpus (in the most literal sense of the word!)
# * the node range(s) (check output of command `F.otype.all` or values found in file `otype.tf`).
# * the slot order (i.e. the order of the wordsin the Text-Fabric corpus; usualy refered to as monad).
# 
# If these conditions are met, it is possible to copy the .tf files from the donor dataset to your local Text-Fabric directory..

# ## 4.3 - Additional dataset<a class="anchor" id="bullet4x3"></a>
# ##### [back to TOC](#TOC)
# 
# Some additional dataset that should work with this Text-Fabric implementation are:
# 
# Dataset location | additions
# --- | ---
# [CenterBLC](https://github.com/CenterBLC/NA/tree/main/tf/202201) | *additional grammatical features, Bible Online Learner details*
#     

# ## 4.4 - Further reference<a class="anchor" id="bullet4x4"></a>
# ##### [back to TOC](#TOC)

# Further reference [module tf.about.datasharing](https://annotation.github.io/text-fabric/tf/about/datasharing.html)

# # 5 - Using multiple Text-Fabric corpora<a class="anchor" id="bullet5"></a>
# ##### [back to TOC](#TOC)
# 
# When using multiple Text-Fabric corpora there are a few things to take care of.
# The most important are to invocate function [`use`](https://annotation.github.io/text-fabric/tf/about/usefunc.html) twice using a different variables (name) to create two Advanced API's. In the following example two `A` (Advanced API) objects are created named CORPUS1 and CORPUS2:
# 

# In[ ]:


CORPUS1 = use ()
CORPUS2 = use ()


# **IMPORTANT:** When working with multiple corpora, do not add 'hoist=globals()' to the invocation!. See the comments on [section hoist of function use](https://annotation.github.io/text-fabric/tf/about/usefunc.html#hoisting).