The getML Python API¶
The getML Python API is shipped along with the matching version of getML engine and monitor in the file you can download from getml.com (see Installation).
The most important thing you have to keep in mind when working with the Python API is this:
All classes in the Python API are just handles to objects living in the getML engine.
In addition, two basic requirements need to be fulfilled to successfully use the API:
You need a running getML engine (on the same host as your Python session) (see Starting the engine)
You need to set a project in the getML engine using
getml.engine.set_project()
.import getml getml.engine.set_project('test')
This section provides some general information about the API and how it interacts with the engine. For an in-depth read about its individual classes, check out the Python API documentation.
Connecting to the getML engine¶
The getML Python API automatically connects to the engine with
every command you execute. It establishes a socket connection to the
engine at port getml.port
.
The port is stored in the config.json file in the .getML/getml-VERSION/ folder in your user’s home directory. If you change the port, you need to tell the Python API:
import getml
getml.communication.port = 3245
Session management¶
You can set the current project (see Managing data using projects)
using getml.engine.set_project()
. If no project matches the
supplied name, a new one will be created. To get a
list of all available projects in your engine, you can use
getml.engine.list_projects()
and to remove an entire project,
you can use getml.engine.delete_project()
.
Lifecycles and synchronization between engine and API¶
The most important objects are the following:
Data frames (
DataFrame
), which act as a container for all your data.Pipelines (
Pipeline
), which hold the trained states of the algorithms.
Lifecycle of a DataFrame
¶
You can create a DataFrame
by calling one of
the from_csv()
,
from_db()
,
from_json()
, or
from_pandas()
classmethods. These create
a data frame object in the getML engine, import the provided data,
and return a handler to the object as a
DataFrame
in the Python API (see
Importing data).
When you apply any method, like add()
, the
changes will be automatically reflected in both the engine and Python.
Under the hood, the Python API sends a
command to create a new column to
the getML engine. The moment the engine is done, it informs the Python
API and the latter triggers the refresh()
method to update the Python handler.
Data frames are never saved automatically
and never loaded automatically. All unsaved changes to a
DataFrame
will be
lost when loading
another project (see Managing data using projects) or restarting
the engine. To save a DataFrame
, use
save()
.
You can use getml.data.list_data_frames()
to get a summary of all
available data frames. To load a data frame, you can use
getml.data.load_data_frame()
:
df = getml.data.load_data_frame(NAME_OF_THE_DATA_FRAME)
If a DataFrame
called NAME_OF_THE_DATA_FRAME is already available in memory,
getml.data.load_data_frame()
will return a handle to that
data frame. If no such DataFrame
is held
in memory, the function will try to load the data frame from disk and
then return a handle. If that is unsuccessful, an exception is
thrown.
If you want to force the API to load the
version stored on disk over the one
held in memory, you can use the load()
as follows:
df = getml.data.DataFrame(NAME_OF_THE_DATA_FRAME).load()
Lifecycle of a Pipeline
¶
The lifecycle of a
getml.pipeline.Pipeline
is straightforward since the getML engine
automatically
saves all changes made to a pipeline and automatically loads all
pipelines contained in a project.
Using the constructors, the individual pipelines are created within the Python API, where they are represented as a set of hyperparameters. The actual weights of the machine learning algorithms are only stored in the getML engine and never transferred to the Python API.
When applying any method, like
fit()
, the changes will be
automatically reflected in both the engine and
the Python API.
When using getml.engine.set_project()
to load an existing
project, all pipelines contained in that project
will be automatically loaded into memory.
In order to create a corresponding handle in the Python API, you can use
getml.pipeline.load()
:
pipe = getml.pipeline.load(NAME_OF_THE_PIPELINE)
The function getml.pipeline.list_pipelines()
lists all
available pipeline within a project.