### Install Sky Patrol Client

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/getting_started.md

Instructions for cloning the Sky Patrol repository from GitHub and installing the client using pip. This method is recommended during the beta release phase.

```bash
git clone https://github.com/asas-sn/skypatrol.git
pip3 install skypatrol/
```

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

### Installation

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

Instructions for installing the pyasassn Python client from source.

```APIDOC
## Installation

Make sure your pip points to the appropriate Python >= 3.6 installation...

```bash
git clone https://github.com/asas-sn/skypatrol.git
pip3 install skypatrol/ 
```
```

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

### Install ASAS-SN SkyPatrol Client

Source: https://github.com/asas-sn/skypatrol/blob/master/README.md

Installs the ASAS-SN SkyPatrol client using pip. Requires Python 3.6 or later. Alternatively, it can be built from source by cloning the repository and installing with pip3.

```bash
python -m pip install skypatrol
```

```bash
git clone https://github.com/asas-sn/skypatrol.git
pip3 install skypatrol/
```

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

### Initialize Sky Patrol Client and List Catalogs

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/getting_started.md

Demonstrates how to import the SkyPatrolClient and create an instance. The output shows a list of available astronomical data catalogs, their column counts, and the number of targets they contain.

```python
>>> from pyasassn.client import SkyPatrolClient
>>> client = SkyPatrolClient()
>>> client.catalogs
Table Name: stellar_main
Num Columns: 47
Num Targets: 98932961

Table Name: master_list
Num Columns: 4
Num Targets: 103874668

Table Name: comets
Num Columns: 1
Num Targets: 1825

Table Name: swift
Num Columns: 56
Num Targets: 254936

Table Name: allwiseagn
Num Columns: 15
Num Targets: 1354900

Table Name: mdwarf
Num Columns: 32
Num Targets: 8927

Table Name: milliquas
Num Columns: 21
Num Targets: 1979676

...
```

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

### Install ASAS-SN SkyPatrol Python Package

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

Installs the pyasassn package from a local clone of the GitHub repository. Requires Python version 3.6 or higher.

```bash
git clone https://github.com/asas-sn/skypatrol.git
pip3 install skypatrol/ 
```

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

### Name Lookup Example

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/additional.md

An example SQL query for performing name lookups in the 'aavsovsx' catalog. It uses a LIKE clause to find all variable objects whose names start with 'ASASSN'.

```SQL
SELECT
  asas_sn_id,
  name
FROM aavsovsx
WHERE name LIKE 'ASASSN%'
```

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

### Cross Catalog Search Example

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/additional.md

An example SQL query illustrating how to perform a cross-catalog search. It joins the 'swift' and 'aavsovsx' catalogs on 'asas_sn_id' to find targets present in both.

```SQL
SELECT
  asas_sn_id,
  s.name AS swift_id,
  v.name AS vso_id
FROM swift s
JOIN aavsovsx v USING(asas_sn_id)
```

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

### Query for White Dwarfs using ADQL

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/queries.md

This example shows a more complex ADQL query to identify white dwarfs. It joins 'stellar_main' with 'aavsovsx' and applies filters on apparent magnitude, absolute magnitude, and color index. It calculates absolute magnitude using parallax.

```python
query = """
SELECT
  asas_sn_id,
  gaia_id,
  pstarrs_g_mag,
  (gaia_mag - (5 * LOG10(plx) - 10)) AS g_mag_abs,
  name
FROM stellar_main
JOIN aavsovsx USING(asas_sn_id)
WHERE 1=1
 AND pstarrs_g_mag < 14
 AND (gaia_mag - (5 * LOG10(plx) - 10)) > 10
 AND (gaia_b_mag - gaia_r_mag) < 1.5
"""
client.adql_query(query)
```

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

### Query Catalog by List of IDs in Python

Source: https://github.com/asas-sn/skypatrol/blob/master/README.md

This example shows how to query astronomical catalogs using a list of external identifiers. For the 'stellar_main' catalog, a specific 'id_col' parameter (e.g., 'tic_id') must be provided. For other catalogs, querying by name is supported. The function returns a DataFrame of matching objects.

```python
my_tic_ids = [6658326, 46783395, 1021890]
client.query_list(my_tic_ids, catalog='stellar_main', id_col='tic_id')
```

```python
my_vso_id = 'ASASSN-V J182608.32-864925.1'
client.query_list(my_vso_id, catalog='aavsovsx')
```

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

### Finding White Dwarfs Example

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/additional.md

An example SQL query designed to identify white dwarfs. It calculates the absolute Gaia magnitude and filters based on this value and the color index (G band - R band magnitude).

```SQL
SELECT
  asas_sn_id,
  gaia_id,
  pstarrs_g_mag,
  (gaia_mag - (5 * LOG10(plx) - 10)) AS g_mag_abs,
  name
FROM stellar_main
JOIN morx USING(asas_sn_id)
WHERE 1=1
  AND (gaia_mag - (5 * LOG10(plx) - 10)) > 10
  AND (gaia_b_mag - gaia_r_mag) < 1.5
```

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

