The C3.ai system contains many tools to help scientists with their data analysis. We want researchers
to researchers to have the option to get started using C3 right away. This guide details how to connect to a C3 cluster,
fetch fetch data you want to use, and convert it into a form that you can more easily analyze. Consider this guide
to guide to cover 'simple read-only' tasks.
...
All data in C3 is represented by a 'Type'. Data for a specific type can be 'fetched' from C3 using the 'fetch' API.
In In each language, each Type has a 'fetch' function to which a FetchSpec Type can be passed. This function then retrieves
the retrieves the data in a FetchResult Type which can be opened and used for data analysis.
Fetching is governed by the FetchSpec Type and you can find full documentation of that type here. However,
as as a simple API description, may not be particularly helpful at first. Generally, the FetchSpec type defines a set of
constraints to apply when gathering Type data. it can be 'empty' i.e. without constraints, but generally you'll
want ll want to apply one or more to get reasonable results.
...
In this example, the Type BlockInfo defines information aggregated about census blocks. We can for example, fetch BlockInfo
types BlockInfo types for which the 'prp_bf_lr' property is defined. Then we can order them based on their 'id' properly.
...
For most data analysis situations, FetchResults need to be massaged a little bit to be useful.
Here Here, we show the typical ways FetchResults can be used.
...
In python, generally, you get the 'objs' property from the FetchResults object, then call the toJson() function.
This This function returns an array of dictionaries each with keys equal to the requested properties of the fetched
typefetched type. This works well with the pandas DataFrame constructor which accepts such an array. The returned
DataFrame returned DataFrame object can now be analyzed very easily. We show an example below.
...
Several spots in the C3 API allow for the use of so-called 'ExpressionEngineFunctions'. These functions take a variety of
arguments of arguments and perform a variety of processing tasks. For example, the function 'contains' takes two strings and checks
whether checks whether the first argument contains the second argument. The function 'lowerCase' takes an input string, and returns
that returns that string with all uppercase letters replaced with lowercase ones. In addition to those string processing functions,
many many math functions exist as well such as 'log' which operates on a variety of input data types.
...
C3 can store timeseries data using many different types, however knowing the exact type of timeseries data isn't
super t super important when it comes to evaluating so-called 'Metrics' on that data.
...
Usually, timeseries data goes through a 'normalization' process, the purpose of which is to take non-uniform, and possibly multiple datasets and produce
a produce a single uniform timeseries which can be analyzed a little more easily in most cases. We copy here the list of normalization steps that are currently
performed currently performed within the C3 platform, these are available from C3's official documentation here: https://developer.c3.ai/docs/7.12.0/guide/guide-c3aisuite-basic/ts-normalization-engine
...
Simple metrics form the 'base' of the Metrics system. They are defined on a specific Type and reference timeseries data stored within.
Essentially Essentially, the Simple metric defines:
...
Compound metrics are generally easier to define and use as they operate on already defined metrics either Simple or Compound.
They They essentially just consist of and id/name, and an expression defining the metric in terms of constants and already defined metrics.
If If you try and execute a CompoundMetric on a type for which some necessary SimpleMetric is not defined, you'll get an error.
...
With a metric in mind, you can use the 'evalMetrics' API function which is brought in with the MetricEvaluatable type to actually evaluate the metric.
The The evalMetrics function takes an 'EvalMetricsSpec' type which contains the following:
...
For most data exploration, you'll find yourself 'Fetching' and running 'evalMetrics'. This guide provides a good foundation for these activities.
This This first set of activities might be described as 'Read-Only'. Here you're using the C3 AI Suite as simply a readable database and API.
The The next set of things to learn would be 'Write' type operations. How do you define new types? How do you 'persist' new instances of a type?
How How do you clean the databases in your tag up? And so on. These will be the subject of a planned DTI Guide.