### Install cellxgene from test PyPI

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Installs the cellxgene package from the test PyPI repository. Run from the project root.

```bash
install-release-test
```

--------------------------------

### Install cellxgene from PyPI

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Installs the cellxgene package from the official PyPI repository. Run from the project root.

```bash
install-release
```

--------------------------------

### Install cellxgene from local distribution folder

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Installs the cellxgene package from a local 'dist' folder. Run from the project root.

```bash
install-dist
```

--------------------------------

### Install cellxgene from local source

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Installs the cellxgene package directly from the local source tree. Run from the project root.

```bash
install-dev
```

--------------------------------

### Launch cellxgene with example data

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/README.md

Launch the cellxgene application with a provided example anndata file URL. For more datasets or to format your own data, refer to the documentation on Demo data and Preparing your data.

```bash
cellxgene launch https://cellxgene-example-data.czi.technology/pbmc3k.h5ad
```

--------------------------------

### Set up development environment

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Installs both the main requirements and development requirements for building the code. Run from the project root.

```bash
make dev-env
```

--------------------------------

### Launch Cellxgene Server

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_guidelines.md

Start the cellxgene server with optional arguments or use the 'make' command as a shortcut.

```shell
cellxgene launch [options] <datafile>
```

```shell
make start-server
```

--------------------------------

### Start Backend Development Server

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_guidelines.md

Launch the server-side code from npm scripts. Requires Python 3.10 with virtualenv.

```bash
scripts/backend_dev
```

--------------------------------

### Install from Local Python Distribution

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_guidelines.md

Install cellxgene using a locally built Python distribution package. This is an alternative to installing directly from source.

```shell
make install-dist
```

--------------------------------

### CELLxGENE YAML Configuration Example

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Demonstrates the structure of a YAML configuration file for CELLxGENE. Command-line arguments override values set in this file.

```yaml
# Example YAML configuration:
# server:
#   port: 5005
# logging:
#   level: INFO
#   file: /var/log/cellxgene.log
# compute:
#   cpu_threshold: 0.8
#   memory_threshold: 0.9
# disable_gene_sets_save: false
# disable_custom_colors: false
```

--------------------------------

### Install Release Candidate from Test PyPI

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/release_process.md

Installs the cellxgene build from Test PyPI into a fresh virtual environment. Replace 'x' with the full version string (e.g., '0.9.1-rc.0').

```bash
make install-release-test VERSION=x
```

--------------------------------

### POST /diffexp/obs Full Request Example

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Complete example of a POST request to the /diffexp/obs endpoint, specifying observation index filters for both sets and requesting top 5 differentially expressed variables.

```http
POST /diffexp/obs
{
  "diffexp": {
    "set1": {
      "filter": {
        "obs": { "index": [ [0, 10000] ] }
      }
    },
    "set2": {
      "filter": {
        "obs": { "index": [28448, 4, [88888, 99999] ] }
      }
    },
    "mode": "topN",
    "count": 5
  }
}
```

--------------------------------

### Install Development Version of Cellxgene

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_guidelines.md

Install the cellxgene package from local files for development purposes. This is typically run after building from source.

```shell
make install-dev
```

--------------------------------

### Install cellxgene

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/README.md

Install the cellxgene package using pip. Ensure you are using Python 3.10+ and recommend installing within a conda or virtual environment.

```bash
pip install cellxgene
```

--------------------------------

### Install local cellxgene version

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Installs the current local version of cellxgene in editable mode within the activated virtual environment.

```bash
pip install -e .
```

--------------------------------

### GET /layout/obs, GET /layout/var

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Retrieves the default layout for all observations or variables, including dimensionality and coordinate lists.

```APIDOC
## GET /layout/obs, (_future_) GET /layout/var

### Description
Get the _default_ layout for all observations or (_future_) all variables. Return dimensionality of layout and a coordinate list. The client must be prepared to accept dimensionality different than it natively displays, and should perform a best-effort attempt to display the higher dimensionality layout (eg, create a 2D view of a 3D layout).

### Method
GET

### Endpoint
/layout/{obs|var}

### Response
#### Success Response (200)
- Dimensionality and coordinate list for each observation or variable, where coordinates are encoded as floats [0,1], sorted by index. Example 2D response:
```json
{
  "layout": {
    "ndims": 2,
    "coordinates": [
      [ 0, 0.284483, 0.983744 ],
      [ 1, 0.038844, 0.739444 ],
      // [ obsOrVarIndex, X_coord, Y_coord ],
      // ...
    ]
  }
}
```

#### Error Responses
- 500 Internal Server Error - unprepared data, layout has not been stored in the input data
```

