Skip to content

Latest commit

 

History

History
148 lines (113 loc) · 7.88 KB

getting-started.md

File metadata and controls

148 lines (113 loc) · 7.88 KB
Raw
copyright lastupdated
years
2015, 2017
2017-04-20

{:curl: #curl .ph data-hd-programlang='curl'} {:javascript: #javascript .ph data-hd-programlang='javascript'} {:java: #java .ph data-hd-programlang='java'} {:python: #python .ph data-hd-programlang='python'} {:swift: data-hd-programlang='swift'} {:new_wind{:new_window: target="_blank"} {:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:codeblock: .codeblock} {:download: .download} {:tip: .tip}

Getting started tutorial

{: #natural-language-classifier}

The {{site.data.keyword.nlclassifierfull}} service can help your application understand the language of short texts, and make predictions about how to handle them. A classifier learns from your example data and then can return information for texts that it is not trained on. {:shortdesc}

You can create and train a {{site.data.keyword.nlclassifiershort}} in less than 15 minutes.

Step 1: Log in, create the service, and get your credentials

If you already know your credentials for the {{site.data.keyword.nlclassifiershort}} service instance, skip this step. {: tip}

  1. Go to the {{site.data.keyword.nlclassifiershort}} service and either sign up for a free {{site.data.keyword.Bluemix_notm}} account or log in.
  2. After you log in, type Classifier-tutorial in the Service name field of the {{site.data.keyword.nlclassifiershort}} page. Click Create.
  3. Copy your credentials:
    1. Click Service credentials.
    2. Click View credentials in the "Service Credentials" section.
    3. Copy the username and password values.

Step 2: Create and train a classifier

The classifier learns from examples before it can return information for texts that it hasn't seen before. The example data is referred to as "training data." You upload the training data when you create a classifier.

  1. Download the sample weather_data_train.csv. This is the same training data that is used in the demo External link icon{:new_window}.

    The file is in a CSV format in two columns. The first column is the text input. The second column is the class for that text: temperature or condition. View the file to see the entries.

  2. Issue the following command to call the POST /classifiers/ method, which uploads the training data and creates the classifier:

    • Replace {username} and {password} with the service credentials you copied in the previous step.
    • Modify the location of the training data to point to where you saved the weather_data_train.csv file.
    curl -i --user "{username}":"{password}" -F training_data=@{path_to_file}/weather_data_train.csv -F training_metadata="{\"language\":\"en\",\"name\":\"TutorialClassifier\"}" "https://gateway.watsonplatform.net/natural-language-classifier/api/v1/classifiers"

    {: pre}

    The response includes a new classifier ID and status. For example:

    {
    "name": "TutorialClassifier",
    "language": "en",
    "status": "Training",
    "url": "https://gateway.watsonplatform.net/natural-language-classifier/api/v1/classifiers/10D41B-nlc-1",
    "classifier_id": "10D41B-nlc-1",
    "created": "2015-05-28T18:01:57.393Z",
    "status_description": "The classifier instance is in its training phase, not yet ready to accept classify requests"
}

    Training begins immediately and must finish before you can query the classifier.

  3. Check the training status periodically until you see a status of Available. With this sample data, training takes about 6 minutes:

    • Issue a GET /classifiers/{classifier_id} call to retrieve the status of the classifier. In the following example, replace {username}, {password}, and {classifier_id} with your information:

      curl --user "{username}":"{password}" "https://gateway.watsonplatform.net/natural-language-classifier/api/v1/classifiers/{classifier_id}"

      {: pre}

Step 3: Classify text

Now that the classifier is trained, you can query it.

  1. Classify some weather-related questions to review how your newly trained classifier responds. Here is an example call. Replace {username}, {password}, and {classifier_id} with your information:

    curl -G --user "{username}":"{password}" "https://gateway.watsonplatform.net/natural-language-classifier/api/v1/classifiers/{classifier_id}/classify" --data-urlencode "text=How hot will it be today?"

    {: pre}

    The API returns a response that includes the name of the class for which the classifier has the highest confidence. Other class-confidence pairs are listed in descending order of confidence:

    {
    "classifier_id": "10D41B-nlc-1",
    "url": "https://gateway.watsonplatform.net/natural-language-classifier/api/v1",
    "text": "How hot will it be today?",
    "top_class": "temperature",
    "classes": [
    {
        "class_name": "temperature",
        "confidence": 0.9998201258549781
    },
    {
        "class_name": "conditions",
        "confidence": 0.00017987414502176904
    }
    ]
}

    The confidence value represents a percentage, and higher values represent higher confidences. The response includes up to 10 classes.

    If you have fewer than 10 classes in your training data, the sum of all confidence values is 100%. In this sample training data, only two classes are defined, so only two can be returned.

  2. Review the top class for the questions to see how the classifier is predicting them.

    Here are some other sample questions to classify:

    • Is it hot outside?
    • Will it be windy?
    • Will we see some sun?
    • What is the expected high for today?
    • Will it be foggy tomorrow morning?

    One of the sample questions includes a term ("foggy") that the classifier isn't trained on. The classifier can score well with these "missing" terms without your having to do extra work to identify them. Try other questions that include words that are not in the training data, for example, "sleet" or "storm."

You're done! You created, trained, and queried a classifier in the {{site.data.keyword.nlclassifiershort}} service.

Delete the tutorial classifier

So that you can create classifiers for your own use and with your own training data, you might want to delete this classifier from the tutorial. To delete the classifier, call the DELETE /classifiers/{classifier_id} method.

As previously, replace {username}, {password}, and {classifier_id} with your information in the following command.

curl -X DELETE --user "{username}":"{password}" "https://gateway.watsonplatform.net/natural-language-classifier/api/v1/classifiers/{classifier_id}"

{: pre}

The response to the command is an empty JSON object.

Next steps

You have a basic understanding of how to use {{site.data.keyword.nlclassifiershort}}. Now dive deeper: