Riferimento API

Creazione e modifica di grafici

Crea grafici pronti per la pubblicazione dai tuoi dati, poi modificali con istruzioni successive.

Campi del modulo#

POST /charts/generations accetta multipart/form-data. Ambito richiesto: figures:generate.

Campo	Tipo	Obbligatorio	Valore predefinito	Regole
data	file	sì	—	CSV, TSV, TXT, XLSX o XLS fino a 8 MB, con riga di intestazione; viene rilevato il delimitatore di CSV, TSV e TXT: virgola, tabulazione o punto e virgola
request	string	sì	—	Cosa rappresentare, in linguaggio naturale; 1–16.000 caratteri
chart_types	string	no	scelto dai dati	Separati da virgole oppure come array JSON; vedi l’elenco sotto
journal_style	string	no	`default`	`default`, `nature`, `science`, `cell`, `plos` o `acs`
figure_width	string	no	`double`	Larghezza di colonna `single`, `onehalf` o `double`; PLOS e ACS non hanno `onehalf`
color_palette	string	no	`okabe_ito`	`okabe_ito`, `wong`, `tol_bright`, `tol_muted`, `nature`, `science`, `nejm`, `lancet` o `jama`
sheet_name	string	per cartelle di lavoro con più fogli	—	Il foglio di un file XLSX o XLS da cui creare il grafico; 1–255 caratteri

Errori nei dati#

I dati vengono analizzati prima di creare qualsiasi cosa, con lo stesso analizzatore del sito. Dati illeggibili restituiscono 400 INVALID_REQUEST con details.field = data e il codice dell’analizzatore in details.reason, ad esempio DATACHART_CSV_INVALID o DATACHART_TOO_MANY_ROWS. Nessun processo viene eseguito e nessun credito viene usato.
Una cartella di lavoro con più fogli senza sheet_name restituisce 400 INVALID_REQUEST con DATACHART_WORKSHEET_REQUIRED e i nomi dei fogli in details.sheet_names; invia nuovamente la richiesta con sheet_name. Un sheet_name sconosciuto restituisce DATACHART_WORKSHEET_INVALID, sempre con details.sheet_names.
Un tipo di file fuori dall’elenco restituisce UNSUPPORTED_DATA_FORMAT; un file oltre il limite di dimensione restituisce DATA_FILE_TOO_LARGE.
Ogni nuovo file di dati conta per i limiti di caricamento del sito; oltre tali limiti la risposta è 429 RATE_LIMITED con UPLOAD_RATE_LIMITED o UPLOAD_DAILY_LIMIT_REACHED. Riprovare con la stessa chiave non conta il file nuovamente.

Tipi di grafici#

bar, line, scatter, dot, frequency_dot, pie, nested_pie, timeseries, waterfall, stacked_area, radar, boxplot, violin, histogram, density, raincloud, beeswarm, qq, ogive, ecdf, ridgeline, regression, errorbar, correlation, bland_altman, funnel, standard_curve, bubble, hexbin, paired_dot, volcano, kaplan_meier, forest, roc, manhattan, ma_plot, enrichment, dose_response, growth_curve, enzyme_kinetics, precision_recall, calibration_curve, confusion_matrix, heatmap, dendrogram, upset, sankey, stem_leaf, calendar_heatmap

Risultati e crediti#

100 crediti per grafico. Un processo riuscito produce la stessa figura in PNG, PDF, TIFF ed EPS, nelle dimensioni della colonna della rivista. Ogni risultato include editor_url, che apre il grafico nella sua conversazione DataChart sul sito.

Modifiche#

POST /charts/edits con JSON {"job": "<chart job id>", "instruction": "..."} modifica il grafico prodotto dal processo mantenendo dati, tipi di grafici, stile della rivista e palette. instruction contiene 1–16.000 caratteri. 100 crediti, come nello spazio di lavoro.

Il processo deve essere uno dei tuoi processi di grafico, altrimenti 400 INVALID_REQUEST con JOB_NOT_FOUND. Se è fallito, la risposta è 400 INVALID_REQUEST con JOB_NOT_SUCCEEDED.
Se è ancora in esecuzione, la risposta è 409 REVISION_CONFLICT con details.reason = PARENT_JOB_RUNNING e Retry-After. Questo errore consente un nuovo tentativo: invia la stessa richiesta con la stessa chiave quando il processo è terminato.
Solo l’ultima versione può essere modificata, come nello spazio di lavoro. Modifica il processo più recente della catena; uno precedente restituisce 409 REVISION_CONFLICT con NOT_LATEST_REVISION, anche se una nuova versione è stata creata sul sito o un’altra modifica della stessa versione è stata accettata prima.
Una modifica alla volta: mentre una modifica della versione corrente è in esecuzione, un’altra restituisce 409 REVISION_CONFLICT con EDIT_IN_PROGRESS. Attendi il processo in corso e poi modifica il suo risultato.
Un grafico creato sul sito prima del formato attuale non può essere continuato tramite l’API: 400 INVALID_REQUEST con JOB_NOT_EDITABLE.
Le modifiche effettuate tramite l’API compaiono nella stessa conversazione DataChart sul sito.

cURL#

curl -X POST https://scifig.ai/api/v1/charts/generations \
  -H "Authorization: Bearer $SCIFIG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=25" \
  -F "data=@measurements.csv" \
  -F "request=Box plot of response by group with individual points" \
  -F "journal_style=nature"

JavaScript#

import { readFile } from 'node:fs/promises';

const form = new FormData();
form.set('data', new Blob([await readFile('measurements.csv')]), 'measurements.csv');
form.set('request', 'Box plot of response by group with individual points');
form.set('journal_style', 'nature');

const response = await fetch('https://scifig.ai/api/v1/charts/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    Prefer: 'wait=25',
  },
  body: form,
});
const result = await response.json();
console.log(response.status, result);

Python#

import os
import uuid

import requests

headers = {
    "Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
    "Idempotency-Key": str(uuid.uuid4()),
    "Prefer": "wait=25",
}
response = requests.post(
    "https://scifig.ai/api/v1/charts/generations",
    headers=headers,
    files={"data": open("measurements.csv", "rb")},
    data={"request": "Box plot of response by group with individual points", "journal_style": "nature"},
    timeout=60,
)
print(response.status_code, response.json())

PrecedenteConversione di immagini SuccessivoCreazione e modifica di diagrammi di flussoDisegna diagrammi di flusso scientifici e dei flussi di lavoro in SVG, poi modificali con istruzioni successive.