--------------------------------

### Install Release Candidate from Test PyPI

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/release_process.md

Installs the cellxgene build from Test PyPI into a fresh virtual environment. Replace <X>.<Y>.<Z>rc.<#> with the actual version number. You may need to run 'hash -r' to update your shell's executable path.

```bash
VERSION=<X>.<Y>.<Z>rc.<#> make install-release-test
```

--------------------------------

### Install Final Release from PyPI

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/release_process.md

Installs the final cellxgene release from PyPI into a fresh virtual environment. You may need to run 'hash -r' to update your shell's executable path.

```bash
pip install --no-cache-dir cellxgene
```

--------------------------------

### Observation Annotations Response Example

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Example JSON response for fetching observation annotations. Data is sorted by index and includes annotation values or null if not defined.

```json
{
  "names": [
    "tissue_type", "sex", "num_reads", "clusters"
  ],
  "data": [
    [ 0, "lung", "F", 39844, 99 ],
    [ 1, "heart", "M", 83, 1 ],
    [ 49, "spleen", null, 2, "unknown cluster" ]
    // [ obsOrVarIndex, value, value, value, value ],
    // ...
  ]
}
```

--------------------------------

### POST /diffexp/obs Request Body (Observation Filter Example)

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Example of a complex filter for defining an observation subset ('set1'). Filters can include annotation values, minimums, and boolean checks.

```json
{
   "set1": {
       "filter": {
           "obs": {
              "annotation_value": [
                   { "name": "tissue", "values": [lung, heart] },
                   { "name": "num_reads", "min": 1000 },
                   { "name": "tumor", "values": true }
              ]
           }
       }
   }
}
```

--------------------------------

### Get application configuration

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Retrieve the application configuration, including feature availability, compute limits, and display names, by calling the /config endpoint.

```bash
curl http://localhost:5005/api/v0.2/config
```

--------------------------------

### Run Docker Containers

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/testing_environment_for_web_hosting.md

Starts the proxy and cellxgene Docker containers, attaching them to the 'cxg' network. The proxy is exposed on port 80, and cellxgene is configured to serve data from a local directory.

```bash
docker run -d -p 80:80 --network cxg --name proxy proxy
docker run -v "$PWD/example-dataset/:/data/" --name cellxgene --network cxg cellxgene launch --host 0.0.0.0 data/pbmc3k.h5ad
```

--------------------------------

### Run backend tests without starting server

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Executes backend tests using Jest without starting the development server. Requires the REST API to be started separately with a dataset like `pbmc3k.h5ad`. The `JEST_ENV` variable can control Jest's browser environment, and `CXG_URL_BASE` can test non-localhost deployments.

```bash
npm run e2e
```

--------------------------------

### GET /annotations/var

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Retrieves variable annotations.

```APIDOC
## GET /annotations/var

### Description
Retrieves variable annotations.

### Method
GET

### Endpoint
/annotations/var
```

--------------------------------

### GET /layout/obs

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Retrieves the default layout for observations.

```APIDOC
## GET /layout/obs

### Description
Retrieves the default layout for observations.

### Method
GET

### Endpoint
/layout/obs
```

--------------------------------

### GET /annotations/obs

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Retrieves observational annotations.

```APIDOC
## GET /annotations/obs

### Description
Retrieves observational annotations.

### Method
GET

### Endpoint
/annotations/obs
```

--------------------------------

### GET /config

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Retrieves the configuration settings for the cellxgene application.

```APIDOC
## GET /config

### Description
Retrieves the configuration settings for the cellxgene application.

### Method
GET

### Endpoint
/config
```

--------------------------------

### Run backend development server

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Enables FE developers to run the REST API for the development server. It creates and activates a virtual environment, installs cellxgene from the current branch, and launches cellxgene. Requires Python 3.10+, virtual-env, and pip. Run from the project root.

```bash
./scripts/backend_dev
```

--------------------------------

### Run E2E Tests with Hot-Reloaded Client

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_guidelines.md

Execute end-to-end tests against a hot-reloaded client. Ensure the backend server is started correctly, especially with annotations disabled if needed.

```bash
npm run e2e
```

