Reference Information

This article contains the following sections:

Accessing Technical Documentation

You can find the complete technical documentation packaged with the SDK. The docstrings can also be accessed within Python. For example:

help(sm)
help(sm.client.Credentials)
help(sm.twin.Machine)

Initializing the SDK Client

The SDK Client provides methods for authentication and initializing new DigitalTwin and Plot objects.

To initialize the SDK Client:

  1. Run:
  2. cli = sm.Client('<tenantname>', auto_login=False)
    	

    where '<tenantname>' is the name of your Sight Machine subdomain (e.g., ‘demo’ for demo.sightmachine.io). The Client will be used to inspect configurations, retrieve data, and generate visualizations.

Setting Authentication Credentials

After installing the SDK, you need to set authentication credentials. You only need to authenticate the first time that you use the SDK; the credentials will be stored for future use.

To set authentication credentials:

  1. Log in using the method provided by Sight Machine:
  2. cli.login('basic', email='<user@domain.com>', password='<password>')
    
    cli.login('apikey', key='<apikey>')
    	

Using Digital Twins

Digital Twins store the configuration for user-configured models such as Machine and Machine Type. Their most common application is to look up information that you can use to refine a query for data, such as the database-friendly name of a particular machine or machine type.

To use Digital Twins:

  1. Run:
  2. dt_mch = cli.get_twin('Machine')
    display(type(dt_mch))
    
    df_mch_config = dt_mch.fetch_meta(cli.session)
    display(type(df_mch_config), df_mch_config.shape)
    
    display(df_mch_config.sort_values('Machine.source_clean').head(10))
    	

Using Sight Machine Data Models

Sight Machine has developed a number of data models for contextualized data. Some, such as Machine Type and Machine, are user-configured models, while others, such as Cycles, Downtimes, and Defects, are generated by the AI Data Pipeline.

For information about interacting with models such as Machine, see Using Digital Twinsabove.

For more information about Sight Machine’s data models, reference the following:
https://docs.sightmachine.com/category/160-models

Retrieving Data

The SDK provides a simple interface for downloading data from models such as Cycles, Downtimes, and Defects.

To retrieve data:

  1. Generate a query to limit the data returned.
    The Sight Machine SDK supports a PyMongo-like query syntax. See the PyMongo Tutorial for examples. One notable difference is that the Sight Machine API does not support logical OR.
  2. You may wish to explore Digital Twins before generating a query. Get the Digital Twin for the machine that you are interested in gathering data from:
  3. MACHINE_TYPE = 'Lasercut'
    dt_lc = cli.get_twin('Machine', MACHINE_TYPE)
    	
  4. Assemble the query:
  5. DATE_START = datetime(2017, 8, 6)
    DATE_END   = datetime(2017, 8, 7)
    QUERY = {
        'endtime' : {'$gte' : DATE_START, '$lt' : DATE_END},
        'machine.source_type' : MACHINE_TYPE
    }
    	
  6. Use the query to fetch data. The data is returned as a pandas dataframe. The same function can be applied to any data model:
  7. df_lc_c = dt_lc.fetch_data(cli.session, 'cycle', QUERY, normalize=True)
    display(df_lc_c.shape)
    df_lc_dt = dt_lc.fetch_data(cli.session, 'downtime', QUERY, normalize=True)
    df_lc_def = dt_lc.fetch_data(cli.session, 'defect', QUERY, normalize=True)
    	
  8. You can now export the data, run an exploratory analysis, train a model, blend in data from other sources, or otherwise manipulate the data.

Generating Data Visualizations

You can generate basic visualizations, set chart titles, add overlays, and define panels using the SDK. Python also supports other visualization libraries. See the following:

Generating Basic Visualizations

The SDK provides simple methods for generating basic visualizations.

Visualization How to Generate
Scatter and Line Plot To generate a scatter or line plot, the dataframe columns must be passed in with the ordering [x, y, z], where each value of z is displayed as a separate trace with a distinct color.
df_tmp = df_cycle[['temperature', 'pressure', 'machine']]

plt1 = cli.get_plot('scatter', df_tmp)		
iplot(plt1.plot())

plt2 = cli.get_plot('line', df_tmp)
iplot(plt2.plot())
			
