Deep Dive into a Project

Analyze detailed metrics for a specific project. New to OSO? Check out our Getting Started guide to set up your API access.

tip

All projects are defined as YAML files in OSS Directory. View our current projects here.

Getting Started

Before running any analysis, you'll need to set up your environment:

Python

Start your Python notebook with the following:

import os
import pandas as pd
from pyoso import Client

OSO_API_KEY = os.environ['OSO_API_KEY']
client = Client(api_key=OSO_API_KEY)

For more details on setting up Python notebooks, see our guide on writing Python notebooks.

GraphQL

The following queries should work if you copy-paste them into our GraphQL sandbox. For more information on how to use the GraphQL API, check out our GraphQL guide.

Find a Project

Search for projects by name:

Python

query = """
SELECT
  project_id,
  project_name,
  display_name
FROM projects_v1
WHERE lower(display_name) LIKE lower('%merkle%')
"""
df = client.to_pandas(query)

GraphQL

query FindProject {
  oso_projectsV1(where: { displayName: { _ilike: "%merkle%" } }) {
    projectId
    projectName
    displayName
  }
}

Find a Project by Artifact

Find projects associated with specific artifacts:

Python

query = """
SELECT
  project_id,
  project_name,
  artifact_namespace as github_owner,
  artifact_name as github_repo
FROM artifacts_by_project_v1
WHERE
  artifact_source = 'GITHUB'
  AND artifact_namespace LIKE '%uniswap%'
"""
df = client.to_pandas(query)

GraphQL

query FindProjectByArtifact {
  oso_artifactsByProjectV1(
    where: {
      artifactNamespace: { _ilike: "%uniswap%" }
      artifactSource: { _eq: "GITHUB" }
    }
  ) {
    projectId
    projectName
    artifactNamespace
    artifactName
  }
}

Code Metrics

Get code metrics for a specific project:

Python

query = """
SELECT
  tm.sample_date,
  m.metric_name,
  tm.amount
FROM timeseries_metrics_by_project_v0 AS tm
JOIN metrics_v0 AS m
  ON tm.metric_id = m.metric_id
JOIN projects_v1 AS p
  ON tm.project_id = p.project_id
WHERE 
  p.project_name = 'opensource-observer'
  AND m.metric_name IN (
    'GITHUB_stars_daily',
    'GITHUB_forks_daily',
    'GITHUB_commits_daily',
    'GITHUB_contributors_daily'
  )
ORDER BY tm.sample_date DESC
"""
df = client.to_pandas(query)

GraphQL

query GetProjectAndMetricIds($projectName: String!) {
  oso_projectsV1(where: { projectName: { _eq: $projectName } }) {
    projectId
  }
  oso_metricsV0(where: { metricName: { _in: [
    "GITHUB_stars_daily",
    "GITHUB_forks_daily",
    "GITHUB_commits_daily",
    "GITHUB_contributors_daily"
  ] } }) {
    metricId
    metricName
  }
}

Variables:

{
  "projectName": "opensource-observer"
}

And then get the timeseries data:

query GetProjectTimeseriesMetrics($projectId: String!) {
  oso_timeseriesMetricsByProjectV0(
    where: {
      projectId: { _eq: $projectId }
      metricId: { _in: $metricIds }
    }
    order_by: { sampleDate: Desc }
  ) {
    sampleDate
    metricId
    amount
  }
}

Using the IDs from the previous query:

{
  "projectId": "UuWbpo5bpL5QsYvlukUWNm2uE8HFjxQxzCM0e+HMZfk=",
  "metricIds": [
    "eV94RLJgcpOd+aMt8Y0sYGyN4V+6CCSwuxyZC7B1/FE=",
    "8oVBt/WidET++OTvxowXmzJRSYVgXHhRQPB0R/JXIa0=",
    "0xy+em6XN6wQKZMqtspcmc49ze3hD4BofTyMG+PU2OE=",
    "4RMwikzLmSG2bwtW+MEFGwIVk7/IjFftTPZ9rU3Isr4="
  ]
}

Timeseries Metrics

Get historical metrics for a project:

Python

query = """
SELECT
  tm.sample_date,
  m.metric_name,
  tm.amount
FROM timeseries_metrics_by_project_v0 AS tm
JOIN metrics_v0 AS m
  ON tm.metric_id = m.metric_id
JOIN projects_v1 AS p
  ON tm.project_id = p.project_id
WHERE p.project_name = 'wevm'
ORDER BY sample_date DESC
"""
df = client.to_pandas(query)

GraphQL

query GetProjectAndMetricIds($projectName: String!) {
  oso_projectsV1(where: { projectName: { _eq: $projectName } }) {
    projectId
  }
  oso_metricsV0 {
    metricId
    metricName
  }
}

Variables:

{
  "projectName": "wevm"
}

And then get the timeseries data:

query GetProjectTimeseriesMetrics($projectId: String!) {
  oso_timeseriesMetricsByProjectV0(
    where: {
      projectId: { _eq: $projectId }
    }
    order_by: { sampleDate: Desc }
  ) {
    sampleDate
    metricId
    amount
  }
}

Using the project ID from the previous query:

{
  "projectId": "iFwvhinW6hRuD/1dIGR7QqYwJTFdfgyLFhWW5Lhp/j4="
}

Repository Snapshot

Get a snapshot of a project's GitHub repositories:

Python

query = """
SELECT
    r.artifact_url,
    r.star_count,
    r.fork_count,
    r.license_name,
    r.language
FROM repositories_v0 AS r
JOIN projects_v1 AS p
  ON r.project_id = p.project_id
WHERE
  p.project_name = 'wevm'
ORDER BY r.star_count DESC
"""
df = client.to_pandas(query)

GraphQL

query GetProjectRepositories($artifactNamespace: String!) {
  oso_repositoriesV0(
    where: { 
      artifactNamespace: { _eq: $artifactNamespace }
    }
    order_by: { starCount: Desc }
  ) {
    artifactUrl
    starCount
    forkCount
    licenseName
    language
  }
}

Variables:

{
  "artifactNamespace": "wevm"
}

Adding Projects

Projects are defined as YAML files in our OSS Directory repo. You can add or update your own projects or project artifacts by submitting a pull request.

For more information on how projects work, see our guide here.