```bash
npm run e2e-annotations
```

--------------------------------

### GET /api/v0.2/config

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Retrieves the application configuration, including feature availability, compute limits, display names, and parameters. This is used by the frontend to adapt the UI.

```APIDOC
## GET /api/v0.2/config

### Description
Fetches the application configuration, including feature flags, interactive limits, and display names.

### Method
GET

### Endpoint
`/api/v0.2/config`

### Parameters
None

### Request Example
```bash
curl http://localhost:5005/api/v0.2/config
```

### Response
#### Success Response (200 OK)
Returns a JSON object containing configuration details.
```json
{
  "config": {
    "features": [
      { "method": "POST", "path": "/cluster/", "available": false },
      { "method": "PUT",  "path": "/layout/obs", "available": true, "interactiveLimit": 10000 },
      { "method": "POST", "path": "/diffexp/obs", "available": true }
    ],
    "displayNames": {
      "engine": "cellxgene 1.3.0",
      "dataset": "pbmc3k.h5ad"
    },
    "parameters": {
      "max-category-items": 1000,
      "annotations_enabled": true,
      "diffexp_may_be_slow": false
    }
  }
}
```
```

--------------------------------

### Run end-to-end tests with backend server

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Starts the backend development server and runs end-to-end tests. This is the primary test run for CI and is useful for checking test passes during frontend development. Depends on `e2e` and `backend-dev` targets. Run from `$PROJECT_ROOT/client`.

```bash
make smoke-test
```

--------------------------------

### Serve the client javascript independently

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

This script serves the current client javascript independently from the server code. Requires the server to be running and `make ci` to install node modules. Run from `$PROJECT_ROOT/client`.

```bash
make start-frontend
```

--------------------------------

### POST /diffexp/obs Request Body (topN mode)

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Example request body for generating top N differentially expressed variables. Specify the number of results with 'count'.

```json
{
  "mode": "topN",
  "count": N
}
```

--------------------------------

### Summarize Variable Data (GET/POST)

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Computes a summary statistic across variables for a filtered set of observations. Useful for computing mean expression across a selected cell population. The GET method is suitable for shorter queries, while POST allows for longer filter queries via a form-encoded body.

```bash
# GET: compute mean expression across all cells for genes matching a filter
curl -H "Accept: application/octet-stream" \
     "http://localhost:5005/api/v0.2/summarize/var?method=mean&obs:louvain=NK%20cells" \
     --output summary.fbs
```

```bash
# POST: same query via form-encoded body (allows longer filter queries)
curl -X POST \
     -H "Accept: application/octet-stream" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data "method=mean&obs:louvain=CD4%20T%20cells" \
     "http://localhost:5005/api/v0.2/summarize/var?key=<query_hash>" \
     --output summary.fbs
```

```text
# Error: unsupported method (only "mean" is currently supported)
# HTTP 400 Bad Request
```

--------------------------------

### Build the entire cellxgene application

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Use this command from the project root to build both the client and server components of the application.

```bash
make build
```

--------------------------------

### Launch CELLxGENE with a Configuration File

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Use this command to launch the CELLxGENE server with a specified YAML configuration file.

```bash
# Launch using this config file
cellxgene launch --config-file cellxgene_config.yaml
```

--------------------------------

### Create Release Candidate

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/release_process.md

Run this command to bump the version and create a release candidate. Use 'major', 'minor', or 'patch' to specify the type of release.

```bash
make create-release-candidate PART=[major | minor | patch]
```

--------------------------------

### Uninstall cellxgene from virtual environment

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Uninstalls cellxgene from the virtual environment if it is currently installed. This command is part of a sequence to ensure a clean installation.

```bash
yes | pip uninstall cellxgene || true
```

--------------------------------

### Launch cellxgene with specific dataset and options

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Demonstrates how to launch cellxgene with a specific dataset and custom options using the `backend_dev` script.

```bash
DATASET=<dataset path> ./scripts/backend_dev
```

```bash
CXG_OPTIONS='--disable-annotations' ./scripts/backend_dev
```

--------------------------------

### GET Request for Annotation Value Filtering

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Use this format for GET requests to filter data by annotation values. Multiple values for the same annotation are ORed, while different annotations are ANDed.

```http
GET /data?obs:tissue=lung&obs:tissue=heart&obs:num_reads=1000,*
```

--------------------------------

### Build client for server development

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

