Documentation - Oncology Data to Lancet

Quick Start

Get up and running with Oncology Data to Lancet in under 5 minutes. This guide covers installation, authentication, and your first analysis.

1. Install the SDK

# Using pip

pip install oncology-lancet

# Using poetry

poetry add oncology-lancet

2. Configure Authentication

import oncology

# Set API key (get from dashboard)

oncology.configure(

  api_key="your_api_key_here"

)

3. Run Your First Analysis

from oncology import Pipeline

# Create analysis pipeline

pipeline = Pipeline(

  data_source="globocan",

  cancer_type="lung",

  year=2022

)

# Run complete analysis

results = pipeline.run()

# Generate Lancet manuscript

manuscript = results.to_manuscript(

  journal="lancet"

)

# Export

manuscript.save("my_paper.docx")

For interactive exploration, try our Jupyter notebook tutorials or the web dashboard.

Installation

System Requirements

Python 3.9 or higher
4GB RAM minimum (8GB recommended for large datasets)
Internet connection for data source access

Dependencies

The SDK automatically installs these core dependencies:

pandas >= 1.5.0
numpy >= 1.23.0
scipy >= 1.9.0
matplotlib >= 3.6.0
plotly >= 5.11.0
statsmodels >= 0.13.0

If you're using Apple Silicon (M1/M2), you may need to install scipy with: conda install scipy

Authentication

All API requests require authentication. You can authenticate using an API key or JWT token.

API Key Authentication

import oncology

# Method 1: Direct configuration

oncology.configure(api_key="olk_...")

# Method 2: Environment variable

# export ONCOLOGY_API_KEY=olk_...

# Method 3: Config file (~/.oncology/config.yaml)

# api_key: olk_...

JWT Token Authentication

from oncology.auth import JWTAuth

auth = JWTAuth(

  email="researcher@university.edu",

  password="your_password"

)

token = auth.get_token()

oncology.configure(token=token)

API Reference Overview

The Oncology Data to Lancet REST API provides programmatic access to all platform features.

Base URL: https://api.oncology-lancet.com/v1

Common Headers

Header	Value	Description
`Authorization`	`Bearer {token}`	API key or JWT token
`Content-Type`	`application/json`	Request body format
`Accept`	`application/json`	Response format

Data Endpoints

GET /data/globocan/{cancer_type}

Fetch GLOBOCAN data for a specific cancer type. Returns incidence, mortality, and prevalence by country.

Parameter	Type	Description
`cancer_type`	string	Cancer type code (e.g., "lung", "breast", "colorectal")
`year`	integer	GLOBOCAN edition year (2018, 2020, 2022)
`countries`	array	ISO country codes to filter (optional)
`metrics`	array	Metrics to include: "incidence", "mortality", "prevalence"

# Example Request

curl -X GET "https://api.oncology-lancet.com/v1/data/globocan/lung?year=2022" \

  -H "Authorization: Bearer your_token_here"

GET /data/seer/{cancer_type}

Fetch SEER program data for US cancer statistics.

POST /data/upload

Upload custom dataset for analysis. Supports CSV, Excel, and JSON formats.

Analysis Endpoints

POST /analysis/create

Create a new analysis pipeline with specified parameters.

# Example Request Body

{

  "data_source": "globocan",

  "cancer_type": "lung",

  "analysis_type": "trend",

  "parameters": {

    "years": [2000, 2005, 2010, 2015, 2020],

    "method": "joinpoint"

  }

}

GET /analysis/{analysis_id}/results

Retrieve results from a completed analysis.

POST /analysis/{analysis_id}/visualize

Generate visualization for analysis results.

Export Endpoints

POST /export/manuscript

Generate a Lancet-format manuscript from analysis results.

POST /export/figures

Export figures in publication-ready format (TIFF, EPS, PNG).

GET /export/{export_id}/download

Download generated export file.

Guide: GLOBOCAN Analysis

This guide walks through analyzing global lung cancer trends using GLOBOCAN data.

Step 1: Fetch Data

from oncology.data import GLOBOCANClient

client = GLOBOCANClient()

# Fetch lung cancer data for all countries

data = client.fetch(

  cancer_type="lung",

  year=2022,

  metrics=["incidence", "mortality"]

)

Step 2: Analyze Trends

from oncology.analysis import TrendAnalyzer

analyzer = TrendAnalyzer(data)

# Calculate age-standardized rates

asr = analyzer.calculate_asr(

  standard="world"

)

# Run joinpoint regression

trends = analyzer.joinpoint_regression(

  variable="asr"

)

Step 3: Generate Visualizations

from oncology.viz import ChartGenerator

viz = ChartGenerator()

# Choropleth map

fig = viz.world_map(

  data=asr,

  metric="incidence",

  colorscale="reds"

)

fig.save("lung_incidence_map.tiff", dpi=300)

Step 4: Generate Manuscript

from oncology.paper import LancetGenerator

gen = LancetGenerator()

ms = gen.generate(

  analysis=results,

  figures=[fig1, fig2, fig3],

  tables=[table1, table2]

)

ms.export("lung_cancer_trends.docx")

See the complete GLOBOCAN tutorial notebook for a hands-on walkthrough with real data.

Guide: Survival Analysis

Learn how to analyze cancer survival data using SEER program integration.

Key Concepts

Relative Survival - Ratio of observed survival to expected survival in the general population
Net Survival - Survival in the hypothetical scenario where cancer is the only possible cause of death
Period Analysis - Uses only recent survival experience for more current estimates

Guide: Manuscript Generation

Our AI manuscript generator creates Lancet-format papers following the journal's specific requirements.

Lancet Requirements

Structured abstract (300 words max): Objectives, Methods, Findings, Interpretation
Word count: 3000-4000 words for original articles
Maximum 6 figures/tables combined
STROBE checklist required for observational studies
Vancouver reference style