### Setup local development environment

Source: https://github.com/jvfe/pytrials/blob/master/docs/contributing.md

Commands to clone the repository, create a virtual environment, and install the package in development mode.

```shell
git clone git@github.com:your_name_here/pytrials.git
mkvirtualenv pytrials
cd pytrials/
python setup.py develop
```

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

### Install PyTrials library

Source: https://github.com/jvfe/pytrials/blob/master/docs/readme.md

The installation command for the PyTrials package via pip.

```bash
pip install pytrials
```

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

### GET /get_full_studies

Source: https://github.com/jvfe/pytrials/blob/master/README.rst

Retrieves full study information based on a search expression from clinicaltrials.gov.

```APIDOC
## GET /get_full_studies

### Description
Retrieves a list of full clinical trial studies matching the provided search criteria.

### Method
GET

### Endpoint
get_full_studies(search_expr, max_studies)

### Parameters
#### Query Parameters
- **search_expr** (string) - Required - The search expression to filter clinical trials (e.g., 'Coronavirus+COVID').
- **max_studies** (integer) - Optional - The maximum number of studies to return.

### Request Example
ct.get_full_studies(search_expr="Coronavirus+COVID", max_studies=50)

### Response
#### Success Response (200)
- **data** (list) - A list of full study records.

#### Response Example
[{"NCTId": "NCT01234567", "BriefTitle": "Example Study", ...}]
```

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

### Handle PyTrials API Errors in Python

Source: https://context7.com/jvfe/pytrials/llms.txt

Illustrates how to handle potential `ValueError` and `HTTPError` exceptions that can occur when using the PyTrials library, such as invalid parameters or API request failures. It shows specific examples for exceeding study limits, using invalid field names, incorrect formats, and general API errors.

```python
from pytrials.client import ClinicalTrials
from requests import HTTPError

ct = ClinicalTrials()

# Handle invalid max_studies parameter (must be between 1 and 1000)
try:
    studies = ct.get_full_studies(
        search_expr="Coronavirus",
        max_studies=2000  # Too many - exceeds 1000 limit
    )
except ValueError as e:
    print(f"ValueError: {e}")
    # Output: ValueError: The number of studies can only be between 1 and 1000

# Handle invalid field names
try:
    studies = ct.get_study_fields(
        search_expr="Coronavirus",
        fields=["NCT Number", "Invalid Field Name"],
        max_studies=50,
        fmt="csv"
    )
except ValueError as e:
    print(f"ValueError: {e}")
    # Output: ValueError: One of the fields is not valid!...

# Handle invalid format parameter
try:
    studies = ct.get_study_fields(
        search_expr="Coronavirus",
        fields=["NCT Number"],
        max_studies=50,
        fmt="xml"  # Invalid format - only 'csv' or 'json' supported
    )
except ValueError as e:
    print(f"ValueError: {e}")
    # Output: ValueError: Format argument has to be either 'csv' or 'json'

# Handle API errors
try:
    studies = ct.get_full_studies(
        search_expr="some_complex_invalid_query!!!",
        max_studies=50
    )
except HTTPError as e:
    print(f"API Error: {e}")
```

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

### GET /get_study_fields

Source: https://github.com/jvfe/pytrials/blob/master/README.rst

Retrieves specific fields for a set of clinical trials matching a search expression.

```APIDOC
## GET /get_study_fields

### Description
Fetches specific data fields for clinical trials matching a search expression, returned in a specified format.

### Method
GET

### Endpoint
get_study_fields(search_expr, fields, max_studies, fmt)

### Parameters
#### Query Parameters
- **search_expr** (string) - Required - The search expression to filter clinical trials.
- **fields** (list) - Required - A list of specific fields to retrieve (e.g., ['NCT Number', 'Conditions']).
- **max_studies** (integer) - Optional - The maximum number of studies to return.
- **fmt** (string) - Optional - The output format, such as 'csv'.

### Request Example
ct.get_study_fields(search_expr="Coronavirus+COVID", fields=["NCT Number", "Conditions"], max_studies=1000, fmt="csv")

### Response
#### Success Response (200)
- **data** (list) - A list containing the requested fields for the matching studies.

#### Response Example
[["NCT Number", "Conditions"], ["NCT01234567", "COVID-19"]]
```

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

