Import Your Data
How to create Phoenix inferences and schemas for common data formats
Last updated
How to create Phoenix inferences and schemas for common data formats
Last updated
This guide shows you how to define Phoenix inferences using your own data.
For a conceptual overview of the Phoenix API, including a high-level introduction to the notion of inferences and schemas, see Phoenix Basics.
For a comprehensive description of phoenix.Dataset
and phoenix.Schema
, see the API reference.
Once you have a pandas dataframe df
containing your data and a schema
object describing the format of your dataframe, you can define your Phoenix dataset either by running
or by optionally providing a name for your dataset that will appear in the UI:
As you can see, instantiating your dataset is the easy part. Before you run the code above, you must first wrangle your data into a pandas dataframe and then create a Phoenix schema to describe the format of your dataframe. The rest of this guide shows you how to match your schema to your dataframe with concrete examples.
Let's first see how to define a schema with predictions and actuals (Phoenix's nomenclature for ground truth). The example dataframe below contains inference data from a binary classification model trained to predict whether a user will click on an advertisement. The timestamps are datetime.datetime
objects that represent the time at which each inference was made in production.
timestamp | prediction_score | prediction | target |
---|---|---|---|
This schema defines predicted and actual labels and scores, but you can run Phoenix with any subset of those fields, e.g., with only predicted labels.
Phoenix accepts not only predictions and ground truth but also input features of your model and tags that describe your data. In the example below, features such as FICO score and merchant ID are used to predict whether a credit card transaction is legitimate or fraudulent. In contrast, tags such as age and gender are not model inputs, but are used to filter your data and analyze meaningful cohorts in the app.
If your data has a large number of features, it can be inconvenient to list them all. For example, the breast cancer dataset below contains 30 features that can be used to predict whether a breast mass is malignant or benign. Instead of explicitly listing each feature, you can leave the feature_column_names
field of your schema set to its default value of None
, in which case, any columns of your dataframe that do not appear in your schema are implicitly assumed to be features.
You can tell Phoenix to ignore certain columns of your dataframe when implicitly inferring features by adding those column names to the excluded_column_names
field of your schema. The dataframe below contains all the same data as the breast cancer dataset above, in addition to "hospital" and "insurance_provider" fields that are not features of your model. Explicitly exclude these fields, otherwise, Phoenix will assume that they are features.
Embedding features consist of vector data in addition to any unstructured data in the form of text or images that the vectors represent. Unlike normal features, a single embedding feature may span multiple columns of your dataframe. Use px.EmbeddingColumnNames
to associate multiple dataframe columns with the same embedding feature.
For a conceptual overview of embeddings, see Embeddings.
For a comprehensive description of px.EmbeddingColumnNames
, see the API reference.
The example in this section contain low-dimensional embeddings for the sake of easy viewing. Your embeddings in practice will typically have much higher dimension.
To define an embedding feature, you must at minimum provide Phoenix with the embedding vector data itself. Specify the dataframe column that contains this data in the vector_column_name
field on px.EmbeddingColumnNames
. For example, the dataframe below contains tabular credit card transaction data in addition to embedding vectors that represent each row. Notice that:
Unlike other fields that take strings or lists of strings, the argument to embedding_feature_column_names
is a dictionary.
The key of this dictionary, "transaction_embedding," is not a column of your dataframe but is name you choose for your embedding feature that appears in the UI.
The values of this dictionary are instances of px.EmbeddingColumnNames
.
Each entry in the "embedding_vector" column is a list of length 4.
The features in this example are implicitly inferred to be the columns of the dataframe that do not appear in the schema.
To compare embeddings, Phoenix uses metrics such as Euclidean distance that can only be computed between vectors of the same length. Ensure that all embedding vectors for a particular embedding feature are one-dimensional arrays of the same length, otherwise, Phoenix will throw an error.
If your embeddings represent images, you can provide links or local paths to image files you want to display in the app by using the link_to_data_column_name
field on px.EmbeddingColumnNames
. The following example contains data for an image classification model that detects product defects on an assembly line.
For local image data, we recommend the following steps to serve your images via a local HTTP server:
In your terminal, navigate to a directory containing your image data and run python -m http.server 8000
.
Add URLs of the form "http://localhost:8000/rel/path/to/image.jpeg" to the appropriate column of your dataframe.
For example, suppose your HTTP server is running in a directory with the following contents:
Then your image URL would be http://localhost:8000/image-data/example_image.jpeg.
If your embeddings represent pieces of text, you can display that text in the app by using the raw_data_column_name
field on px.EmbeddingColumnNames
. The embeddings below were generated by a sentiment classification model trained on product reviews.
Sometimes it is useful to have more than one embedding feature. The example below shows a multi-modal application in which one embedding represents the textual description and another embedding represents the image associated with products on an e-commerce site.
Distinct embedding features may have embedding vectors of differing length. The text embeddings in the above example have length 4 while the image embeddings have length 5.
fico_score | merchant_id | loan_amount | annual_income | home_ownership | num_credit_lines | inquests_in_last_6_months | months_since_last_delinquency | age | gender | predicted | target |
---|---|---|---|---|---|---|---|---|---|---|---|
target | predicted | mean radius | mean texture | mean perimeter | mean area | mean smoothness | mean compactness | mean concavity | mean concave points | mean symmetry | mean fractal dimension | radius error | texture error | perimeter error | area error | smoothness error | compactness error | concavity error | concave points error | symmetry error | fractal dimension error | worst radius | worst texture | worst perimeter | worst area | worst smoothness | worst compactness | worst concavity | worst concave points | worst symmetry | worst fractal dimension |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
target | predicted | hospital | insurance_provider | mean radius | mean texture | mean perimeter | mean area | mean smoothness | mean compactness | mean concavity | mean concave points | mean symmetry | mean fractal dimension | radius error | texture error | perimeter error | area error | smoothness error | compactness error | concavity error | concave points error | symmetry error | fractal dimension error | worst radius | worst texture | worst perimeter | worst area | worst smoothness | worst compactness | worst concavity | worst concave points | worst symmetry | worst fractal dimension |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
predicted | target | embedding_vector | fico_score | merchant_id | loan_amount | annual_income | home_ownership | num_credit_lines | inquests_in_last_6_months | months_since_last_delinquency |
---|---|---|---|---|---|---|---|---|---|---|
defective | image | image_vector |
---|---|---|
name | text | text_vector | category | sentiment |
---|---|---|---|---|
name | description | description_vector | image | image_vector |
---|---|---|---|---|