### Inspect Catalog Columns and Data Types

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/getting_started.md

Shows how to inspect the column names and their corresponding data types for a specific catalog, such as 'master_list' or 'milliquas'. This helps in understanding the available data fields for querying.

```python
>>> client.catalogs.master_list

         col_names         dtypes
0       asas_sn_id         bigint
1           ra_deg         double
2          dec_deg         double
3  catalog_sources  array<string>

>>> client.catalogs.milliquas

        col_names  dtypes
0      asas_sn_id  bigint
1          ra_deg  double
2         dec_deg  double
3            name  string
4             lii  double
5             bii  double
6      broad_type  string
7            rmag  double
8            bmag  double
9    optical_flag  string
10   red_psf_flag  string
11  blue_psf_flag  string
12       redshift  double
13       ref_name  string
14   ref_redshift  string
15       qso_prob  double
16     radio_name  string
17      xray_name  string
18     alt_name_1  string
19     alt_name_2  string
20          class  bigint
```

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

### Cone Search Example

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/additional.md

An example SQL query demonstrating a cone search. It selects targets from the 'stellar_main' catalog that fall within a specified angular distance (5.0 degrees) from a given coordinate (RA 255.0, Dec 82.1).

```SQL
SELECT
  asas_sn_id,
  ra_deg,
  dec_deg
FROM stellar_main
WHERE DISTANCE(ra_deg, dec_deg, 255.0, 82.1) <= 5.0
```

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

### Nearest Neighbor Search Example

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/additional.md

An example SQL query for performing a nearest neighbor search. It calculates the angular distance of all sources from a central coordinate and then filters for those within 15 arcminutes, ordering them by proximity.

```SQL
WITH sources AS
  (
    SELECT
      asas_sn_id,
      ra_deg,
      dec_deg,
      DISTANCE(ra_deg, dec_deg, 255.0, 82.1) AS angular_dist
    FROM stellar_main
  )
SELECT * 
FROM sources
WHERE angular_dist <= ARCMIN(15)
ORDER BY angular_dist ASC
```

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

### Filtering by Magnitude and Flux Example

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/additional.md

An example SQL query demonstrating how to filter targets based on magnitude and flux properties. It selects targets within a specific Gaia G magnitude range (17.0 to 18.0) and with a cumulative flux exceeding a certain threshold.

```SQL
SELECT
  asas_sn_id,
  gaia_mag,
  rp_01
FROM stellar_main
WHERE 1=1
  AND gaia_mag BETWEEN 17.0 AND 18.0
  AND rp_00_1 > 20
```

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

### random_sample - Get Random Targets

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Retrieves a random sample of targets from any input catalog. Useful for statistical studies, testing pipelines, or exploring catalog contents.

```APIDOC
## random_sample - Get Random Targets

### Description
Retrieves a random sample of targets from any input catalog. Useful for statistical studies, testing pipelines, or exploring catalog contents.

### Method
GET

### Endpoint
/random_sample

### Parameters
#### Query Parameters
- **n** (int) - Required - The number of random targets to retrieve.
- **catalog** (str) - Required - The name of the catalog to sample from.
- **cols** (list[str]) - Optional - A list of column names to include in the results.
- **download** (bool) - Optional - If True, downloads light curves for the sampled targets.
- **threads** (int) - Optional - Number of threads to use for downloading light curves.
- **save_dir** (str) - Optional - Directory to save downloaded light curves.
- **file_format** (str) - Optional - Format for saving downloaded light curves (e.g., 'parquet', 'csv').

### Request Example
```python
client.random_sample(n=1000, catalog='aavsovsx')
client.random_sample(n=500, catalog='master_list', cols=['asas_sn_id', 'ra_deg', 'dec_deg', 'catalog_sources'])
client.random_sample(n=10000, catalog='stellar_main', download=True, threads=8, save_dir='./lightcurves', file_format='parquet')
```

### Response
#### Success Response (200)
- **results** (DataFrame or list[str]) - A pandas DataFrame containing the random sample of targets, or a list of saved filenames if download is True.
```

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

### Get Random Catalog Samples with Python

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

Retrieves a specified number of random targets from a given catalog. This function is useful for obtaining a representative sample of objects for analysis. It requires the client object to be initialized and the catalog name as a string.

```python
client.random_sample(1000, catalog="aavsovsx")
```

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

### Client Initialization and Catalog Listing

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

Demonstrates how to create a SkyPatrolClient object and access the available catalogs.

```APIDOC
## Client Initialization and Catalog Listing

Create a SkyPatrolClient object. The client will automatically ping the server for the most recent catalog data.

### Request Example

```python
from pyasassn.client import SkyPatrolClient

client = SkyPatrolClient()
print(client.catalogs)
```

### Response Example

```
Table Name:  stellar_main
Num Columns: 47
Num Targets: 98932961

Table Name:  master_list
Num Columns: 4
Num Targets: 106483451

...
```
```

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