### Retrieve Full Study Records

Source: https://context7.com/jvfe/pytrials/llms.txt

Illustrates how to fetch complete study records using `get_full_studies`. This method supports retrieving up to 1000 studies per request in either JSON or CSV format. The example shows processing JSON output and converting CSV output to a pandas DataFrame.

```python
from pytrials.client import ClinicalTrials
import pandas as pd

ct = ClinicalTrials()

# Get 50 full studies related to COVID-19 in JSON format
covid_studies = ct.get_full_studies(
    search_expr="Coronavirus+COVID",
    max_studies=50,
    fmt="json"
)

# Access study data from JSON response
for study in covid_studies["studies"][:3]:
    protocol = study["protocolSection"]
    identification = protocol["identificationModule"]
    status = protocol["statusModule"]

    print(f"NCT ID: {identification['nctId']}")
    print(f"Title: {identification['briefTitle']}")
    print(f"Status: {status['overallStatus']}")
    print("---")

# Get full studies in CSV format
covid_studies_csv = ct.get_full_studies(
    search_expr="Coronavirus+COVID",
    max_studies=50,
    fmt="csv"
)

# CSV returns a list of lists (header row + data rows)
header = covid_studies_csv[0]
print(f"Number of columns: {len(header)}")
print(f"Number of studies: {len(covid_studies_csv) - 1}")

# Convert to pandas DataFrame for analysis
df = pd.DataFrame.from_records(
    covid_studies_csv[1:],
    columns=covid_studies_csv[0]
)
print(df.head())
```

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

### Retrieve Specific Study Fields

Source: https://context7.com/jvfe/pytrials/llms.txt

Demonstrates using `get_study_fields` to query for specific data points from clinical trial records, which is more efficient when only certain information is needed. The method validates field names and supports up to 1000 studies. The example shows fetching data in CSV format and converting it to a pandas DataFrame.

```python
from pytrials.client import ClinicalTrials
import pandas as pd

ct = ClinicalTrials()

# Query specific fields in CSV format
crona_fields_csv = ct.get_study_fields(
    search_expr="Coronavirus+COVID",
    fields=["NCT Number", "Conditions", "Study Title", "Study Status", "Phases"],
    max_studies=100,
    fmt="csv"
)

# Convert CSV results to pandas DataFrame
df = pd.DataFrame.from_records(
    corona_fields_csv[1:],  # Skip header row
    columns=corona_fields_csv[0]  # Use header as column names
)

print(df.head())
```

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

### GET /full_studies

Source: https://github.com/jvfe/pytrials/blob/master/docs/pytrials.md

Retrieves full study records from the ClinicalTrials.gov API based on a search expression. Limited to a maximum of 100 records.

```APIDOC
## GET /full_studies

### Description
Retrieves all available fields for a maximum of 100 study records using a search expression.

### Method
GET

### Endpoint
/full_studies

### Parameters
#### Query Parameters
- **search_expr** (str) - Required - A search expression string as defined by ClinicalTrials.gov documentation.
- **max_studies** (int) - Optional - Maximum number of studies to return (1-100). Defaults to 50.

### Request Example
{ "search_expr": "heart disease", "max_studies": 10 }

### Response
#### Success Response (200)
- **data** (dict) - Object containing the queried study information.

#### Response Example
{ "StudyFieldsResponse": { "NCTId": ["NCT01234567"], "BriefTitle": ["Example Study"] } }
```

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

### GET /get_study_fields

Source: https://context7.com/jvfe/pytrials/llms.txt

Retrieves specific fields from clinical trial records to allow for more efficient data retrieval.

```APIDOC
## GET /get_study_fields

### Description
Retrieves specific fields from clinical trial records, allowing efficient queries when you only need certain data points.

### Method
GET

### Endpoint
get_study_fields(search_expr, fields, max_studies, fmt)

### Parameters
#### Query Parameters
- **search_expr** (string) - Required - The search query string.
- **fields** (list) - Required - A list of field names to retrieve.
- **max_studies** (integer) - Optional - Maximum number of studies to return.
- **fmt** (string) - Optional - Output format, either "json" or "csv".

### Request Example
ct.get_study_fields(search_expr="Coronavirus+COVID", fields=["NCT Number", "Conditions"], max_studies=100, fmt="csv")

### Response
#### Success Response (200)
- **data** (list/dict) - The requested fields for the matching studies.

#### Response Example
[
  ["NCT Number", "Conditions"],
  ["NCT01234567", "COVID-19"]
]
```

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

