Package: tensorfx
Introduction to TensorFX========================TensorFX is an end to end application framework to simplifies machinelearning with `TensorFlow <http://tensorflow.org>`__ - both trainingmodels and using them for prediction. It is designed from the ground upto make the mainline scenarios simple with higher level building blocks,while ensuring custom or complex scenarios remain possible by preservingthe flexibility of TensorFlow APIs.There are some important principles that shape the design of theframework:1. **Simple, consistent set of usage patterns** Local or cloud, singlenode or distributed execution, in-memory data or big data shardedacross files, you should have to write code once, in a single wayregardless of how the code executes.2. **A Toolbox with Useful Abstractions** The right entrypoint for thetask at hand, starting with off-the-shelf algorithms that let youfocus on feature engineering and hyperparam tuning. If you need tosolve something unqiue, you can focus on building TensorFlow graphs,rather than infrastructure code (distributed cluster setup,checkpointing, logging, exporting models etc.).3. **Declarative** Using YAML, JSON, and simplified Python interfaces tominimize the amount of boilerplate code.OK, enough context... here is some information to get you started.Getting Started---------------Once you have a Python environment (recommendation: use Miniconda),installation is straightforward:::pip install tensorflowpip install tensorfxNote that TensorFX depends on TensorFlow 1.0, and supporting librariessuch as numpy and pandas.Documentation-------------Documentation is at https://tensorlab.github.io/tensorfx/. This includesAPI reference topics, as well as conceptual and how-to topics. They area work-in-progress, but check them out! There are a few samples thatdemonstrate how to get started as well in the repository. Likewise, moreto be added over time.Contributions and Development-----------------------------We welcome contributions in form of ideas, issues, samples as well ascode. Since the project is at a super-early stage, and evolving rapidly,its best to start a discussion by filing an issue for any contribution.Building and Testing~~~~~~~~~~~~~~~~~~~~If you want to develop within the repository, clone it, and run thefollowing commands:::# Install requirements and setup envionmentsource init.sh install# Build and Test./build.sh testRelated Links~~~~~~~~~~~~~-  Development workflow [TODO: Add wiki entry]Hello World - Iris Classification Model---------------------------------------This sample here is a quick 5-minute introduction to using TensorFX.Here is the code for building a feed-forward neural networkclassification model for the `irisdataset <https://archive.ics.uci.edu/ml/datasets/Iris>`__.::import tensorfx as tfximport tensorfx.models.nn as nn# Hyperparameters, training parameters, and dataargs, job = nn.FeedForwardClassificationArguments.parse(parse_job=True)dataset = tfx.data.CsvDataSet(args.data_schema,train=args.data_train,eval=args.data_eval,metadata=args.data_metadata,features=args.data_features)# Instantiating the model builderclassification = nn.FeedForwardClassification(args, dataset)# Trainingtrainer = tfx.training.ModelTrainer()model = trainer.train(classification, job)# Predictioninstances = ['6.3,3.3,6,2.5',   # virginica'4.4,3,1.3,0.2',   # setosa'6.1,2.8,4.7,1.2'  # versicolor]predictions = model.predict(instances)Here's an outline steps to perform for basic usage of what TensorFXoffers:1. Parse (or build) an Arguments object, usually from the command-lineto define hyperparameters. This object corresponds to the kind ofmodel you are training, so, ``FeedForwardClassificationArguments`` inthis case.2. Create a DataSet to reference training and evaluation data, alongwith supporting configuration - namely - schema, metadata, andfeatures (more on these below).3. Initialize the model builder - in this case``FeedForwardClassification``.4. Initialize the model trainer, and invoke ``train()`` which runs thetraining process to return a model.5. Load some instances you want to run through the model and call``predict()``.Schema - schema.yaml^^^^^^^^^^^^^^^^^^^^The schema describes the structure of your data. This can be definedprogrammatically, but is conveniently expressible in declarative YAMLform, and placed alongside training data.::fields:- name: speciestype: discrete- name: petal_lengthtype: numeric- name: petal_widthtype: numeric- name: sepal_lengthtype: numeric- name: sepal_widthtype: numericMetadata - metadata.json^^^^^^^^^^^^^^^^^^^^^^^^Metadata is the result of analyzing training data, based on typeinformation in the schema. Iris is a tiny dataset, so metadata isreadily producable using simple python code looping over the data. Forreal-world and large datasets, you'll find Spark and BigQuery (on GoogleCloud Platform) as essential data processing runtimes. Stay tuned -TensorFX will provide support for these capabilities out of the box.::{"species": { "entries": ["setosa", "virginica", "versicolor"] },"petal_length": { "min": 4.3, "max": 7.9 },"petal_width": { "min": 2.0, "max": 4.4 },"sepal_length": { "min": 1.1, "max": 6.9 },"sepal_width": { "min": 0.1, "max": 2.5 }}Features - features.yaml^^^^^^^^^^^^^^^^^^^^^^^^Like schema, features can also be defined programmatically, or expressedin YAML. Features describe the set of inputs that your models operateover, and how they are produced by applying transformations to thefields in your data. These transformations are turned into TensorFlowgraph constructs and applied consistently to both training andprediction data.In this particular example, the FeedForwardClassification model requirestwo features: X defining the values the model uses for producinginferences, and Y, the target label that the model is expected topredict which are defined as follows:::features:- name: Xtype: concatfeatures:- name: petal_widthtype: scale- name: petal_lengthtype: scale- name: sepal_widthtype: log- name: sepal_lengthtype: log- name: Ytype: targetfields: speciesRunning the Model^^^^^^^^^^^^^^^^^The python code in the sample can be run directly, or using a ``train``tool, as shown:::python -m tensorfx.tools.train \--module iris.trainer.main \--output /tmp/tensorfx/iris/csv \--data-train iris/data/train.csv \--data-eval iris/data/eval.csv \--data-schema iris/data/schema.yaml \--data-metadata iris/data/metadata.json \--data-features iris/features.yaml \--log-level-tensorflow ERROR \--log-level INFO \--batch-size 5 \--max-steps 2000 \--checkpoint-interval-secs 1 \--hidden-layers:1 20 \--hidden-layers:2 10Once the training is complete, you can list the contents of the outputdirectory. You should see the model (the prediction graph, and learntvariables) in the ``model`` subdirectory, alongside checkpoints, andsummaries.::ls -R /tmp/tensorfx/iris/csvcheckpoints job.yaml    model       summaries/tmp/tensorfx/iris/csv/checkpoints:checkpoint                             model.ckpt-2000.indexmodel.ckpt-1.data-00000-of-00001       model.ckpt-2000.metamodel.ckpt-1.index                     model.ckpt-2001.data-00000-of-00001model.ckpt-1.meta                      model.ckpt-2001.indexmodel.ckpt-1562.data-00000-of-00001    model.ckpt-2001.metamodel.ckpt-1562.index                  model.ckpt-778.data-00000-of-00001model.ckpt-1562.meta                   model.ckpt-778.indexmodel.ckpt-2000.data-00000-of-00001    model.ckpt-778.meta/tmp/tensorfx/iris/csv/model:saved_model.pb  variables/tmp/tensorfx/iris/csv/model/variables:variables.data-00000-of-00001   variables.index/tmp/tensorfx/iris/csv/summaries:eval        prediction  train/tmp/tensorfx/iris/csv/summaries/eval:events.out.tfevents.1488351760events.out.tfevents.1488352853/tmp/tensorfx/iris/csv/summaries/prediction:events.out.tfevents.1488351765/tmp/tensorfx/iris/csv/summaries/train:events.out.tfevents.1488351760events.out.tfevents.1488352852Summaries are TensorFlow events logged during training. They can beobserved while the training job is running (which is essential whenrunning a long or real training job) to understand how your training isprogressing, or how the model is converging (or not!).::tensorboard --logdir /tmp/tensorfx/iris/csvThis should bring up TensorBoard. Its useful to see the graph structure,metrics and other tensors that are automatically published.**Training Graph**.. figure:: https://tensorlab.github.io/tensorfx/_static/images/intro-graph.jpg:alt: Graphs in TensorBoardGraphs in TensorBoard**Training Metrics -- Accuracy, Loss and Throughput**.. figure:: https://tensorlab.github.io/tensorfx/_static/images/intro-metrics.jpg:alt: Metrics in TensorBoardMetrics in TensorBoard**Model Variables -- Weights, Gradients, etc.**.. figure:: https://tensorlab.github.io/tensorfx/_static/images/intro-watch.jpg:alt: Watchin Learnt VariablesWatchin Learnt VariablesAs you can see, the out-of-box model takes care of a number of details.The same code can be run on a single machine, or in a cluster (ofcourse, iris is too simple of a problem to need that).