### Analyze Individual Light Curves with SkyPatrol Client

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Demonstrates how to retrieve, inspect, plot, and save individual astronomical light curves using the SkyPatrol client. It shows accessing metadata and data, direct column access, plotting with various options, saving data in different formats, and applying quality cuts and normalization.

```python
from pyasassn.client import SkyPatrolClient

client = SkyPatrolClient()

# Get a light curve collection and extract one
lcs = client.random_sample(10, catalog='aavsovsx', download=True)
lightcurve = lcs[lcs.ids[0]]

# Access light curve data and metadata
print(lightcurve.meta)
#     asas_sn_id     ra_deg   dec_deg                          name
# 18      229541  122.54987 -80.11104  ASASSN-V J081011.92-800639.7

print(lightcurve.data.head())
#    asas_sn_id            jd      flux  flux_err        mag   mag_err  ...

# Access columns directly as attributes
print(lightcurve.jd[:5])       # Julian dates
print(lightcurve.mag[:5])      # Magnitudes
print(lightcurve.mag_err[:5])  # Magnitude errors

# Plot the light curve
lightcurve.plot(
    figsize=(12, 8),
    include_non_det=True,
    phot_filter='all'
)

# Save plot to file
lightcurve.plot(
    save_file='lightcurve_plot.png',
    include_poor_images=False,
    phot_filter='g'
)

# Save light curve data
lightcurve.save('my_lightcurve.csv', file_format='csv')
lightcurve.save('my_lightcurve.parq', file_format='parquet')

# Quality filtering
clean_lc = lightcurve.quality_cut(sigma_cut=5)

# Normalize light curve
normalized_lc = lightcurve.normalize(method='median', col='mag')
```

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

### Download Light Curves with pyasassn Client

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/lightcurves.md

Demonstrates how to download light curves using the pyasassn client. The `download=True` parameter in query functions returns a LightCurveCollection. Supports multi-threading for large downloads and saving directly to disk.

```python
>>> lcs = client.random_sample(100, 'aavsovsx', download=True)
>>> lcs
<pyasassn.utils.LightCurveCollection object at 0x7f407d458ac8>
```

```python
# Two degree cone search near the south pole returns about 38k lightcurves
>>> lcs = client.cone_search('18:54:11.5', '-88:02:55.22', radius=2.0, download=True, threads=8)
<pyasassn.utils.LightCurveCollection object at 0x7f403d319550>
```

```python
>>> client.random_sample(100000, download=True, threads=10, save_dir='tmp', file_format='csv')
['tmp/292058613402.csv', 'tmp/292058614306.csv', 'tmp/292058615974.csv' ...  'tmp/292058617076.csv', 'tmp/292058618092.csv', 'tmp/292058618311.csv']
```

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

### Initialize SkyPatrolClient and List Catalogs

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

Initializes the SkyPatrolClient to connect to the ASAS-SN server and retrieve the list of available catalogs. The client automatically pings the server for the most recent catalog data upon instantiation.

```python
from pyasassn.client import SkyPatrolClient

client = SkyPatrolClient()
client.catalogs
```

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

### Download Lightcurves with ADQL

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

Shows how to download lightcurve data for targets identified by an ADQL query. The 'download=True' parameter triggers the download, and 'threads' can be used to parallelize the process. The result is a LightCurveCollection object, which has a 'data' attribute containing the lightcurve information. This method can take a significant amount of time.

```python
# Should take about 2-4 minutes
lcs = client.adql_query(query, download=True, threads=8)
lcs.data
```

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

### Work with LightCurveCollection

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Demonstrates how to use the LightCurveCollection object, which is returned when downloading multiple light curves. It provides methods for batch analysis, iteration, filtering, and saving.

```python
from pyasassn.client import SkyPatrolClient

client = SkyPatrolClient()

# Download light curves
lcs = client.random_sample(100, catalog='aavsovsx', download=True)

# View collection info
print(f"Collection contains {len(lcs)} light curves")

# Get all target IDs in collection
print(lcs.ids)

# Calculate statistics for all curves
stats = lcs.stats()
print(stats)
```

```python
# Filter statistics by photometric filter
g_stats = lcs.stats(phot_filter='g')
v_stats = lcs.stats(phot_filter='V')
```

```python
# Apply custom function to all light curves
from scipy.stats import kurtosis
kurtosis_results = lcs.apply_function(kurtosis, col='mag')
```

```python
# Iterate through individual light curves
for lightcurve in lcs.itercurves():
    print(f"ID: {lightcurve.meta.asas_sn_id.values[0]}, Epochs: {lightcurve.epochs}")
```

```python
# Access individual light curve by ID
single_lc = lcs[229541]
```

```python
# Save entire collection to disk
filenames = lcs.save(save_dir='./output', file_format='parquet')
```

```python
# Merge collection for objects with multiple designations
merged_lc = lcs.merge(name='Combined_Object')
```

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

### Get Available Catalog Names

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/pyasassn.md

