Hoe schrijf ik een analyse in crandas?

Zodra andere gebruikers die deelnemen aan de samenwerking datasets hebben geüpload, wil je waarschijnlijk graag beginnen met je analyse! Dit artikel leidt je stapsgewijs door het proces om een crandas script te schrijven, goed te (laten) keuren en uit te voeren. Meer informatie over het goedkeuringsproces is hier te vinden. 

1. Controleer of je de rol van 'analist' hebt in zowel de designomgeving als de geautoriseerde omgeving.

2. Voer de stappen uit om je sleutelpaar en het verbindingsbestand te downloaden, in zowel de designomgeving als de geautoriseerde omgeving.

3. Zorg dat je een lokale/afgeschermde pythonomgeving beschikbaar hebt, en installeer crandas. 

4. Je kunt nu in python een script ontwerpen op dummy data op basis van een csv-bestand, een dummy pandas DataFrame of de table handle van een tabel die via het designplatform is geüpload. Alle drie de opties staan in de voorbeeldcode hieronder.

import crandas as cd

# Option 1 - Create a Dummy Dataframe with the same columns as the original data
dummy_data1 = cd.DataFrame({'Fruit':['apple','pear','banana','apple'],
                            'Prijs':[2,3,4,2]})

# Option 2 - upload a csv of dummy data to use
dummy_data2 = cd.read_csv('PATH/TO/dummy_data.csv')

# Option 3 - refer to a table handle from the design platform
dummy_data3 = cd.get_table('TABLE_HANDLE')

Als je klaar bent met het schrijven van je analyse op dummy data, kun je de analyse uitvoeren op gevoelige (productie)data in de geautoriseerde omgeving. Er bestaan drie typen databronnen die in het script verwerkt kunnen worden (enquête, dataverzoek en ad-hoc data upload). Voor elk van deze opties wordt hieronder uitleg gegeven. Een uitgebreide tutorial, met een aantal concrete voorbeelden van hoe datasets en enquêtes uit het platform geanalyseerd kunnen worden, is te vinden in de crandas documentatie.

Script recording

5. Een script kan worden opgenomen door een van de volgende code snippets uit te voeren. Welke je moet gebruiken, hangt af van of je data verwerkt die is geüpload via een ad-hoc data upload, een enquête of een dataverzoek. Deze code snippets zijn ook te zien in het designplatform, waarbij de waarden voor de designvariabelen (bovenin, in hoofdletters) al zijn ingevuld. Bij dataverzoeken zijn de code snippets net iets anders, aangezien het aantal datasets daar meer dan één kan zijn.

Data upload/enquête:

# copy from design platform:
DESIGN_ENV = ""
DUMMY_HANDLE = ""

# copy from authorized platform:
AUTH_ENV = ""
ANALYST_KEY = ""  
PROD_HANDLE = ""
SCHEMA = {''} 

# fill this in yourself:
ANALYSIS_NAME = ""


import crandas as cd

cd.connect(DESIGN_ENV)

cd.get_table(DUMMY_HANDLE,dummy_for=PROD_HANDLE)

script = cd.script.record(name=ANALYSIS_NAME)

table = cd.get_table(PROD_HANDLE, schema=SCHEMA)

## add any analysis on `table`

script.save(ANALYSIS_NAME + '.recording')

Dataverzoek:

import crandas as cd
import pandas as pd

# copy from design platform:
DESIGN_ENV = ""
DESIGN_HANDLES = []

# copy from authorized platform:
AUTH_ENV = ""
ANALYST_KEY = "" 
SCHEMA = {}
production_metadata = pd.DataFrame({
    "handle": [],
    "date_uploaded": [],
    "owner": []})

# fill this in yourself:
ANALYSIS_NAME = ""

cd.connect(DESIGN_ENV)

# Map production table handles to design table handles
table_dict = dict(zip(production_metadata["handle"].tolist(), DESIGN_HANDLES))

# Link each dummy table to its production handle
for handle in production_metadata["handle"].tolist():
    cd.get_table(table_dict.get(handle), dummy_for=handle)

script = cd.script.record(name=ANALYSIS_NAME)

# Concatenate the uploaded tables into a single table
tables = [cd.get_table(handle, schema=SCHEMA) for handle in production_metadata["handle"].tolist()]
table = cd.concat(tables)

## add any analysis on `table`

script.save(ANALYSIS_NAME + '.recording') 

Variabelen

De variabelen in hoofdletters die bovenin elke code snippet staan, moeten deels nog worden ingevuld:

DESIGN_ENV:
De naam van de designomgeving. Hier hoort de bestandsnaam van het verbindingsbestand te staan, zonder de '.vdlconn' aan het einde.

AUTH_ENV:
Vergelijkbaar met DESIGN_ENV. Naam van de geautoriseerde omgeving en daarmee van het verbindingsbestand, zonder '.vdlconn'.

DUMMY_HANDLE:
Table handle van de dummytabel die hoort bij de productietabel die wordt geanalyseerd. De makkelijkste manier om die handle te verkrijgen, is door de dummy tabel te uploaden naar het designplatform en de handle van de tabel te kopiëren.

Als de dataset die je wil analyseren is gebaseerd op een enquête zijn er twee manieren om de dummy data te uploaden en de dummy handle te verkrijgen:

1. Genereer een dummy dataset met dezelfde structuur als de survey, en upload die via het design platform of direct in het script.
2. Genereer een identieke survey in het design platform, en beantwoord die minstens een keer. Kopiëer dan de handle van de gegenereerde tabel met anwoorden.

PRODUCTION_METADATA:

