How_to_use_the_kata.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to use the kata\n",
    "\n",
    "**kata** is a Japanese word meaning 'form'. In martial arts like karate, _kata_ are training exercises. Software engineers have adapted the idea into coding challenges. We have written some geocomputing-flavoured _kata_ for you to try.\n",
    "\n",
    "_Kata_ also happens to mean 'down' in Greek (e.g. as in 'katabatic wind'), so it's especially appropriate for geoscience :)\n",
    "\n",
    "Use the same `geocomp` environment we set up in the class. (If you need to install the `requests` library, you can do that with `pip install requests`.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting the exercise\n",
    "\n",
    "To receive the challenge, get your input data, and give your responses, you will be communicating with a [web API](https://en.wikipedia.org/wiki/Web_API). The API is being served at the URL `https://kata.geosci.ai`\n",
    "\n",
    "We can read this week's question from the **challenge** 'endpoint' at `https://kata.geosci.ai/challenge`. This is expecting you to ask for a resource (the challenge name). For week one, the challenge is called **sequence** so we'll go to `https://kata.geosci.ai/challenge/sequence`.\n",
    "\n",
    "You can paste that URL into a browser to read the challange, but we can do it right from Python."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "\n",
    "url = 'https://kata.geosci.ai/challenge/sequence'  # <--- In week 2, you'll change the name.\n",
    "\n",
    "r = requests.get(url)\n",
    "r.status_code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What comes back is a string:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r.text"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The text is written in [Markdown](https://daringfireball.net/projects/markdown/syntax), a markup language for formatting plain text. We can use IPython's display module to render it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import Markdown\n",
    "\n",
    "Markdown(r.text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----\n",
    "## About those questions\n",
    "\n",
    "In general, question 1 should be prety approachable for all learners. It shouldn't take more than a few lines of code to solve &mdash; and you can probably do it in one!\n",
    "\n",
    "Question 2 should be solvable by most beginners, but it will take a bit more work. It probably needs at least a few lines of code. It will probably involve more than one data structure. You might need loops or NumPy, depending on the type of problem.\n",
    "\n",
    "Question 3 is supposed to be a bit tricky. It should be solvable by beginners, but it might take you an hour or two.\n",
    "\n",
    "----\n",
    "## Getting your input\n",
    "\n",
    "When you think you've figured out how to solve the problem, or at least have a go at Question 1, you'll need some unique input that's only for you, so we need to pass some information to the server.\n",
    "\n",
    "Choose a value for `'key'` &mdash; it can be any string, like your name, or your favourite word. It is not stored on the server or interpreted in any way, it's just a string that acts as a unique identifier. It ensures that you will probably get your own input, unlike anyone else's."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_key = \"honey badger\"\n",
    "\n",
    "params = {'key': my_key}\n",
    "\n",
    "r = requests.get(url, params)\n",
    "\n",
    "r.text"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This input will be the same for all of the questions.\n",
    "\n",
    "You can now attempt to answer the questions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----\n",
    "## Giving your answer\n",
    "\n",
    "Running your solution on your unique input gives you an answer. You can give this answer to the server and it will tell you if you are correct or not:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = {'key': my_key,   # <--- must be the same key as before\n",
    "          'question': 1,   # <--- which question you're answering\n",
    "          'answer': 1234,  # <--- your answer to that question\n",
    "         }\n",
    "\n",
    "r = requests.get(url, params)\n",
    "\n",
    "r.text"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The answer `1234` for Question 1 was not right. Back to the drawing board!\n",
    "\n",
    "When you move on to Question 2, you'll use the same input as before, but you will submit your answer like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = {'key': my_key,\n",
    "          'question': 2,   # <--- now it's question 2\n",
    "          'answer': 9876,  # <--- your answer to question 2\n",
    "         }\n",
    "\n",
    "r = requests.get(url, params)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----\n",
    "\n",
    "## Tips\n",
    "\n",
    "- Try to write functions to solve the problems. You often need to build on what you did in previous questions, and re-using code like this is much easier if you use functions.\n",
    "- Before answering most of the questions, you'll probably need to convert the data you are given, which is one long string, into something more digestible. For example, you might want to convert a bunch of filenames into a list of strings. Sometimes, a dictionary representation might help.\n",
    "- The questions are solvable with pure Python code, but it might sometimes help to use other libraries. If the other libraries are _really_ helpful, we'll let you know about them in the question. If you want to use Pandas or NumPy, that's definitely fine &mdash; and some questions will be easier if you do.\n",
    "- Do chat with others on [Software Underground](https://www.softwareunderground.org/) if you get stuck.\n",
    "- We'll be sending example solutions as we unlock new puzzles each week.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----\n",
    "© 2020 Agile Scientific &mdash; Code: openly licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) &mdash; Text: all rights reserved."
   ]
  }
 ],
 "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.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}