Retrieves a list of all available input catalog names from the ASAS-SN Sky Patrol database.

```APIDOC
## GET /catalogs/names

### Description
Get all the names of our available input catalogs.

### Method
GET

### Endpoint
`/catalogs/names`

### Parameters
None

### Response
#### Success Response (200)
- **names** (list) - A list of strings, where each string is the name of an available input catalog.

#### Response Example
```json
{
  "names": [
    "master_list",
    "stellar_main",
    "transient_sources"
  ]
}
```
```

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

### Initialize SkyPatrolClient Connection

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Initializes the SkyPatrolClient to connect to ASAS-SN servers and fetch catalog metadata. It allows exploration of available catalogs and their columns before performing queries. Dependencies include the pyasassn library.

```python
from pyasassn.client import SkyPatrolClient

# Initialize the client (automatically fetches catalog metadata)
client = SkyPatrolClient(verbose=True)

# View all available catalogs
print(client.catalogs)
# Output:
# Table Name: stellar_main
# Num Columns: 47
# Num Targets: 98932961
#
# Table Name: master_list
# Num Columns: 4
# Num Targets: 103874668
#
# Table Name: aavsovsx
# Num Columns: 28
# ...

# Explore columns in a specific catalog
print(client.catalogs.stellar_main.head(10))
#    col_names   dtypes
# 0  asas_sn_id  bigint
# 1  ra_deg      double
# 2  dec_deg     double
# 3  gaia_id     bigint
# 4  tic_id      bigint
# ...

# Get list of all catalog names
catalog_names = client.catalogs.catalog_names()
# dict_keys(['stellar_main', 'master_list', 'comets', 'swift', 'allwiseagn', ...])
```

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

### Get Random Targets from Catalog

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Retrieves a random sample of targets from a specified catalog. This function is useful for statistical studies or exploring catalog contents. It can also download light curves and save them to disk.

```python
from pyasassn.client import SkyPatrolClient

client = SkyPatrolClient()

# Get 1000 random targets from AAVSO VSX catalog
results = client.random_sample(
    n=1000,
    catalog='aavsovsx'
)
print(results)
```

```python
results = client.random_sample(
    n=500,
    catalog='master_list',
    cols=['asas_sn_id', 'ra_deg', 'dec_deg', 'catalog_sources']
)
```

```python
client.random_sample(
    n=10000,
    catalog='stellar_main',
    download=True,
    threads=8,
    save_dir='./lightcurves',
    file_format='parquet'
)
```

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

### Query Stellar Main Catalog Head

Source: https://github.com/asas-sn/skypatrol/blob/master/README.md

Retrieves the first 15 entries from the 'stellar_main' catalog. This catalog contains the primary targets and includes identifiers from various astronomical surveys like GAIA, TESS, SDSS, and ALLWISE.

```python
client.catalogs.stellar_main.head(15)
```

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

### Query ADQL for Light Curves using Python

Source: https://github.com/asas-sn/skypatrol/blob/master/README.md

This snippet shows how to query the ADQL database to download light curve data. It utilizes the 'adql_query' method, specifying the query, download mode, and number of threads. The result is stored in the 'lcs' variable, and the '.data' attribute accesses the downloaded data, likely a pandas DataFrame.

```python
lcs = client.adql_query(query, mode="download_curves", threads=2)
lcs.data
```

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

### SkyPatrolClient - Initialize Client Connection

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Initializes the SkyPatrolClient, which connects to ASAS-SN servers and retrieves catalog schema. It allows exploration of available catalogs and their columns before making queries.

```APIDOC
## SkyPatrolClient - Initialize Client Connection

### Description
Initializes the SkyPatrolClient, the main entry point for ASAS-SN Sky Patrol interactions. It connects to the ASAS-SN servers and retrieves the current catalog schema, allowing users to explore available catalogs and their columns before querying.

### Method
Initialization (implicitly via constructor)

### Endpoint
N/A (Client-side initialization)

### Parameters
#### Constructor Parameters
- **verbose** (bool) - Optional - If True, prints connection and catalog information during initialization.

### Request Example
```python
from pyasassn.client import SkyPatrolClient

# Initialize the client (automatically fetches catalog metadata)
client = SkyPatrolClient(verbose=True)

# View all available catalogs
print(client.catalogs)

# Explore columns in a specific catalog
print(client.catalogs.stellar_main.head(10))

# Get list of all catalog names
catalog_names = client.catalogs.catalog_names()
```

### Response
#### Success Response (Initialization)
- **client object**: An instance of SkyPatrolClient connected to the ASAS-SN servers.
- **client.catalogs**: An object containing metadata about available catalogs and their columns.

#### Response Example (client.catalogs)
```json
{
  "stellar_main": {
    "Table Name": "stellar_main",
    "Num Columns": 47,
    "Num Targets": 98932961
  },
  "master_list": {
    "Table Name": "master_list",
    "Num Columns": 4,
    "Num Targets": 103874668
  },
  ...
}
```

#### Response Example (client.catalogs.stellar_main.head(10))
```json
{
  "col_names": ["asas_sn_id", "ra_deg", "dec_deg", "gaia_id", "tic_id", ...],
  "dtypes": ["bigint", "double", "double", "bigint", "bigint", ...]
}
```
```

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