Bar Plot To generate a bar plot, the dataframe columns must be passed in with the ordering [x, y, z], where each value of z is displayed as a separate trace with a distinct color. This grouping step illustrates one way of aggregating data.         
df_tmp = df_cycle[[model_number, 'pressure', 'machine']]   
         ].groupby([model_number', 'machine']
         ).mean().reset_index()[['model_number', 'pressure', 'machine.source']]
			
plt = cli.get_plot('bar', df_tmp)		
iplot(plt.plot())
			
Box Plot To generate a box plot, the dataframe columns must be passed in with the ordering [x, y, z], where each value of z is displayed as a separate trace with a distinct color.

df_tmp = df_cycle[[‘model_number’, 'pressure', 'machine']]

plt = cli.get_plot('box', df_tmp)
iplot(plt.plot())
			
Histogram To generate a histogram, the dataframe columns must be passed in with the ordering [x, z], where each value of z is displayed as a separate trace with a distinct color.
df_tmp = df_cycle[['pressure', 'machine']]

plt = cli.get_plot('histogram', df_tmp)
iplot(plt.plot())
			
Pareto To generate a pareto, the dataframe columns must be passed in with the ordering [x, y, z], where each value of z is displayed as a separate trace with a distinct color. This grouping step illustrates one way of aggregating data.
df_tmp = df_defect[[‘defect’, ‘quantity’, 'machine']] 
                ]].groupby(['defect','machine']
		).sum().sort_values('quantity', ascending=False).reset_index()
			
df_tmp = df_tmp[[‘defect’, ‘quantity’, 'machine']]
			
plt = cli.get_plot('pareto', df_tmp)
iplot(plt.plot())
			
Heatmap To generate a heatmap, the dataframe columns must be passed in with the ordering [x, y, z], where x and y are the labels and z is the value of each cell. This correlation step illustrates one common way of preparing correlation data for use in a heatmap.

 

df_tmp = df_cycle[[  
   'temperature',
   'pressure',					
   'velocity',
   'flowrate',
   'current’,		
   ‘voltage’		
]]

df_corr = df_tmp.corr().unstack().to_frame().reset_index()
			
plt = sm.Client.get_plot('heatmap', df_corr)
iplot(plt.plot())
			

Using Other Styling Methods

You can add a chart title.

To set the title of your chart:

  1. Run:
  2. plt = cli.get_plot('line', df_tmp)
    plt.set_title('Temperature over Time')
    iplot(plt.plot())
    	

Adding Overlays

The SDK offers support for adding overlays to plots using a Plotly feature called “shapes.” At present, the SDK provides methods for adding lines, rectangles, and circles/ovals.

The basic information needed to generate a shape include its location, form, and style. These attributes of the shape must be stored as columns in a dataframe, which the SDK will interpret.

To add overlays:

  1. Generate the x and y coordinates of the shape’s bounding box from your data. This example overlay is designed to be applied to a graph of temperature over time; select the appropriate data for your own chart.
  2. df_rect = df_cycle[['starttime','endtime']].copy(deep=True)
    df_rect = df_rect.rename(columns={'starttime': 'x0', 'endtime': 'x1'})
    df_rect.loc[:, 'x0'] = pd.to_datetime(
    df_rect['x0'])df_rect.loc[:, 'x1'] = pd.to_datetime(
    df_rect['x1'])
    df_rect.loc[:, 'y0'] = 0df_rect.loc[:, 'y1'] = 1
    	
  3. Set the form of the shape.
  4. df_rect.loc[:, 'xref'] = 'x'
    df_rect.loc[:, 'yref'] = 'paper'
    df_rect.loc[:, 'type'] = 'rect'
    	
  5. If desired, set styling for the shape. This is optional; a default styling will be applied to any options that are not specified. Note that Plotly expects some style and layout options to be nested. To set these, insert a dictionary into each cell that contains the appropriate levels of nesting. The dataframe is treated as the outside level.
  6. df_rect.loc[:, 'fillcolor'] = '#134936'
    df_rect.loc[:, 'opacity'] = 0.15
    df_rect.reset_index(drop=True, inplace=True)
    df_rect['line'] = pd.Series([{ 'width': 0 } for i in range(len(df_rect.index))])
    	
  7. After the shape definition dataframe is complete, apply it to your plot.
  8. df_tmp = df_cycle[['endtime', 'temperature', 'shift']]
    
    plt = cli.get_plot('line', df_tmp)
    
    plt.add_overlay(sm.plot.Shape(df_rect, 'df_rect'))
    
    iplot(plt.plot())
    	

For more information about Plotly shapes and the available options, see: https://plot.ly/python/reference/#layout-shapes

Generating Code and Customizing Plots

The SDK supports basic visualizations with Sight Machine styling. Advanced users can also customize the styling or other features of the plots.

The SDK generates the Python code used to make each plot. You can edit and run this code independently.

To generate the code and customize plots:

  1. Run:
  2. sys.stdout.write(str(plt6.generate_code()))sys.stdout.flush()
    	
  3. Copy the output into your environment (a new file, a Jupyter notebook cell, etc.) and edit as desired.

For more details, consult the Plotly reference: https://plot.ly/python/reference/