### GET /study_fields

Source: https://github.com/jvfe/pytrials/blob/master/docs/pytrials.md

Retrieves specific fields for up to 1000 study records based on a search expression.

```APIDOC
## GET /study_fields

### Description
Retrieves specific information fields for a large number of studies (up to 1000).

### Method
GET

### Endpoint
/study_fields

### Parameters
#### Query Parameters
- **search_expr** (str) - Required - Search expression string.
- **fields** (list) - Required - List of desired information fields.
- **max_studies** (int) - Optional - Maximum number of studies (1-1000). Defaults to 50.
- **min_rnk** (int) - Optional - Minimum rank for the range of records. Defaults to 1.
- **fmt** (str) - Optional - Output format, 'csv' or 'json'. Defaults to 'csv'.

### Request Example
{ "search_expr": "diabetes", "fields": ["NCTId", "BriefTitle"], "max_studies": 100 }

### Response
#### Success Response (200)
- **data** (dict/list) - Returns a dict if fmt='json' or a list of records if fmt='csv'.

#### Response Example
{ "StudyFieldsResponse": { "Field1": ["Value1"], "Field2": ["Value2"] } }
```

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

### GET /get_full_studies

Source: https://context7.com/jvfe/pytrials/llms.txt

Retrieves complete study records for a given search expression. Supports up to 1000 studies per request with configurable output formats.

```APIDOC
## GET /get_full_studies

### Description
Retrieves complete study records with all available fields. Returns data in either CSV (list of records) or JSON (dictionary) format.

### Method
GET

### Endpoint
get_full_studies(search_expr, max_studies, fmt)

### Parameters
#### Query Parameters
- **search_expr** (string) - Required - The search query string (e.g., "Coronavirus+COVID").
- **max_studies** (integer) - Optional - Maximum number of studies to return (up to 1000).
- **fmt** (string) - Optional - Output format, either "json" or "csv".

### Request Example
ct.get_full_studies(search_expr="Coronavirus+COVID", max_studies=50, fmt="json")

### Response
#### Success Response (200)
- **studies** (list/dict) - The collection of clinical trial records.

#### Response Example
{
  "studies": [
    {
      "protocolSection": {
        "identificationModule": {
          "nctId": "NCT01234567",
          "briefTitle": "Example Study"
        }
      }
    }
  ]
}
```

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

### Version and deploy project

Source: https://github.com/jvfe/pytrials/blob/master/docs/contributing.md

Commands for maintainers to bump the project version and push changes to trigger deployment.

```shell
bump2version patch
git push
git push --tags
```

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

### Initialize ClinicalTrials Client

Source: https://context7.com/jvfe/pytrials/llms.txt

Demonstrates how to initialize the ClinicalTrials client and access API version and database update information. The client automatically fetches API details upon instantiation.

```python
from pytrials.client import ClinicalTrials

# Initialize the client
ct = ClinicalTrials()

# Access API information
print(ct)  # Output: ClinicalTrials.gov client v2.0.0, database last updated 2024-01-15T12:00:00Z

# Get API version and last update timestamp
api_version, last_updated = ct.api_info
print(f"API Version: {api_version}")
print(f"Database Last Updated: {last_updated}")
```

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

### Perform Advanced Searches with PyTrials in Python

Source: https://context7.com/jvfe/pytrials/llms.txt

This section demonstrates how to construct complex search queries using the `search_expr` parameter in PyTrials. It covers simple keyword searches, combining terms with AND, searching by specific conditions and sponsors, and creating intricate queries with multiple criteria. Results can be fetched in CSV format and converted to a pandas DataFrame for further analysis.

