HIV molecular immunology database
Immunology API - API access for the LANL HIV Molecular Immunology Database
This documentation refers to API version v1.0.2.
wget -O- 'https://www.hiv.lanl.gov/mojo/immunology/api/v1/epitope/ctl?id=42'The HIV Immunology API provides a public interface to retrieve data from the LANL HIV Molecular Immunology database. The returned data are formatted as JSON.
All endpoints are relative to the server installation path. For example, if the API is installed at https://www.hiv.lanl.gov/mojo/immunology, then the full path of /api/v1/epitope/ctl would be https://www.hiv.lanl.gov/mojo/immunology/api/v1/epitope/ctl.
The following endpoints are available:
Search {table} in the immunology database and return the matching epitope records.
The {table} and at least one search parameter must be supplied; otherwise an error occurs. If multiple search parameters are supplied, then all of them must be satisfied.
table
One of ctl, helper, or ab. The HIV Molecular Immunology Database is organized into three main tables according to the immune respnse: CTL/CD8+ (ctl), T-helper/CD4+ (helper), and Antibodies (ab). The T-cell tables are ctl and helper; the antibody table is ab.
author
Search for epitopes by the name of an author of a reference.
author_first author_last
Restrict search by author to only first authors or only last authors respectively.
au_filter
Filter the results to include only notes and references with the matching author. Requires author. Antibody only.
binding_type
Search for epitopes by ID of the antibody binding type. See "/api/v1/list/binding_type/{table}" to obtain the list of binding types and IDs. Antibody only.
cite
Search for epitopes by the citation key of a reference, E.g., Doe2008.
dna_end
Search for epitopes before this DNA location.
dna_start
Search for epitopes after this DNA location.
dna_start and dna_end search for epitopes by DNA location. The epitope is matched if the contig overlaps dna_start–dna_end.
end
Search for epitopes before this protein location; requires protein or protein_name. See also start.
start and end search for epitopes by protein location. The epitope is matched if the location overlaps start–end.
epitope
Search for epitopes by epitope amino acid sequence. The match succeeds if the query sequence is in the epitope sequence. The wildcard characters ? and * may be use to specify one or any number of arbirary amino acids respectively.
epitope_name
Search for epitopes by name.
hla
Search for epitopes by MHC/HLA. T cell only.
hla_id
Search for epitopes by MHC/HLA ID. T cell only. See "/api/v1/list/hla/{table}" to obtain the list of HLAs and IDs.
id
Search for epitopes by database ID.
immunogen
Search for epitopes by immunogen ID. See "/api/v1/list/immunogen/{table}" to obtain the list of immunogens and IDs.
isotype
Search for epitopes by isotype ID. See "/api/v1/list/isotype/{table}" to obtain the list of isotypes and IDs. Antibody only.
keyword
Search for epitopes by keyword ID. See "/api/v1/list/keyword/{table}" to obtain the list of keywords and IDs.
kw_filter
Filter the results to include only notes and references with the matching keyword. Requires keyword. Antibody only.
mab_name
Search for epitopes by the name (or alias) of the monoclonal antibody (mAb). Antibody only.
note
Search for epitopes by the text in a note. The search is limited to a single word or phrase. Full-text search is not supported.
note_filter
Filter the results to include only notes and references matching note. Requires note. Antibody only.
outcome
Search for epitopes by outcome (experimental methods or outcomes measures) ID. See "/api/v1/list/outcome/{table}" to obtain the list of outcomes and IDs. T cell only.
protein
Search for epitopes by protein ID. See "/api/v1/list/protein/{table}" to obtain the list of proteins and IDs.
protein_name
Search for epitopes by protein name.
pubmed_id
Search for epitopes by the PubMed ID of a reference.
spans
Search for epitopes at this protein location; requires protein or protein_name.
species
Search for epitopes by the species ID the immune response was observed in. See "/api/v1/list/species/{table}" to obtain the list of species and IDs.
start
Search for epitopes after this protein location; requires protein or protein_name. See also end.
subtype
Search for epitopes by viral subtype ID. See "/api/v1/list/subtype/{table}" to obtain the list of subtypes and IDs.
vaccine_adjuvant
Search for epitopes by vaccine adjuvant ID. Requires that the immunogen be a vaccine. See "/api/v1/list/vaccine_adjuvant/{table}" to obtain the list of vaccine adjuvants and IDs.
vaccine_component
Search for epitopes by vaccine component ID. Requires that the immunogen be a vaccine. See "/api/v1/list/vaccine_component/{table}" to obtain the list of vaccine components and IDs.
vaccine_strain
Search for epitopes by vaccine strain ID. Requires that the immunogen be a vaccine. See "/api/v1/list/vaccine_strain/{table}" to obtain the list of vaccine strains and IDs.
vaccine_type
Search for epitopes by vaccine type ID. Requires that the immunogen be a vaccine. See "/api/v1/list/vaccine_type/{table}" to obtain the list of vaccine types and IDs.
Retrieve the list of antibody binding types and IDs present in {table}. Antibody only.
Retrieve the list of country names and ISO country codes present in {table}.
Retrieve the list of HLA/MHC types and IDs present in {table}. T cell only.
Retrieve the list of immunogens and IDs present in {table}.
Retrieve the list of isotypes and IDs present in {table}. Antibody only.
Retrieve the list of keywords and IDs present in {table}.
Retrieve the list of outcomes (experimental methods and outcomes measured) and IDs present in {table}.
Retrieve the list of proteins and IDs present in {table}.
Retrieve the list of species and IDs present in {table}.
Retrieve the list of subtypes and IDs present in {table}.
Retrieve the list of vaccine adjuvants and IDs present in {table}.
Retrieve the list of vaccine components and IDs present in {table}.
Retrieve the list of vaccine strains and IDs present in {table}.
Retrieve the list of vaccine types and IDs present in {table}.
Search the patient table in the immunology database and return the matching patient records.
Retrieve the list of patient ethnicities.
Retrieve the list of patient HLA/MHC types and IDs.
Retrieve the list patient infection country names and codes.
Retrieve the list of patient infection years.
Retrieve the list patient HIV progression codes and names.
Retrieve the list patient HIV risk factor codes and names.
Retrieve the list patient sexes.
Retrieve the list patient species.
At least one search parameter must be supplied; otherwise an error occurs. If multiple search parameters are supplied, then all of them must be satisfied.
ethnicity
Search for patients by ethnicity.
id
Search for patients by database ID.
infection_country
Search for patients by country where infected.
infection_year
Search for patients by year when infected.
note
Search for patients by the text in a note. The search is limited to a single word or phrase. Full-text search is not supported.
patient_code
Search for patients by code as published in the literature.
patient_code_exact
If true, find only exact matches to patient_code.
patient_hla_id
Search for patients by MHC/HLA ID.
patient_sex
Search for patients by sex.
progression
Search for patients by HIV progression status.
risk_factor
Search for patients by HIV risk factor.
species
Search for patients by species.
The information below explains what the database contains and the meaning of terms used in the search interfaces.
T-cell epitopes are categorized into cytotoxic T lymphocytes (CTL/CD8+) and helper T lymphocytes (T-helper/CD4+). The database organization for CTL/CD8+ and T-helper/CD4+ is identical, so they are described together.
The T cell databases include tables and associated references of HIV-specific T-cell epitopes arranged according to the location of the proteins in the HIV-1 genome. We attempted to make this section as comprehensive as possible, requiring that the epitope be contained within a defined region of a maximum of 30 amino acids, but not that the optimal boundaries be defined. Studies that were based on the analysis of whole proteins are described at the end of each protein section. The same epitope can have multiple entries, and each entry represents a single publication in this section of the database.
Recent studies utilize multiple functions attributed to T cells to define responses, and the simple distinctions of cytotoxic T cells and helper T cells have become blurred as more is learned about the range of responses triggered in CD4- and CD8-positive T cells responding to antigenic stimulus. When adding the most recent studies, we have tried to place T-cell responses in a reasonable manner into our traditional CTL and helper T-cell sections, and to specify the assay used to measure the response in each study.
Each T cell epitope has a multi-part basic entry:
Record number
A unique number assigned by the database, in approximate order of entry. Please refer to this number if you have any comments or questions about an entry.
HXB2 Location
The viral strain HXB2 (GenBank Accession Number K03455) is used as a reference strain throughout this publication. The position of the defined epitope location relative to the sequence of the HXB2 protein is indicated. The numbering in this table corresponds to the protein maps. Because of HIV-1 variation the epitope may not actually be present in HXB2, rather the position in HXB2 indicates the position aligned to the epitope. HXB2 was selected as the reference strain because so many studies use HXB2, and because crystal structures for HXB2-related proteins are available.
Author Location
The amino acid positions of the epitope boundaries and the reference sequence are listed as given in the primary publication. Frequently, these positions as published are imprecise, and do not truly correspond to the numbering of the sequence, but they provide a reasonable guide to the peptide's approximate location in the protein. Also, in many cases the reference sequence identification was not provided, and in such cases it is not possible to use these numbers to specify precise locations.
Subtype
The subtype under study, generally not specified for B subtype.
Epitope Sequence
The amino acid sequence of the epitope of interest as defined in the reference. On occasions when only the position numbers and not the actual peptide sequence was specified in the original publication, we try to fill in the peptide sequence based on the position numbers and reference strain. If the sequences were numbered inaccurately by the primary authors, or if we made a mistake in this process, we may misrepresent the amino acid sequence. Because of this uncertainty, epitopes that were not explicitly written in the primary publication are followed by a question mark (?) in the table.
Epitope Name
If the epitope has a name attributed by the publication, it is recorded here, e.g. “SL9”.
Species (MHC/HLA)
The species responding and MHC or HLA specificity of the epitope.
Immunogen
The original stimulus of the T-cell response. Often this is an HIV-1 infection. If a vaccine was used as the original antigenic stimulation, not a natural infection, this is noted on a separate line, and additional information about the vaccine antigen is provided as available.
Keywords
The keyword field helps identify entries of particular interest.
Reference
The primary reference (sometimes two or more directly related studies are included).
Notes
Brief comments explain the context in which the epitope was studied and what was learned about the epitope in a given study.
The antibody database summarizes HIV-specific antibodies (Abs) arranged sequentially according to the location of their binding domain, organized by protein. We attempted to make this section as comprehensive as possible. For the monoclonal (MAbs) capable of binding to linear peptides, we require that the binding site be contained within a region of 30 or so amino acids to define the epitope, but not that the precise boundaries be defined. MAbs that do not bind to defined linear peptides are grouped by category at the end of each protein. Antibody categories, for example CD4 binding site (CD4BS) antibodies, are also noted in the index at the beginning of this section. Studies of polyclonal Ab responses are also included. Responses that are just characterized by binding to a protein, with no known specific binding site, are listed at the end of each protein.
Each MAb or polyclonal response has a multi-part basic entry:
Record number
A unique number assigned by the database, in approximate order of entry. Please refer to this number if you have any comments or questions about an entry.
MAb name
The name of the monoclonal antibody with synonyms in parentheses. MAbs often have several names. For example, punctuation can be lost and names are often shortened (“M-70” in one paper can be “M70” in another). Polyclonal responses are listed as “polyclonal” in this field.
HXB2 Location
Position of the Ab binding site relative to the viral strain HXB2 (GenBank Accession Number K03455), which is used as a reference strain throughout this publication. The numbering in this table corresponds to the protein maps. Because of HIV-1 variation the epitope may not actually be present in HXB2, rather the position in HXB2 indicates the position aligned to the epitope. HXB2 was selected as the reference strain because so many studies use HXB2, and because crystal structures for HXB2-related proteins are often available.
Author Location
The amino acid positions of the epitope boundaries and the reference sequence used to define the epitope are listed as given in the primary publication. Frequently, these positions as published are imprecise, and do not truly correspond to the numbering of the sequence, but they provide a reasonable guide to the peptide's approximate location in the protein. Also, in many cases, position numbers were provided but the reference sequence identification was not. Because of HIV-1’s variability, position numbers require a reference strain to be meaningful. Binding sites that cannot be defined through peptide binding or interference studies are labeled as discontinuous. The approximate location on the protein, sequence number, and reference sequence are listed.
Sequence
The amino acid sequence of the binding region of interest, based on the reference strain used in the study defining the binding site. On occasions when only the position numbers and not the actual peptide sequence was specified in the original publication, we tried to fill in the peptide sequence based on the position numbers and reference strain. If the sequences were numbered inaccurately by the primary authors, or if we made a mistake in this process, we may have misrepresented the binding site's amino acid sequence. Because of this uncertainty, epitopes that were not explicitly written in the primary publication, that we determined by looking up the reference strain and the numbered location, are followed by a question mark in the table.
Neutralizing
L: neutralizes lab strains.
P: neutralizes at least some primary isolates or pseudoviruses.
P (tier 1): neutralizes tier 1 isolates (easily neutralized strains).
P (tier 2): neutralizes at least some tier 2 isolates (moderately difficult strains).
no: does not neutralize.
No information in this field means that neutralization was either not discussed or unresolved in the primary publications referring to the MAb.
Immunogen
The antigenic stimulus of the original B cell response. Often this is an HIV-1 infection. If a vaccine was used as the original antigenic stimulation, not a natural infection, this is noted on a separate line, and additional information about the vaccine antigen is provided as available.
Species(Isotype)
The host that the antibody was generated in, and the isotype of the antibody.
Donor
Information about an antibody or how to obtain it, as well as to provide credit.
References
All publications that we could find that refer to the use of a specific monoclonal antibody. First is a list of all references. Some of the earlier references include notes with additional details, although we have tried to keep the entries self-contained since 1997.
Notes
Describe the context of each study, and what was learned about the antibody in the study.
This is a brief description of the database fields in the search and results pages. Please see above for more details.
HIV protein
The protein for which the epitope was defined.
Defined epitopes
Epitopes or reactive peptides that have a known protein sequence.
Undefined epitopes
Reactive peptides or proteins for which the binding site is not exactly known. This could either be because it was unspecified by the authors (e.g., a polyclonal response to Env) or because it is a conformational epitope for an antibody that binds to discontinuous amino acids in the folded protein.
HXB2 protein location
The HXB2 protein coordinates within the protein selected in the “HIV protein” field above. Be sure to enter a HIV protein when using protein location search. This finds epitopes that overlap any residue of the specified location. To find epitopes that contain a single specific residue, you can enter the same coordinate number in both boxes.
HXB2 DNA location
The HXB2 DNA coordinates. Results will include all epitopes that overlap the coordinates of the query. If multiple proteins overlap at the DNA coordinates selected, you can use the “HIV protein” field to narrow the search to the protein of interest.
Epitope
The amino acid sequence of the epitope or short reactive peptide. Finds epitopes that contain the query sequence. Results will be the same length or longer than the query.
Epitope name
Epitope name as reported by the authors.
Record number
A unique number assigned by the database, in approximate order of entry. Please refer to this number if you have any comments or questions about an entry.
Subtype
The subtype under study, generally not specified for B subtype.
Immunogen
The stimulus of the original immune response under study.
Vaccine details
Data included only if the immunogen was a vaccine.
Vaccine type
The vaccine construct and boost.
Vaccine strain
The strain of HIV or SHIV used for the vaccine antigen.
Vaccine component
The HIV protein (complete or partial) included in the vaccine.
Adjuvant
Traditional adjuvants or chemokines.
Species
The species in which the immune response was stimulated.
MHC/HLA
The MHC (or HLA) presenting molecules as described by the primary authors.
Author
Any one author from primary publication. Specify as Surname and Initials, e.g., “Brander C”, “Korber BT” or “Haynes”.
Country
The country where the samples were obtained.
Keywords
Searchable topics that can be used to narrow your search. Each reference is assigned one or more keywords that characterize the information provided in that paper.
Experimental methods (outcome)
Methods used by the authors to test the immune response.
MAb name
Name of monoclonal antibody or “polyclonal” if a general response is being studied. The name is usually given as the authors defined it in the paper that described the antibody’s isolation.
HXB2 location
Epitope position numbers in the HXB2 reference strain.
Author location
Epitope location as reported by the authors. Includes strain and subtype from which the epitope was derived.
Epitope name
Epitope name as reported by the authors.
Ab binding type
Classes of antibodies have shared properties with regard to their binding site and can be grouped; for example they might bind to a similar region (like V3) or near a common functional domain (like the CD4 binding site, CD4BS).
Neutralizing
Neutralizing properties of the antibody—often different studies involving the same antibody will report this differently, so this classification is somewhat subjective.
Research contact (donor)
The person or lab that generated or provides the antibody.
Notes
Brief comments explain the context in which the epitope was studied and what was learned about the epitope in a given study.
The formal OpenAPI specification for this API is available via "api/v1", E.g., https://www.hiv.lanl.gov/mojo/immunology/api/v1. An HTML rendering is available via "api/v1.html", E.g., https://www.hiv.lanl.gov/mojo/immunology/api/v1.html.
There are no known bugs in this app. Please report problems to the author at mailto:immuno@lanl.gov
HIV Molecular Immunology website https://www.hiv.lanl.gov/content/immunology
OpenAPI/Swagger https://swagger.io
LANL T-6 HIV Databases mailto:immuno@lanl.gov
Copyright © 2020–2021 Triad National Security, LLC. All rights reserved.
LA-UR-21-22506
Los Alamos National Laboratory, an affirmative action/equal opportunity employer, is operated by Triad National Security, LLC for the National Nuclear Security Administration of U.S. Department of Energy under contract 89233218CNA000001. Los Alamos National Laboratory strongly supports academic freedom and a researcher’s right to publish; as an institution, however, the Laboratory does not endorse the viewpoint of a publication or guarantee its technical correctness.