### Perform Cone Search using ADQL in Python

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

This snippet demonstrates how to perform a cone search using the custom ADQL parser in Python. It constructs an ADQL query to select all columns from the 'stellar_main' table within a specified distance and right ascension/declination, then executes the query using a client object. No external libraries are explicitly mentioned as dependencies, but a 'client' object is assumed to be available.

```python
query = """
SELECT 
 * 
FROM stellar_main 
WHERE DISTANCE(ra_deg, dec_deg, 270, 88) <= ARCMIN(7.1)
"""
client.adql_query(query)
```

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

### ADQL Query to Join Chandra and Swift Catalogs

Source: https://github.com/asas-sn/skypatrol/blob/master/README.md

This Python code snippet demonstrates how to use ADQL to perform a JOIN operation between the Chandra and Swift catalogs, selecting the asas_sn_id, Chandra name, and Swift name. It assumes the existence of a 'client' object with an 'adql_query' method. The result is a table containing matched entries from both catalogs.

```python
query = """
SELECT 
 asas_sn_id,
 chandra.name AS c_name,
 swift.name AS s_name  
FROM chandra 
JOIN swift USING(asas_sn_id) 
"""
client.adql_query(query)
```

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

### Accessing Stellar Main Catalog

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

Shows how to access and view the head of the 'stellar_main' catalog, which contains the bulk of ASAS-SN targets.

```APIDOC
## Accessing Stellar Main Catalog

The __stellar_main__ catalog contains the bulk of our targets. It was built off of ATLAS REFCAT2 and contains GAIA, TESS, SDSS, and ALLWISE identifiers where available.

### Request Example

```python
client.catalogs.stellar_main.head(12)
```

### Response Example

```
     col_names  dtypes
0   asas_sn_id  bigint
1       ra_deg  double
2      dec_deg  double
3    refcat_id  bigint
4      gaia_id  bigint
...
```
```

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

### SkyPatrolClient

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/pyasassn.md

The SkyPatrolClient allows users to interact with the ASAS-SN Sky Patrol photometry database. This client enables users to use ADQL, cone searches, random samples, and catalog ID lookups on the input catalogs.

```APIDOC
## Class: SkyPatrolClient

### Description
Allows users to interact with the ASAS-SN Sky Patrol photometry database using ADQL, cone searches, random samples, and catalog ID lookups.

### Parameters
* **verbose** (bool) - Optional - If True, enables verbose output.
```

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

### Complex Target Selection using ADQL

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

Illustrates a complex ADQL query to find specific types of astronomical targets, in this case, white dwarfs that cross-match in the VSO catalog. The query filters based on apparent magnitude, absolute magnitude, and color index. It requires a client object with an 'adql_query' method and access to 'stellar_main' and 'aavsovsx' tables.

```python
query = """
SELECT 
  asas_sn_id,
  gaia_id,
  pstarrs_g_mag,
  (gaia_mag - (5 * LOG10(plx) - 10)) AS g_mag_abs, 
  name 
FROM stellar_main 
JOIN aavsovsx USING(asas_sn_id)
WHERE 1=1
 AND pstarrs_g_mag < 14 
 AND (gaia_mag - (5 * LOG10(plx) - 10)) > 10
 AND (gaia_b_mag - gaia_r_mag) < 1.5 
"""
client.adql_query(query)
```

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

### Download Light Curves via ADQL Query

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Downloads light curve data for query results using the ADQL query. This function supports parallel downloads with a specified number of threads.

```python
lcs = client.adql_query(query, download=True, threads=4)
```

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

### Join Astronomical Catalogs with ADQL

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

Demonstrates how to join two astronomical catalogs (chandra and fermi) using ADQL based on a common identifier (asas_sn_id). This query retrieves specific columns from each catalog for matching entries. It requires a client object with an 'adql_query' method.

```python
query = """
SELECT 
 asas_sn_id,
 chandra.name AS c_name,
 fermi.name 
FROM chandra 
JOIN fermi USING(asas_sn_id) 
"""
client.adql_query(query)
```

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

### Perform ADQL Cross-Catalog JOIN

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Performs a cross-catalog join using ADQL to find white dwarfs in the AAVSO catalog by joining 'stellar_main' with 'aavsovsx'. It applies several magnitude and color criteria.

```python
query = """
SELECT
  asas_sn_id,
  gaia_id,
  pstarrs_g_mag,
  (gaia_mag - (5 * LOG10(plx) - 10)) AS g_mag_abs,
  name
FROM stellar_main
JOIN aavsovsx USING(asas_sn_id)
WHERE 1=1
  AND pstarrs_g_mag < 14
  AND (gaia_mag - (5 * LOG10(plx) - 10)) > 10
  AND (gaia_b_mag - gaia_r_mag) < 1.5
"""
white_dwarfs = client.adql_query(query)
print(white_dwarfs)
```

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