```python
from pytrials.client import ClinicalTrials
import pandas as pd

ct = ClinicalTrials()

# Simple keyword search (combines terms with AND)
diabetes_studies = ct.get_study_fields(
    search_expr="diabetes",
    fields=["NCT Number", "Study Title", "Conditions"],
    max_studies=50,
    fmt="csv"
)

# Multiple keywords with + (AND operator)
covid_vaccine_studies = ct.get_study_fields(
    search_expr="COVID+vaccine+efficacy",
    fields=["NCT Number", "Study Title", "Phases", "Enrollment"],
    max_studies=100,
    fmt="csv"
)

# Search by specific condition
cancer_studies = ct.get_study_fields(
    search_expr="AREA[Condition]breast cancer",
    fields=["NCT Number", "Study Title", "Study Status", "Sponsor"],
    max_studies=100,
    fmt="csv"
)

# Search by sponsor
pfizer_studies = ct.get_study_fields(
    search_expr="AREA[LeadSponsorName]Pfizer",
    fields=["NCT Number", "Study Title", "Conditions", "Phases"],
    max_studies=50,
    fmt="csv"
)

# Complex query with multiple conditions
complex_query = ct.get_study_fields(
    search_expr="AREA[Condition]lung cancer+AREA[Phase]Phase 3+AREA[OverallStatus]Recruiting",
    fields=["NCT Number", "Study Title", "Sponsor", "Start Date", "Locations"],
    max_studies=200,
    fmt="csv"
)

# Convert to DataFrame for analysis
df = pd.DataFrame.from_records(complex_query[1:], columns=complex_query[0])
print(f"Found {len(df)} recruiting Phase 3 lung cancer trials")
print(df[["NCT Number", "Study Title", "Sponsor"]].head(10))
```

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

### Format and test code

Source: https://github.com/jvfe/pytrials/blob/master/docs/contributing.md

Commands to format the codebase using Black and execute the test suite using pytest.

```shell
black pytrials tests
pytest
```

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

### Query Clinical Trials Data

Source: https://github.com/jvfe/pytrials/blob/master/docs/readme.md

Demonstrates how to initialize the ClinicalTrials client, perform searches for full studies or specific fields, and process the results using Pandas.

```python
from pytrials.client import ClinicalTrials
import pandas as pd

ct = ClinicalTrials()

# Get 50 full studies related to Coronavirus and COVID in csv format.
ct.get_full_studies(search_expr="Coronavirus+COVID", max_studies=50)

# Get the NCTId, Condition and Brief title fields from 1000 studies
corona_fields = ct.get_study_fields(
    search_expr="Coronavirus+COVID",
    fields=["NCT Number", "Conditions", "Study Title"],
    max_studies=1000,
    fmt="csv",
)

# Read the csv data in Pandas
pd.DataFrame.from_records(corona_fields[1:], columns=corona_fields[0])
```

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

### Access Available Study Fields

Source: https://context7.com/jvfe/pytrials/llms.txt

Shows how to retrieve a dictionary of all valid study field names usable in queries, categorized by CSV and JSON output formats. This is useful for discovering fields before constructing queries.

```python
from pytrials.client import ClinicalTrials

ct = ClinicalTrials()

# Get all available study fields
available_fields = ct.study_fields

# List CSV fields (column names for tabular output)
print("CSV Fields:")
for field in available_fields["csv"]:
    print(f"  - {field}")

# List JSON fields (API field names)
print("\nJSON Fields:")
for field in available_fields["json"][:10]:
    print(f"  - {field}")
```

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

### Utility Functions API

Source: https://github.com/jvfe/pytrials/blob/master/docs/modules.md

This section details the utility functions for handling data formats and making requests.

```APIDOC
## POST /utils/csv_handler

### Description
Handles CSV data, potentially for reading or writing.

### Method
POST

### Endpoint
/utils/csv_handler

### Parameters
#### Request Body
- **data** (any) - Required - The data to be processed as CSV.
- **operation** (string) - Optional - Specifies the operation (e.g., 'read', 'write').

### Request Example
```json
{
  "data": [{"col1": "val1", "col2": "val2"}],
  "operation": "write"
}
```

### Response
#### Success Response (200)
- **result** (any) - The result of the CSV operation.

#### Response Example
```json
{
  "result": "CSV data processed successfully."
}
```
```

