XMLCorpus.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# XMLCorpus\n",
    "Una herramienta personalizada para analizar datos\n",
    "contenidos en ficheros `xml`.\n",
    "\n",
    "La ejecución se realiza sobre un [Jupyter Notebook](https://jupyter.org/),\n",
    "un sistema de ejecución que permite integrar las\n",
    "herramientas necesarias para que el sistema funcione\n",
    "sin mayor complejidad.\n",
    "\n",
    "## Estructura del `XML`\n",
    "Siguiendo de ejemplo el fichero `xml` provisto,\n",
    "este programa está especialmente diseñado para funcionar\n",
    "con la siguiente estructura:\n",
    "\n",
    "```xml\n",
    "<!-- Notation:\n",
    "    x, y: mandatory values\n",
    "    o: optional values\n",
    "-->\n",
    "<propiel>\n",
    "    <annotation>\n",
    "        <!-- Optional -->\n",
    "        <parts-of-speech>\n",
    "            <value tag=\"x\" summary=\"y\" />\n",
    "                        ...\n",
    "        </parts-of-speech>\n",
    "        <!-- Mandatory -->\n",
    "        <morphology>\n",
    "            <field tag=\"x\">\n",
    "                <value tag=\"x\" summary=\"y\" />\n",
    "                            ...\n",
    "            </field>\n",
    "            ...\n",
    "        </morphology>\n",
    "        <!-- Optional -->\n",
    "        <gloss>\n",
    "            <value tag=\"x\" summary=\"y\" />\n",
    "        </gloss>\n",
    "    </annotation>\n",
    "\n",
    "    <source id=\"x\" alignment-id=\"o\" language=\"y\">\n",
    "        <!-- All these fields are optional -->\n",
    "        <title></title>\n",
    "        <citation-part></citation-part>\n",
    "        <editorial-note></editorial-note>\n",
    "        <annotator></annotator>\n",
    "        <reviewer></reviewer>\n",
    "        <electronic-text-original-url></electronic-text-original-url>\n",
    "        <!-- Source main section -->\n",
    "        <div>\n",
    "            <title>Actually unused</title>\n",
    "            <sentence id=\"x\" alignment-id=\"o\" status=\"[annotated, unannotated, reviewed]\">\n",
    "                <token id=\"x\" form=\"y\" alignment-id=\"o\" lemma=\"o\" part-of-speech=\"o\" morphology=\"o\" gloss=\"o\" />\n",
    "                ...\n",
    "            </sentence>\n",
    "            ...\n",
    "        </div>\n",
    "    </source>\n",
    "    ...\n",
    "</propiel>\n",
    "```\n",
    "## Ejecución de las celdas\n",
    "Las celdas que contienen texto y/o código se pueden\n",
    "ejecutar. Esto permite, por ejemplo, que se pueda\n",
    "cambiar este texto y que se muestre actualizado así\n",
    "como ejecutar código en particular.\n",
    "\n",
    "Para ejecutar una celda, existen dos opciones:\n",
    " + Con la celda seleccionada, pulsar el botón\n",
    "   `Run` que aparece en la barra de opciones.\n",
    "\n",
    " + Con la celda seleccionada, pulsar <kbd>⇧ Shift</kbd> + <kbd>↵ Enter</kbd>.\n",
    "\n",
    "Cualquiera de las dos opciones anteriores es perfectamente\n",
    "válida para ejecutar una celda.\n",
    "\n",
    "## Instalación de requisitos\n",
    "Para que la aplicación funcione correctamente, es\n",
    "necesario instalar las siguientes dependencias:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    },
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "pip install -r requirements.txt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "## Carga de los datos\n",
    "Para poder evaluar distintos ficheros `XML` se ofrece\n",
    "un sistema de carga que permite o bien trabajar con\n",
    "una URL o bien con un fichero `XML` en sí.\n",
    "\n",
    "En el *widget* que aparece justo debajo tienes la opción\n",
    "de subir un fichero o trabajar con una URL. Ten en cuenta\n",
    "que, si pones una URL, esta tendrá prioridad sobre el\n",
    "fichero."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    },
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "from xmlcjupyter import init, show_widgets, load_source, annotations_widget\n",
    "\n",
    "init()\n",
    "uploader, url = show_widgets()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "Además, se puede trabajar con dos ficheros `XML` por\n",
    "separado: un primer fichero que contenga únicamente\n",
    "las anotaciones y el segundo que contenga ya las\n",
    "fuentes. En este caso, se marcaría la casilla\n",
    "y se especificaría la ubicación de dicho fichero."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    },
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "use_annotations, file_data = annotations_widget()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    },
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "annotations_tree, tree = load_source(uploader, url, use_annotations, file_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Procesado de los datos\n",
    "Ahora el fichero `XML` está ya cargado y listo\n",
    "para ser utilizado. El objeto `tree` contiene todos los\n",
    "valores del mismo, pero ahora es necesario hacer que\n",
    "el programa lo entienda.\n",
    "\n",
    "La función\n",
    "```python\n",
    "def parse_tree(tree, annotations) -> Dict[SourceID, Source]\n",
    "```\n",
    "identifica, dentro del árbol `XML`, las distintas\n",
    "fuentes (`<source>`) que lo componen y genera un mapa\n",
    "con distintas claves y valores. La clave consta\n",
    "del identificador de una fuente (por ejemplo, `text1`)\n",
    "y el valor es la fuente en sí, con todas las oraciones,\n",
    "*tokens* y demás valores pertinentes.\n",
    "\n",
    "Para ello, primero se han de cargar las anotaciones en\n",
    "sí. Para ello, se usa la siguiente función:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    },
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "from xmlcjupyter import load_annotations\n",
    "\n",
    "annotations = load_annotations(annotations_tree)\n",
    "\n",
    "# Show the identified annotations\n",
    "print(annotations)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "Después, ya se pueden obtener las fuentes:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    },
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "from xmlcjupyter import parse_tree\n",
    "\n",
    "sources = parse_tree(tree, annotations)\n",
    "\n",
    "# Show the identified sources\n",
    "print(\"Identified sources:\", end=' {')\n",
    "for key in sources.keys():\n",
    "    print(key, end=', ')\n",
    "print(\"}\\nAccess them by writting: 'sources['sourceID']'\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "## Operaciones con las fuentes\n",
    "Ahora que ya están las fuentes listas para trabajar con\n",
    "ellas, se pueden realizar las siguientes operaciones:\n",
    "\n",
    " + Mostrar el contenido de las fuentes como tabla.\n",
    " Para ello, se cuenta con el método\n",
    " ```python\n",
    " def display_source(source, tabletype=\"latex\")\n",
    " ```\n",
    " el cual muestra el contenido de la fuente o de todas\n",
    " las fuentes, en caso de usar `sources` como parámetro.\n",
    "\n",
    " + Comparar el contenido de dos fuentes, mediante\n",
    " el método\n",
    " ```python\n",
    " def compare(source, another_source, sentences=(), status=None, tabletype=\"latex\")\n",
    " ```\n",
    " el cual mostrará en una tabla las oraciones junto con\n",
    " sus *token*s anotados y las relaciones entre ellos.\n",
    "\n",
    " + Buscar dentro de una fuente según ciertas\n",
    " características. Por ejemplo, si se quiere buscar\n",
    " por todos los *token*s en primera persona del singular,\n",
    " o si son adjetivos, etc. Para ello, se cuenta con\n",
    " el método:\n",
    " ```python\n",
    " def find_words_by(data, source, tabletype=\"latex\")\n",
    " ```\n",
    "\n",
    "Como se puede ver, los métodos reciben un parámetro\n",
    "adicional `tabletype` que por defecto está con un\n",
    "valor \"latex\". Esto permite cambiar cómo se muestran\n",
    "las tablas y si se quiere otro formato (hay una lista\n",
    "con todos los formatos disponible en https://github.com/astanin/python-tabulate#table-format).\n",
    "\n",
    "A continuación, a modo explicativo, se muestran ejemplos\n",
    "de cómo usar las funciones anteriores:\n",
    "\n",
    "### Mostrar todas las fuentes con sus datos\n",
    "```python\n",
    "display_source(sources)\n",
    "```\n",
    "\n",
    "### Mostrar los datos de una fuente con ID `text1`\n",
    "```python\n",
    "display_source(sources['text1'])\n",
    "```\n",
    "\n",
    "### Mostrar los datos de una fuente con otro formato de tabla\n",
    "```python\n",
    "display_source(sources['text2'], tabletype=\"grid\")\n",
    "```\n",
    "\n",
    "### Comparar `text1` con `text2`\n",
    "```python\n",
    "compare(sources['text1'], sources['text2'])\n",
    "```\n",
    "\n",
    "### Comparar `text1` con `text2` las oraciones '0a' y '1a'\n",
    "```python\n",
    "compare(sources['text1'], sources['text2'], sentences=('0a', '1a'))\n",
    "```\n",
    "\n",
    "### Comparar `text1` con `text2` aquellas oraciones que estén anotadas\n",
    "```python\n",
    "compare(sources['text1'], sources['text2'], status=AnnotationStatus.ANNOTATED)\n",
    "```\n",
    "\n",
    "### Buscar palabras según distintos campos\n",
    "```python\n",
    "source = sources['text1']\n",
    "\n",
    "# Find all first person tokens in text1\n",
    "find_words_by({\n",
    "    AnnotationsElements.Morphology: 'person.1'\n",
    "}, source)\n",
    "\n",
    "# Find all first person singular masculine tokens in text1\n",
    "find_words_by({\n",
    "    AnnotationsElements.Morphology: {'person.1', 'number.s', 'gender.m'}\n",
    "}, source)\n",
    "\n",
    "# Find all first person singular adjectives\n",
    "find_words_by({\n",
    "    AnnotationElements.Morphology: {'person.1', 'number.s'},\n",
    "    AnnotationElements.PartsOfSpeech: 'A-'\n",
    "}, source)\n",
    "\n",
    "# Find all words literally translated from Latin (in example)\n",
    "find_words_by({\n",
    "    AnnotationElements.Gloss: 'l'\n",
    "}, sources['text2'])\n",
    "\n",
    "# Find all positive words in all sources\n",
    "find_words_by({\n",
    "    AnnotationElements.Morphology: 'degree.p'\n",
    "}, sources)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "## Declaración de las cabezeras de las funciones\n",
    "A continuación, se declaran las cabeceras de las\n",
    "funciones anteriores"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    },
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "from xmlcjupyter import (\n",
    "    display_source,\n",
    "    compare,\n",
    "    find_words_by\n",
    ")\n",
    "from xmlc import AnnotationStatus, AnnotationElements"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "## Código de prueba (funcional con `lindgos.xml`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    },
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "# Print all sources\n",
    "display_source(sources, tabletype=\"fancy_grid\")\n",
    "\n",
    "print('Comparing text1 with text2 (all sentences):', end='\\n\\n')\n",
    "# Compare all sentences\n",
    "compare(sources['text1'], sources['text2'], tabletype=\"fancy_grid\")\n",
    "\n",
    "print('Comparing text1 with text2 (reviewed sentences):', end='\\n\\n')\n",
    "# Compare all reviewed sentences\n",
    "compare(sources['text1'], sources['text2'], status=AnnotationStatus.REVIEWED, tabletype=\"fancy_grid\")\n",
    "\n",
    "print('All first person words in text1:', end='\\n\\n')\n",
    "# Find all first person words\n",
    "find_words_by({\n",
    "    AnnotationElements.Morphology: 'person.1'\n",
    "}, sources['text1'], tabletype=\"fancy_grid\")\n",
    "\n",
    "print('All common nouns:', end='\\n\\n')\n",
    "# Find all common nouns\n",
    "find_words_by({\n",
    "    AnnotationElements.PartsOfSpeech: 'Nb'\n",
    "}, sources, tabletype=\"fancy_grid\")\n",
    "\n",
    "print('All first person singular masculine words in text1:', end='\\n\\n')\n",
    "# Find all first person singular masculine words\n",
    "find_words_by({\n",
    "    AnnotationElements.Morphology: {'person.1', 'number.s', 'gender.m'}\n",
    "}, sources['text1'], tabletype=\"fancy_grid\")\n",
    "\n",
    "print('All literal translated words:', end='\\n\\n')\n",
    "# Find all literal translated words\n",
    "find_words_by({\n",
    "    AnnotationElements.Gloss: 'l'\n",
    "}, sources['text2'], tabletype=\"fancy_grid\")\n",
    "\n",
    "print('All unassigned words:', end='\\n\\n')\n",
    "# Find all unassigned words\n",
    "find_words_by({\n",
    "    AnnotationElements.PartsOfSpeech: 'X-'\n",
    "}, sources, tabletype=\"fancy_grid\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    },
    "scrolled": true
   },
   "source": [
    "## Código fuente\n",
    "El código fuente de la aplicación al completo se\n",
    "encuentra en: https://github.com/Javinator9889/XMLCorpus\n",
    "\n",
    "Ahí se puede ver cómo está diseñado y qué opciones\n",
    "ofrece, junto con la documentación de cada una de las\n",
    "funciones que lo componen.\n",
    "\n",
    "## Descarga de las salidas\n",
    "Al estar trabajando sobre este entorno, todas las\n",
    "salidas se guardan y pueden ser descargadas\n",
    "posteriormente. Además, a continuación puedes seguir\n",
    "creando más celdas para seguir trabajando, y una vez\n",
    "acabado, descargar el resultado o ver cómo queda.\n",
    "\n",
    "## $\\LaTeX$\n",
    "Actualmente, por comodidad, las tablas se muestran\n",
    "en el formato \"*fancy_grid*\", pero pueden ser exportadas\n",
    "fácilmente a $\\LaTeX$ para usarlas posteriormente. Para\n",
    "ello, en los comandos anteriores, bastaría con quitar\n",
    "el campo \"*tabletype*\", ya que su valor por defecto\n",
    "es $\\LaTeX$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "# Esta celda es para ti 😉\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}