This command builds the client and places the output directly into the source tree, intended solely for server-side development workflows.

```bash
make build-for-server-dev
```

--------------------------------

### Launch CELLxGENE with a Config File

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Demonstrates how to launch the CELLxGENE server using a specified configuration file.

```APIDOC
## Launch using this config file
```bash
cellxgene launch --config-file cellxgene_config.yaml
```
```

--------------------------------

### Programmatic Configuration with AppConfig

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Shows how to use the `AppConfig` class in Python to configure and launch the CELLxGENE server programmatically, including updating settings, loading from YAML, and building the Flask app.

```APIDOC
## Python: `AppConfig` Programmatic Configuration

The `AppConfig` class provides a Python API for configuring and launching the server programmatically, useful for embedding CELLxGENE in other Flask applications or scripting deployments.

```python
from server.common.config.app_config import AppConfig
from server.app.app import Server

# Create and configure the app
app_config = AppConfig()

# Update server-level settings
app_config.update_server_config(
    app__host="localhost",
    app__port=5005,
    app__verbose=True,
    app__debug=False,
    single_dataset__datapath="./data/pbmc3k.h5ad",
    single_dataset__title="PBMC 3k",
    single_dataset__about="https://example.com",
    adaptor__anndata_adaptor__backed=False,
)

# Update dataset-level settings
app_config.update_dataset_config(
    presentation__max_categories=500,
    presentation__custom_colors=True,
    user_annotations__enable=True,
    user_annotations__local_file_csv__directory="./annotations/",
    embeddings__names=["umap", "tsne"],
    diffexp__enable=True,
    diffexp__lfc_cutoff=0.01,
    X_approximate_distribution="auto",
)

# Load from a YAML config file (then override with programmatic settings)
app_config.update_from_config_file("./config.yaml")
app_config.update_server_config(app__port=9000)  # override port from file

# Set a single nested config value by path
app_config.update_single_config_from_path_and_value(
    ["server", "app", "flask_secret_key"], "my-secret-key"
)

# Validate and complete configuration
def log_message(msg):
    print(f"[config] {msg}")

app_config.complete_config(messagefn=log_message)

# Dump config to YAML
app_config.write_config("./current_config.yaml")

# Build and run the Flask app
server = Server(app_config)
server.app.run(
    host=app_config.server_config.app__host,
    port=app_config.server_config.app__port,
    debug=app_config.server_config.app__debug,
    threaded=True,
    use_reloader=False,
)
```
```

--------------------------------

### Run All Unit Tests

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_guidelines.md

Execute all unit tests for the project. Ensure you are in the project root directory before running.

```shell
make dev-env
make unit-test
```

--------------------------------

### Expression Data JSON Response Example

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Example JSON response for fetching expression data, filtered by observation annotation. Data is organized in observation-major order and includes secondary axis indices.

```json
{
  "var": [ [ 0, 20000 ] ],
  "obs": [
    [ 1, 39483, 3902, 203, 0, 0, ..., 28 ],   // length == 20001
    // [ obsIndex, value1, value2, ..., value20000 ]
    // ...
  ]
}
```

--------------------------------

### Build the cellxgene client

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Run this command from the project root to specifically build the client-side application using webpack.

```bash
make build-client
```

--------------------------------

### Annotation Value Filters (GET)

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Filter data by annotation values using URL query parameters for GET requests. Annotation names are prefixed with 'obs:' or 'var:'. Enumerated values are comma-separated lists, and scalar values are specified as ranges.

```APIDOC
## GET /data

### Description
Retrieve data subsets filtered by annotation values.

### Method
GET

### Endpoint
/data

### Query Parameters
- **obs:name** (string) - Annotation name for observation filters.
- **var:name** (string) - Annotation name for variable filters.
- **values** (string) - Comma-separated list of enumerated values (e.g., `lung,heart`).
- **range** (string) - Range for scalar values (e.g., `1000,*` for >= 1000).

### Example
```
GET /data?obs:tissue=lung&obs:tissue=heart&obs:num_reads=1000,*
```
```

--------------------------------

### Build Python distribution for PyPI

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

This command, run from the project root, builds the code and then creates a source distribution (sdist) for uploading to PyPI.

```bash
make pydist
```

--------------------------------

### Run Client-Only Unit Tests

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_guidelines.md

Execute unit tests specifically for the client code. Navigate to the 'client' directory first.

```shell
cd client
make unit-test
```

--------------------------------