```APIDOC
## POST /utils/json_handler

### Description
Handles JSON data, potentially for parsing or formatting.

### Method
POST

### Endpoint
/utils/json_handler

### Parameters
#### Request Body
- **data** (any) - Required - The data to be processed as JSON.
- **operation** (string) - Optional - Specifies the operation (e.g., 'parse', 'format').

### Request Example
```json
{
  "data": "{\"key\": \"value\"}",
  "operation": "parse"
}
```

### Response
#### Success Response (200)
- **result** (any) - The result of the JSON operation.

#### Response Example
```json
{
  "result": {"key": "value"}
}
```
```

```APIDOC
## POST /utils/request_ct

### Description
Handles requests to the Clinical Trials API.

### Method
POST

### Endpoint
/utils/request_ct

### Parameters
#### Request Body
- **endpoint** (string) - Required - The specific Clinical Trials API endpoint to call.
- **params** (object) - Optional - Parameters for the API request.

### Request Example
```json
{
  "endpoint": "/studies",
  "params": {"term": "diabetes"}
}
```

### Response
#### Success Response (200)
- **response_data** (any) - The data returned from the Clinical Trials API.

#### Response Example
```json
{
  "response_data": {"studies": [{"id": "NCT98765432", "title": "Diabetes Study"}]}
}
```
```

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

### Query Specific Fields with JSON Output in Python

Source: https://context7.com/jvfe/pytrials/llms.txt

Demonstrates querying specific fields for studies related to 'Coronavirus+COVID' and retrieving the results in JSON format. It then iterates through the first three studies to print their NCT ID, title, and conditions.

```python
from pytrials.client import ClinicalTrials

ct = ClinicalTrials()
corona_fields_json = ct.get_study_fields(
    search_expr="Coronavirus+COVID",
    fields=["NCTId", "Condition", "BriefTitle", "OverallStatus", "Phase"],
    max_studies=100,
    fmt="json"
)

for study in corona_fields_json["studies"][:3]:
    protocol = study["protocolSection"]
    print(f"NCT ID: {protocol['identificationModule']['nctId']}")
    print(f"Title: {protocol['identificationModule']['briefTitle']}")
    if "conditionsModule" in protocol:
        conditions = protocol["conditionsModule"].get("conditions", [])
        print(f"Conditions: {', '.join(conditions)}")
    print("---")
```

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

### ClinicalTrials Client API

Source: https://github.com/jvfe/pytrials/blob/master/docs/modules.md

This section covers the methods available within the ClinicalTrials client class for retrieving clinical trial data.

```APIDOC
## GET /api/v1/studies

### Description
Retrieves a list of full clinical trial studies based on specified criteria.

### Method
GET

### Endpoint
/api/v1/studies

### Parameters
#### Query Parameters
- **term** (string) - Required - The search term for clinical trials.
- **count** (integer) - Optional - The number of studies to retrieve.

### Request Example
```json
{
  "term": "cancer",
  "count": 10
}
```

### Response
#### Success Response (200)
- **studies** (array) - A list of clinical trial study objects.

#### Response Example
```json
{
  "studies": [
    {
      "id": "NCT12345678",
      "title": "A Study of Cancer Treatment"
    }
  ]
}
```
```

```APIDOC
## GET /api/v1/study_fields

### Description
Retrieves specific fields for clinical trial studies.

### Method
GET

### Endpoint
/api/v1/study_fields

### Parameters
#### Query Parameters
- **study_id** (string) - Required - The ID of the study to retrieve fields for.
- **fields** (array of strings) - Optional - A list of fields to retrieve.

### Request Example
```json
{
  "study_id": "NCT12345678",
  "fields": ["title", "status"]
}
```

### Response
#### Success Response (200)
- **study_data** (object) - An object containing the requested fields for the study.

#### Response Example
```json
{
  "study_data": {
    "title": "A Study of Cancer Treatment",
    "status": "Recruiting"
  }
}
```
```

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

### Filter Studies by Status in Python

Source: https://context7.com/jvfe/pytrials/llms.txt

This snippet shows how to filter a pandas DataFrame of clinical studies to find only those with a 'Completed' status. It assumes the DataFrame 'df' is already populated with study data.

```python
completed_studies = df[df["Study Status"] == "Completed"]
print(f"Completed studies: {len(completed_studies)}")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.