### Execute Advanced ADQL Queries

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Executes ADQL (Astronomical Data Query Language) queries against ASAS-SN catalogs. Supports complex queries including JOINs, CTEs, window functions, and custom distance calculations for advanced astronomical analysis.

```python
from pyasassn.client import SkyPatrolClient

client = SkyPatrolClient()


```

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

### simbad_lookup - Search by SIMBAD Name

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Resolves astronomical object names using SIMBAD and retrieves matching targets from the ASAS-SN database.

```APIDOC
## simbad_lookup - Search by SIMBAD Name

### Description
Resolves astronomical object names using SIMBAD and retrieves matching targets from the ASAS-SN database.

### Method
GET

### Endpoint
/simbad_lookup

### Parameters
#### Query Parameters
- **obj_name** (str) - Required - The astronomical object name to look up (e.g., 'Betelgeuse', 'Polaris').
- **download** (bool) - Optional - If True, downloads light curves for the matched targets.

### Request Example
```python
client.simbad_lookup('Betelgeuse')
client.simbad_lookup(obj_name='Polaris', download=True)
```

### Response
#### Success Response (200)
- **results** (DataFrame or LightCurveCollection) - A pandas DataFrame containing matching targets, or a LightCurveCollection object if download is True.
```

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

### Search by SIMBAD Name

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Resolves astronomical object names using SIMBAD and retrieves matching targets from the ASAS-SN database. It can also download associated light curves.

```python
from pyasassn.client import SkyPatrolClient

client = SkyPatrolClient()

# Lookup by common name
results = client.simbad_lookup('Betelgeuse')
print(results)
```

```python
lcs = client.simbad_lookup(
    obj_name='Polaris',
    download=True
)

# Access the light curve data
if lcs is not None:
    print(lcs.data.head())
    print(lcs.stats())
```

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

### adql_query - Advanced SQL-like Queries

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Executes ADQL (Astronomical Data Query Language) queries against the ASAS-SN catalogs. Supports JOINs, CTEs, window functions, and custom distance calculations for complex astronomical queries.

```APIDOC
## adql_query - Advanced SQL-like Queries

### Description
Executes ADQL (Astronomical Data Query Language) queries against the ASAS-SN catalogs. This method allows for complex data retrieval using SQL-like syntax, including support for JOINs, CTEs (Common Table Expressions), window functions, and custom distance calculations.

### Method
POST (typically for sending query bodies)

### Endpoint
`/adql_query` (Conceptual endpoint for the function)

### Parameters
#### Request Body
- **query** (str) - Required - The ADQL query string to execute.
- **catalog** (str) - Optional - The primary catalog to query against. Defaults to 'master_list'.
- **cols** (list of str) - Optional - A list of column names to retrieve. If not specified, a default set of columns is returned.
- **download** (bool) - Optional - If True, downloads the light curve data for the found targets. Defaults to False.
- **threads** (int) - Optional - Number of threads to use for downloading light curves if `download` is True. Defaults to 1.

### Request Example
```python
from pyasassn.client import SkyPatrolClient

client = SkyPatrolClient()

# Example ADQL query to find variable stars in stellar_main with Gaia magnitude < 15
adql_query_string = """
SELECT
    asas_sn_id, ra_deg, dec_deg, gaia_id, gaia_mag
FROM
    stellar_main
WHERE
    gaia_mag < 15 AND is_variable = TRUE
LIMIT 100
"""

results = client.adql_query(
    query=adql_query_string,
    catalog='stellar_main'
)
print(results)

# Example ADQL query with a JOIN
adql_query_join = """
SELECT
    s.asas_sn_id, s.ra_deg, s.dec_deg, c.comet_name
FROM
    stellar_main AS s
JOIN
    comets AS c ON CONTAINS(POINT('ICRS', s.ra_deg, s.dec_deg), c.coords) = 1
WHERE
    s.gaia_mag < 17
LIMIT 50
"""

results_join = client.adql_query(query=adql_query_join)
print(results_join)

# Example ADQL query with light curve download
lcs = client.adql_query(
    query="SELECT asas_sn_id, ra_deg, dec_deg FROM master_list WHERE is_transient = TRUE LIMIT 10",
    download=True,
    threads=4
)
print(f"Downloaded {len(lcs)} light curves")
```

### Response
#### Success Response (200)
- **pandas DataFrame**: A DataFrame containing the results of the ADQL query. Columns will match those specified in the query or the default set. If `download=True`, the function returns a list of light curve objects.

#### Response Example (DataFrame)
```json
{
  "asas_sn_id": [1234567890, 9876543210, ...],
  "ra_deg": [180.12345, 270.54321, ...],
  "dec_deg": [45.67890, -30.12345, ...],
  "gaia_id": [1111111111111111111, 2222222222222222222, ...],
  "gaia_mag": [14.5, 13.8, ...]
}
```

#### Response Example (Downloaded Light Curves)
```json
[
  {
    "target_id": "...",
    "times": [2457000.5, 2457001.5, ...],
    "mags": [19.1, 19.2, ...],
    "mags_err": [0.15, 0.16, ...],
    "filters": ["g", "r", ...]
  },
  ...
]
```
```

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