### Create Release Candidate (Patch)

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/release_process.md

Run this make command on the release branch to increment the patch version and create the initial release candidate (e.g., '0.9.1-rc.0').

```bash
make create-release-candidate PART=patch
```

--------------------------------

### GET /schema

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Retrieves the schema definition for the cellxgene data.

```APIDOC
## GET /schema

### Description
Retrieves the schema definition for the cellxgene data.

### Method
GET

### Endpoint
/schema
```

--------------------------------

### Run Client Smoke Tests

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_guidelines.md

Execute the client smoke test suites from the `client` directory. Use `smoke-test-annotations` for the annotations test suite.

```bash
make smoke-test
```

```bash
make smoke-test-annotations
```

--------------------------------

### Run all unit tests for the client

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Executes all unit tests for the client, excluding tests in the e2e folder. This is used for CI checks. Run from `$PROJECT_ROOT/client`.

```bash
make unit-test
```

--------------------------------

### Activate virtual environment

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Activates the 'cellxgene' virtual environment.

```bash
source cellxgene/bin/activate
```

--------------------------------

### Upload Release Candidate to Test PyPI

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/release_process.md

Uploads the current release candidate to Test PyPI for verification. Ensure you have the necessary PyPI and Test PyPI credentials.

```bash
make release-candidate-to-test-pypi
```

--------------------------------

### GET /health

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Health check endpoint that returns the server status and version. This endpoint does not require dataset access.

```APIDOC
## GET /health

### Description
Checks the health status of the cellxgene server.

### Method
GET

### Endpoint
`/health`

### Parameters
None

### Request Example
```bash
curl http://localhost:5005/health
```

### Response
#### Success Response (200 OK)
Returns server status and version information.
```json
{
  "status": "pass",
  "version": "1",
  "releaseID": "1.3.0"
}
```

#### Failed Response (400 Bad Request)
Returned if the dataset is not accessible.
```json
{
  "status": "fail",
  "version": "1",
  "releaseID": "1.3.0"
}
```
```

--------------------------------

### Annotate using GPU acceleration

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Leverage GPU acceleration for faster annotation when available. This requires a compatible GPU and drivers.

```bash
cellxgene annotate input.h5ad \
  --model-url ./models/cell_type_model.tar.gz \
  --use-gpu \
  --output-h5ad-file annotated.h5ad
```

--------------------------------

### Create cellxgene virtual environment

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Creates a Python virtual environment named 'cellxgene' for the project.

```bash
python3.12 -m venv cellxgene
```

--------------------------------

### GET /api/v0.2/schema

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Returns the data schema for the loaded dataset, including matrix dimensions, annotation names, types, and categorical values for observations and genes.

```APIDOC
## GET /api/v0.2/schema

### Description
Retrieves the schema of the loaded dataset, detailing matrix dimensions and annotation information.

### Method
GET

### Endpoint
`/api/v0.2/schema`

### Parameters
None

### Request Example
```bash
curl http://localhost:5005/api/v0.2/schema
```

### Response
#### Success Response (200 OK)
Returns a JSON object describing the dataset schema.
```json
{
  "schema": {
    "dataframe": {
      "nObs": 2638,
      "nVar": 1838,
      "type": "float32"
    },
    "annotations": {
      "obs": {
        "index": "obs_index",
        "columns": [
          { "name": "louvain", "type": "categorical", "categories": ["CD4 T cells", "NK cells", "B cells"] },
          { "name": "n_genes",  "type": "int32" },
          { "name": "percent_mito", "type": "float32" }
        ]
      },
      "var": {
        "index": "var_index",
        "columns": [
          { "name": "n_cells", "type": "int32" }
        ]
      }
    },
    "layout": {
      "obs": [
        { "name": "umap", "type": "float32", "dims": ["umap_0", "umap_1"] },
        { "name": "tsne", "type": "float32", "dims": ["tsne_0", "tsne_1"] }
      ]
    }
  }
}
```
```

--------------------------------

### Clean all generated files and node modules

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Execute this from the project root to perform a comprehensive clean, removing all generated files and node modules. Note that subsequent builds may take longer.

```bash
make clean
```

--------------------------------

### Run End-to-End Smoke Tests

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_guidelines.md

Execute end-to-end smoke tests. Navigate to the 'client' directory before running.

```shell
cd client
make smoke-test
```

--------------------------------

