How griffithlab/civicpy works
Project type and purpose
• From the README and file tree, CIViCpy is an open-source Python client library and CLI analysis toolkit for the Clinical Interpretations of Variants in Cancer (CIViC) knowledgebase.
• It provides a programmable interface (via civicpy.civic) and a command-line tool (civicpy.cli) to query CIViC’s GraphQL API, process and cache results, and export data in common formats.
File structure
• Top-level code lives in the “civicpy” package:
• civic.py: core client class (HTTP/GraphQL orchestration)
• graphql_payloads.py: pre-built GraphQL query templates
• exports.py: routines to serialize data to CSV/TSV/JSON
• cli.py: command-line entry points and argument parsing
• utils.py: shared helpers (e.g., caching, rate-limit handling)
• data/: test fixtures and example cache
• tests/: unit tests for each module
• Supporting files: setup.py, Pipfile, Dockerfile, CI workflows (.github/workflows + .travis.yml), docs/ for Sphinx, examples/ notebooks.
README for additional insights
• Confirms the role of the library as a “Python client and analysis toolkit.”
• External dependency: CIViC’s public GraphQL endpoint.
• Encourages use in Jupyter (examples).
Main components & interactions
a. Internal Components
• CLI Interface (civicpy.cli)
• Core API Client (civicpy.civic)
• GraphQL Payload Builder (civicpy.graphql_payloads)
• Data Models & Caching (civicpy.utils + data/)
• Export Module (civicpy.exports)
b. External Services
• CIViC GraphQL API (public endpoint)
• Local filesystem or cache store (pickle cache)
• User environment (Jupyter notebooks, scripts)
c. CI/CD & Deployment (secondary)
• GitHub Actions / Travis CI pipelines (tests, lint, release)
• Docker container for reproducible environment
• PyPI for package distribution
d. Data Flows & Relationships
1. User invokes CLI or imports library in code/notebook
2. CLI calls Core API Client with user arguments
3. Core client uses GraphQL Payload Builder to assemble queries
4. Queries sent over HTTP to CIViC GraphQL API
5. JSON responses returned → parsed into Python objects
6. Data optionally cached via utils; subsequent calls read cache
7. Export module serializes objects to CSV/TSV/JSON or returns Pandas DataFrames
8. Output delivered to console, files, or notebook
Architectural patterns and design principles
• Modular design: separation of concerns (CLI, client logic, payloads, exports)
• Reuse of query templates (GraphQL payloads)
• Caching layer abstracts network latency
• Test coverage enforces reliability