### Perform ADQL Nearest Neighbor Search with CTE

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Conducts a nearest neighbor search using ADQL with a Common Table Expression (CTE) to find sources within a specified angular distance. Results are ordered by angular distance.

```python
query = """
WITH sources AS (
  SELECT
    asas_sn_id,
    ra_deg,
    dec_deg,
    DISTANCE(ra_deg, dec_deg, 255.0, 82.1) AS angular_dist
  FROM stellar_main
)
SELECT * FROM sources
WHERE angular_dist <= ARCMIN(15)
ORDER BY angular_dist ASC
"""
neighbors = client.adql_query(query)
```

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

### query_list - Search by External Identifiers

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Queries the catalog using a list of external identifiers such as Gaia IDs, TIC IDs, or object names. Useful for querying a predefined list of targets from other surveys.

```APIDOC
## query_list - Search by External Identifiers

### Description
Queries the ASAS-SN catalog using a list of external identifiers like Gaia IDs, TIC IDs, or object names. This method is useful when you have a predefined list of targets from other surveys or databases.

### Method
GET (or POST depending on implementation details)

### Endpoint
`/query_list` (Conceptual endpoint for the function)

### Parameters
#### Query Parameters
- **target_ids** (list or str) - Required - A list of external identifiers or a single identifier (string).
- **catalog** (str) - Optional - The name of the catalog to search within. Defaults to 'master_list'.
- **id_col** (str) - Optional - The name of the column in the specified catalog that corresponds to the `target_ids`. Examples: 'tic_id', 'gaia_id'. Defaults to inferring from common IDs like 'tic_id' or 'gaia_id'.
- **cols** (list of str) - Optional - A list of column names to retrieve. If not specified, a default set of columns is returned.
- **download** (bool) - Optional - If True, downloads the light curve data for the found targets. Defaults to False.
- **threads** (int) - Optional - Number of threads to use for downloading light curves if `download` is True. Defaults to 1.

### Request Example
```python
from pyasassn.client import SkyPatrolClient

client = SkyPatrolClient()

# Query by TIC (TESS Input Catalog) IDs
tic_ids = [6658326, 46783395, 1021890]
results = client.query_list(
    target_ids=tic_ids,
    catalog='stellar_main',
    id_col='tic_id'
)
print(results)

# Query by Gaia IDs
gaia_ids = [5775496815616520960, 5785843769793058048]
results = client.query_list(
    target_ids=gaia_ids,
    catalog='stellar_main',
    id_col='gaia_id',
    cols=['asas_sn_id', 'ra_deg', 'dec_deg', 'gaia_id', 'gaia_mag']
)

# Query AAVSO VSX catalog by name
vsx_name = 'ASASSN-V J182608.32-864925.1'
results = client.query_list(
    target_ids=vsx_name,
    catalog='aavsovsx'
)

# Query with light curve download
lcs = client.query_list(
    target_ids=tic_ids,
    catalog='stellar_main',
    id_col='tic_id',
    download=True,
    threads=2
)
```

### Response
#### Success Response (200)
- **pandas DataFrame**: A DataFrame containing the query results. Columns include identifiers, coordinates, and any other requested columns. If `download=True`, the function returns a list of light curve objects.

#### Response Example (DataFrame)
```json
{
  "asas_sn_id": [309238124040, 335007699083, 335007693701],
  "ra_deg": [329.260377, 97.045759, 81.164422],
  "dec_deg": [-8.035864, 18.214838, 18.222147],
  "tic_id": [1021890, 46783395, 6658326]
}
```

#### Response Example (Downloaded Light Curves)
```json
[
  {
    "target_id": "...",
    "times": [2457000.5, 2457001.5, ...],
    "mags": [17.2, 17.3, ...],
    "mags_err": [0.05, 0.06, ...],
    "filters": ["g", "r", ...]
  },
  ...
]
```
```

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

### Load LightCurveCollection API

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/pyasassn.md

Loads a LightCurveCollection from a specified directory. This requires that the collection's index and light curve files were previously saved.

```APIDOC
## POST /pyasassn/client/load_collection

### Description
Loads a LightCurveCollection from directory. Requires an index and light curve files saved from previous collection.

### Method
POST

### Endpoint
/pyasassn/client/load_collection

### Parameters
#### Request Body
- **save_dir** (string) - Required - path where collection is saved
- **file_format** (string) - Optional - format of saved light curves (default: 'parquet')

### Request Example
```json
{
  "save_dir": "/path/to/saved/collection",
  "file_format": "parquet"
}
```

### Response
#### Success Response (200)
- **collection** (LightCurveCollection) - The loaded LightCurveCollection object.

#### Response Example
```json
{
  "collection": "<LightCurveCollection object>"
}
```
```

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