### GET /schema API Endpoint

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Fetches the schema definition for the dataframe and its annotations (obs and var). This includes dimensionality, data types, and categorical values.

```http
GET /schema
--
200
{
  "schema": {
    "dataframe": {
      "nObs": 383,
      "nVar": 19944,
      "type": "float32"
    },
    "annotations": {
      "obs": [
        { "name": "name", "type": "string" },
        { "name": "tissue_type", "type": "string" },
        { "name": "num_reads", "type": "int32" },
        { "name": "sample_name", "type": "string" },
        {
          "name": "clusters",
          "type": "categorical",
          "categories"=[ 99, 1, "unknown cluster" ]
        },
        { "name": "QScore", "type": "float32" }
      ],
      "var": [
        { "name": "name", "type": "string" },
        { "name": "gene", "type": "string" }
      ]
    }
  }
}
```

--------------------------------

### Add Javascript Breakpoint with ndb

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/e2e_tests.md

Insert 'debugger;' into your test code to pause execution at that point when running tests with ndb. Ensure ndb is installed globally.

```javascript
debugger
```

--------------------------------

### GET /api/v0.2/annotations/obs

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Fetches observation (cell) annotation columns as a binary FlatBuffers matrix. Supports fetching all annotations or a filtered subset via query parameters.

```APIDOC
## GET /api/v0.2/annotations/obs

### Description
Retrieves observation annotation columns in a binary FlatBuffers format.

### Method
GET

### Endpoint
`/api/v0.2/annotations/obs`

### Parameters
#### Query Parameters
* `annotation-name` (string, optional): Comma-separated list of annotation names to filter the results.

### Request Example
```bash
# Fetch all obs annotations (binary FlatBuffers response)
curl -H "Accept: application/octet-stream" \
     http://localhost:5005/api/v0.2/annotations/obs \
     --output obs_annotations.fbs
```

### Response
#### Success Response (200 OK)
Returns a binary FlatBuffers matrix containing the requested observation annotations.
```

--------------------------------

### Update Dockerfile for Local Build

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/testing_environment_for_web_hosting.md

Modifies the cellxgene Dockerfile to install from a local source distribution (sdist) instead of PyPI. This is useful for testing local code changes.

```dockerfile
FROM ubuntu:bionic

ENV LC_ALL=C.UTF-8
ENV LANG=C.UTF-8
COPY [ "dist/",    "/cellxgene/dist/" ]

RUN apt-get update && \
    apt-get install -y build-essential libxml2-dev python3-dev python3-pip zlib1g-dev && \
    pip3 install /cellxgene/dist/cellxgene-0.5.1.tar.gz

ENTRYPOINT ["cellxgene"]
```

--------------------------------

### Release Directly to Prod

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/release_process.md

This command uploads the release directly to the production PyPI. Use with caution as it bypasses Test PyPI and is considered a 'DANGER' option.

```bash
make release-directly-to-prod
```

--------------------------------

### Run End-to-End Tests as on CI

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_guidelines.md

Execute end-to-end tests using the exact command and environment configuration used on the Continuous Integration (CI) platform.

```shell
JEST_ENV=prod make pydist install-dist dev-env smoke-test
```

--------------------------------

### Add data-testid Attribute Example

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/e2e_tests.md

Use `data-testid` or `data-testclass` attributes for selectors to make tests more robust and self-documenting. This avoids issues with positional, classname, or ID selectors.

```html
<div data-testid="test-id" />
```

```html
<div data-testclass="test-class" />
```

--------------------------------

### Create Docker Network

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/testing_environment_for_web_hosting.md

Creates a Docker network for containers to communicate. This is the first step in setting up the isolated environment.

```bash
docker network create cxg
```

--------------------------------

### Fetch observation annotations

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Download observation (cell) annotations as a binary FlatBuffers matrix. Use the `-H "Accept: application/octet-stream"` header and redirect output to a file.

```bash
# Fetch all obs annotations (binary FlatBuffers response)
curl -H "Accept: application/octet-stream" \
     http://localhost:5005/api/v0.2/annotations/obs \
     --output obs_annotations.fbs
```

--------------------------------

### Debug Failing End-to-End Tests with ndb

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_guidelines.md

Use the 'ndb' tool to debug failing end-to-end tests by setting breakpoints in the JavaScript code. Ensure 'ndb' is installed globally.

```shell
npm install -g ndb
```

```shell
ndb make e2e
```