Handles en metadata van de productietabellen, wanneer die zijn geüpload via een dataverzoek. Deze informatie kan worden gekopiëerd van het geautoriseerde platform wanneer het dataverzoek is beantwoord.

DESIGN_HANDLES:

Om een script op te nemen dat data verwerkt die is geüpload via een dataverzoek, kun je elk van de tabellen in PRODUCTION_METADATA linken aan een individuele dummytabel in de designomgeving. Het aantal table handles in DESIGN_HANDLES moet dus hetzelfde zijn als het aantal in PRODUCTION_METADATA. Als het verzoek vaker is beantwoord in de geautoriseerde omgeving zijn er twee opties:

1. Beantwoord het dataverzoek in de designomgeving even vaak
2. Upload verschillende dummytabellen naar de engine (via het designscript of via het design platform).

In beide gevallen moeten de resulterende table handles naar DESIGN_HANDLES gekopiëeerd worden.

ANALYST_KEY:

De naam van de geheime sleutel die je als het goed is hebt gedownload bij het opzetten van je account. Als die op de standaardplek is opgeslagen, kan crandas erbij wanneer hier slechts de volledige naam van het bestand wordt gekopiëerd.

ANALYSIS_NAME:

De naam van de analyse, en de bestandsnaam van de recording. De analist mag deze naam hier zelf invullen (bij voorkeur zonder spaties).

Dit is ook de naam die ingevuld moet worden bij het het aanvragen van goedkeuring voor het script via het platform.

PROD_HANDLE/SCHEMA:

Handle en schema van de (gevoelige) productie-dataset die wordt verwerkt in het script. Afhankelijk van het type databron kan dit de handle zijn van een tabel die is geüpload als een dataverzoek, een enquête of een databron die direct is geüpload naar het platform. Voor elke optie staan de vervolgstappen hieronder.

5.1 Dataverzoek
Als de productie-dataset is geupload via een dataverzoek, kan het schema van de tabel als volgt worden gevonden:

5.1.1 Verstuur een dataverzoek, en wacht tot die is beantwoord.

5.1.2 Klik op het oog-icoontje op het verstuurde dataverzoek.

5.1.3 Het dataschema is op de overzichtspagina te vinden.

Het dataschema kan worden omgezet in een JSON, om gebruikt te worden in het script. In dit voorbeeld:

SCHEMA = {'inta': 'int', 'intb': 'int', 'intc': 'int', 'stringd':'varchar', 'datee':'date'}

5.2 Enquête

Als je data uit een enquête wil verwerken, kun je de handle en het schema van die dataset als volgt vinden:

5.2.1. Ga naar het tabje 'Enquêtes' en verstuur een enquête. Wacht tot de enquête door deelnemers is beantwoord.

5.2.2. Klik op het 'Oog'-icoontje om de enquête-overzichtspagina te bekijken.

5.2.3. Kopiëer de table handle, en bepaal het schema van de tabel aan de hand van de layout. In dit geval:

SCHEMA = {'question1': 'int?', 'question2': 'int?', 'question3': 'int?'}

5.3 Data upload

5.3.1. Ga naar het tabblad "Data" in de linker zijbalk. Identificeer welke dataset je wil openen en klik op de "Oog"-knop aan de rechterkant van de rij.

5.3.2. Kopiëer de handle van de dataset die je in je analyse wil gebruiken.

5.3.3. Bepaal het schema van je tabel, aan de hand van de data layout:

Het script opnemen

6. Als alle bovenstaande variabelen zijn ingevuld, kan de analyse worden opgenomen door het pythonscript te draaien. Vervolgens wordt er een RECORDING-bestand gegenereerd dat je kunt downloaden (bijvoorbeeld vanuit Jupyter notebook).

7. Klik met de rechtermuisknop op het RECORDING-bestand en klik op 'Download'

8. Maak in het geautoriseerde platform een nieuwe analyse aan, en upload het RECORDING-bestand dat je zojuist hebt gedownload.

Een goedgekeurd script draaien

10. Ga terug naar de pythonomgeving en upload het APPROVED-bestand.

11. Draai vervolgens de volgende code om het goedgekeurde script te draaien op de gevoelige data. De variabelen in hoofdletters blijven hetzelfde.

 

Data upload/enquête:

# copy from design platform:
DESIGN_ENV = ""
DUMMY_HANDLE = ""

# copy from authorized platform:
AUTH_ENV = ""
ANALYST_KEY = "" 
PROD_HANDLE = ""
SCHEMA = {''} 

# fill this in yourself:
ANALYSIS_NAME = ""

import crandas as cd

cd.connect(AUTH_ENV)
cd.base.session.analyst_key = ANALYST_KEY

script = cd.script.load(ANALYSIS_NAME + '.approved')

table = cd.get_table(PROD_HANDLE, schema=SCHEMA)

## add the same analysis on `table` as was recorded

script.reset()

Dataverzoek:

import crandas as cd
import pandas as pd

# copy from design platform:
DESIGN_ENV = ""
DESIGN_HANDLES = []

# copy from authorized platform:
AUTH_ENV = ""
ANALYST_KEY = "" 
SCHEMA = {}
production_metadata = pd.DataFrame({
    "handle": [],
    "date_uploaded": [],
    "owner": []})

# fill this in yourself:
ANALYSIS_NAME = ""

cd.connect(AUTH_ENV)
cd.base.session.analyst_key = ANALYST_KEY

script = cd.script.load(ANALYSIS_NAME + '.approved')

# Concatenate the uploaded tables into a single table
tables = [cd.get_table(handle, schema=SCHEMA) for handle in production_metadata["handle"].tolist()]
table = cd.concat(tables)

## add any analysis on `table`


script.reset()