### Accessing the Master List Catalog

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

Shows how to access the 'master_list' catalog, which contains ASAS-SN IDs, coordinates, and catalog sources for all targets.

```APIDOC
## Accessing the Master List Catalog

The __master_list__ contains __asas_sn_ids__ coordinates and catalog sources for all of our targets. All of our catalogs are cross-matched on the master list with a 2-arcsecond cone.

### Request Example

```python
client.catalogs.master_list
```

### Response Example

```
         col_names         dtypes
0       asas_sn_id         bigint
1           ra_deg         double
2          dec_deg         double
3  catalog_sources  array<string>
```
```

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

### Perform ADQL Cone Search

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Executes a cone search query using ADQL to find sources within a specified radius from a given point. It requires a client object and returns query results.

```python
query = """
SELECT asas_sn_id, ra_deg, dec_deg
FROM stellar_main
WHERE DISTANCE(ra_deg, dec_deg, 270, -88) <= 5.1
"""
results = client.adql_query(query)
print(results)
```

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

### ADQL Queries

Source: https://github.com/asas-sn/skypatrol/blob/master/docs/queries.md

The ADQL query interface allows astronomers and data scientists to query input tables using ADQL grammar. It supports Common Table Expressions, WINDOW functions, correlated subqueries, and UNIONS. Geometry functions like BOX, CIRCLE, AREA, POINT, and CONTAINS have been removed and replaced with a DISTANCE function for cone searches and finding nearest neighbors.

```APIDOC
## ADQL Queries

### Description
This endpoint allows users to submit ADQL (Astronomical Data Query Language) queries to retrieve data from astronomical tables. It supports advanced SQL features and a custom `DISTANCE` function for spatial queries.

### Method
POST

### Endpoint
`/asas-sn/skypatrol/adql_query`

### Parameters
#### Query Parameters
- **query_str** (string) - Required - The ADQL query string to execute.

### Request Body
This endpoint does not use a request body. The query is passed as a parameter.

### Request Example
```python
query_str = """
  SELECT
    asas_sn_id, ra_deg, dec_deg
  FROM stellar_main
  WHERE DISTANCE(ra_deg, dec_deg, 270, -88) <= 5.1 """
client.adql_query(query_str)
```

### Response
#### Success Response (200)
- **results** (table) - A table containing the results of the ADQL query.

#### Response Example
```json
{
  "results": [
    { "asas_sn_id": 1094902, "ra_deg": 14.059417, "dec_deg": -89.846361 },
    { "asas_sn_id": 1099017, "ra_deg": 182.038926, "dec_deg": -89.804971 },
    { "asas_sn_id": 1105675, "ra_deg": 309.260296, "dec_deg": -89.743042 },
    { "asas_sn_id": 1109079, "ra_deg": 39.243573, "dec_deg": -89.709996 },
    { "asas_sn_id": 1110860, "ra_deg": 281.009406, "dec_deg": -89.701636 }
    // ... more rows
  ]
}
```

### Error Handling
- **400 Bad Request**: If the ADQL query is malformed or invalid.
- **500 Internal Server Error**: If there is a server-side issue executing the query.
```

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

### Display Head of Stellar Main Catalog

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

Retrieves and displays the first 12 rows of the 'stellar_main' catalog, which contains the majority of ASAS-SN targets. This catalog is based on ATLAS REFCAT2 and includes identifiers from GAIA, TESS, SDSS, and ALLWISE.

```python
client.catalogs.stellar_main.head(12)
```

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

### Query Solar System Objects

Source: https://context7.com/asas-sn/skypatrol/llms.txt

Retrieves light curves for solar system objects (asteroids and comets) by name from the Minor Planet Center catalog. Supports downloading and saving light curves.

```python
from pyasassn.client import SkyPatrolClient

client = SkyPatrolClient()

# Query asteroid by name
results = client.solar_system_object(
    obj_name='Ceres',
    catalog='asteroids'
)
```

```python
lcs = client.solar_system_object(
    obj_name='67P',
    catalog='comets',
    download=True,
    threads=2
)
```

```python
files = client.solar_system_object(
    obj_name='Vesta',
    catalog='asteroids',
    download=True,
    save_dir='./asteroid_lcs',
    file_format='csv'
)
```

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

### Query Catalog by List of IDs with Python

Source: https://github.com/asas-sn/skypatrol/blob/master/examples/SkyPatrol_Demo.ipynb

Queries astronomical catalogs using a list of external identifiers. This function supports querying the 'stellar_main' catalog using the 'tic_id' parameter, and other catalogs by their 'name'. It requires the client object, a list of IDs, the catalog name, and the identifier column name.

```python
my_tic_ids = [6658326, 46783395, 1021890]
client.query_list(my_tic_ids, catalog='stellar_main', id_col='tic_id', download=Tre)
```

```python
my_vso_id = 'ASASSN-V J182608.32-864925.1'
client.query_list(my_vso_id, catalog='aavsovsx', id_col='name')
```