```shell
ndb npm run e2e
```

--------------------------------

### Run Server Unit Tests

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_guidelines.md

Execute unit tests for the server-side code. This can be done either from the 'server' directory or the project root.

```shell
make dev-env
make unit-test
```

```shell
make unit-test-server
```

--------------------------------

### Filter Syntax Reference

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Explains the filter syntax used in CELLxGENE's REST API for querying data, applicable to both GET query parameters and PUT/POST request bodies.

```APIDOC
## Filter Syntax Reference

CELLxGENE's REST API uses a consistent filter format across multiple endpoints. Filters can be specified as GET query parameters or as a JSON body in PUT/POST requests.

```bash
# --- GET query parameter filter syntax ---
# Format: <axis>:<annotation_name>=<value>
# Axis must be "obs" (cells) or "var" (genes)

# Categorical / string value filter (ORed for repeated names)
GET /api/v0.2/data/var?obs:tissue=lung&obs:tissue=heart

# Numeric range filter (use * for open-ended bound)
GET /api/v0.2/data/var?obs:num_reads=1000,*
GET /api/v0.2/data/var?obs:num_reads=*,5000
GET /api/v0.2/data/var?obs:num_reads=1000,5000

# Combined filters (ANDed across different annotation names)
GET /api/v0.2/data/var?obs:tissue=lung&obs:num_reads=1000,*
```
```

--------------------------------

### GET /config

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Retrieves configuration information for the cellxgene engine. This includes feature availability, interactive compute limits, display names for the engine and dataset, and system-wide configuration parameters.

```APIDOC
## GET /config

### Description
Configuration information to assist in front-end adaptation to underlying engine, available functionality, interactive time limits, etc.

### Method
GET

### Endpoint
/config

### Response
#### Success Response (200)
- `config` (object) - Contains configuration details.
  - `features` (array) - Encoded as an array of features, each with a method, path, and availability status. Optional `interactiveLimit` may be included.
  - `displayNames` (object) - Contains `engine` and `dataset` display names.
  - `parameters` (object) - System configuration parameters as key/value pairs.

#### Response Example
```json
{
  "config": {
    "features": [
      { "method": "POST", "path": "/cluster/", "available": false },
      {
        "method": "PUT",
        "path": "/layout/obs",
        "available": true,
        "interactiveLimit": 10000
      },
      { "method": "PUT", "path": "/layout/var", "available": false }
    ],
    "displayNames": {
      "engine": "ScanPy version 1.33",
      "dataset": "/home/joe/mouse/blorth.csv"
    },
    "parameters": {
      "max-category-items": 1000,
      "verbose": false
    }
  }
}
```
```

--------------------------------

### Launch cellxgene

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/developer_scripts.md

Launches the cellxgene application. This command typically requires a dataset path as the last parameter.

```bash
cellxgene launch
```

--------------------------------

### Annotate using a local model directory

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Use this command to annotate a .h5ad file with a local model. Ensure the model path is correct.

```bash
cellxgene annotate input.h5ad \
  --model-url /path/to/model.tar.gz \
  --output-h5ad-file annotated.h5ad
```

--------------------------------

### POST /diffexp/obs Response Body (Success)

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Example of a successful 200 response body containing differential expression statistics. Values are ordered as varIndex, logfoldchange, pVal, pValAdj.

```json
{
  "diffexp": [
    [ 328, -2.569489, 2.655706e-63, 3.642036e-57 ],
    // [ varIdx, logfoldchange, pVal, pValAdj ],
    // ...
  ]
}
```

--------------------------------

### POST /diffexp/obs Request Body (varFilter mode)

Source: https://github.com/chanzuckerberg/cellxgene/blob/main/dev_docs/REST_API.md

Example request body for generating differential expression for a caller-provided variable filter. The 'varFilter' object specifies the filter criteria.

```json
{
  "mode": "varFilter",
  "varFilter": {
    "filter": {
      "var": {
        "annotation_value": [
          { "name": "gene", "values": [ "FOXP2", "ACTN1" ] }
        ]
      }
    }
  }
}
```

--------------------------------

### Get dataset schema

Source: https://context7.com/chanzuckerberg/cellxgene/llms.txt

Fetch the data schema for the loaded dataset, including matrix dimensions, annotation names, types, and categorical values. This is useful for understanding the dataset's structure.

```bash
curl http://localhost:5005/api/v0.2/schema
```